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在 getSurroundingText() 傳回的 Text 元素中，取得這個 Position 的偏移值。
insertBookmark()Bookmark在這個 Position 建立及插入新的 Bookmark。
insertInlineImage(image)InlineImage在這個 Position 從指定的圖片 blob 建立及插入新的 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)

在這個 Position 從指定的圖片 blob 建立及插入新的 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