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获取此 Position 在 getSurroundingText() 返回的 Text 元素中的偏移量。
insertBookmark()Bookmark在此 Position 处创建并插入新的 Bookmark。
insertInlineImage(image)InlineImage|null根据指定的图片 blob 在此 Position 处创建并插入新的 InlineImage。
insertText(text)Text|null在此 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()

获取此 Position 在 getSurroundingText() 返回的 Text 元素中的偏移量。偏移量是指 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|null - 新的图片元素，或者如果此 Position 所在的元素不允许插入图片，则为 null

授权

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

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

insertText(text)

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

参数

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

返回

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

授权

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

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