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 元素,用于表示 包含 PositionParagraphListItem(直接或通过子元素链)。
getSurroundingTextOffset()Integer获取此 PositiongetSurroundingText() 返回的 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 元素,用于表示 包含 PositionParagraphListItem(直接或通过子元素链)。如需确定 Position 在返回的 Text 元素中的偏移量,请使用 getSurroundingTextOffset()

返回

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

授权

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

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

getSurroundingTextOffset()

获取此 PositiongetSurroundingText() 返回的 Text 元素中的偏移量。偏移量是 Position 之前的字符数 (即,此 Position 之后的字符的索引)。

返回

Integer - 包含 PositionParagraphListItem 中此 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