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（直接或通过子元素链）。
getSurroundingTextOffset()Integer获取此 Position 在 getSurroundingText() 返回的 Text 元素中的偏移量。
insertBookmark()Bookmark在此 Position 处创建并插入新的 Bookmark。
insertInlineImage(image)InlineImage基于指定图片在此 Position 处创建并插入新的 InlineImage blob。
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（直接或通过子元素链）。如需确定 Position 在返回的 Text 元素中的偏移量，请使用 getSurroundingTextOffset()。

返回

Text - 相当于调用 editAsText() 结果的元素 在包含 Position 的 Paragraph 或 ListItem 上（直接或通过子元素链）

授权

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

  • 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)

基于指定图像在此 Position 处创建并插入新的 InlineImage blob。

参数

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

返回

InlineImage - 新的图片元素，或者 null（如果此 Position 所在的元素） 不允许插入图片

授权

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

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

insertText(text)

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

参数

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

返回

Text - 新的文本元素，或者 null（如果此 Position 所在的元素） 不允许插入文字

授权

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

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