Class Position

位置

对文档中某个位置的引用（相对于特定元素）。用户光标表示为 Position，以及其他一些用途。脚本只能访问运行脚本的用户的游标，且仅当脚本绑定到文档时才可访问。

// Insert some text at the cursor position and make it bold.
var 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.
  var 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 的文本和格式的人为 Text 元素。
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 元素。如需确定返回的 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