Class Position

位置

对文档标签页中相对于特定元素的位置的引用。用户的光标以 Position 表示，除此之外还有其他用途。脚本只能访问运行脚本的用户的光标，并且只有在脚本绑定到文档的情况下才能访问。 

// Insert some text at the cursor position and make it bold.
const cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns
  // null, the cursor's containing element doesn't allow insertions, so show the
  // user an error message.
  const element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}

方法

方法返回类型简介
getElement()Element获取包含此 Position 的元素。
getOffset()Integer获取此 Position 在包含它的元素中的相对位置。
getSurroundingText()Text创建一个人工 Text 元素，用于直接或通过一连串子元素表示包含 Position 的 Paragraph 或 ListItem 的文本和格式。
getSurroundingTextOffset()Integer获取 getSurroundingText() 返回的 Text 元素中此 Position 的偏移量。
insertBookmark()Bookmark在此 Position 中创建并插入新的 Bookmark。
insertInlineImage(image)InlineImage从指定的图片 blob 中创建并在此 Position 中插入新的 InlineImage。
insertText(text)Text在此 Position 中插入指定文本。

详细文档

getElement()

获取包含此 Position 的元素。这将是 Text 元素或 Paragraph 等容器元素。无论是哪种情况，都可以使用 getOffset() 确定元素内的相对位置。

返回

Element - 此 Position 对象所在的容器或 Text 元素

getOffset()

获取此 Position 在包含它的元素中的相对位置。如果元素是 Text 元素，则偏移量为 Position 之前的字符数（即此 Position 后面的字符的索引）；对于任何其他元素，偏移量为同一容器元素中此 Position 之前的子元素数（即此 Position 后面的子元素的索引）。

返回

Integer - 对于 Text 元素，是此 Position 之前的字符数；对于其他元素，是同一容器元素中此 Position 之前的子元素数

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getSurroundingText()

创建一个人工 Text 元素，用于直接或通过一连串子元素表示包含 Position 的 Paragraph 或 ListItem 的文本和格式。如需确定返回的 Text 元素中的 Position 偏移量，请使用 getSurroundingTextOffset()。

返回

Text - 一个元素，相当于直接或通过子元素链对包含 Position 的 Paragraph 或 ListItem 调用 editAsText() 的结果

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getSurroundingTextOffset()

获取 getSurroundingText() 返回的 Text 元素中此 Position 的偏移量。偏移量是 Position 前面的字符数（即此 Position 后面的字符的索引）。

返回

Integer - 包含 Position 的 Paragraph 或 ListItem（直接或通过一连串子元素）中此 Position 前面的字符数

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertBookmark()

在此 Position 中创建并插入新的 Bookmark。

返回

Bookmark - 新书签

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertInlineImage(image)

从指定的图片 blob 中创建并在此 Position 中插入新的 InlineImage。

参数

名称类型说明
imageBlobSource要在此 Position 中插入的图片数据

返回

InlineImage - 新的图片元素；如果此 Position 所在的元素不允许插入图片，则为 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertText(text)

在此 Position 中插入指定文本。此方法会创建一个新的 Text 元素，即使字符串插入现有 Text 元素中也是如此，这样便于为新元素设置样式。

参数

名称类型说明
textString要在此 Position 中插入的字符串

返回

Text - 新文本元素；如果此 Position 所在的元素不允许插入文本，则为 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents