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取得 getSurroundingText() 傳回的 Text 元素中此 Position 的偏移量。
insertBookmark()Bookmark在這個 Position 上建立並插入新的 Bookmark。
insertInlineImage(image)InlineImage從指定圖片 Blob 建立並插入新的 InlineImage 到這個 Position。
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：這個元素等同於在包含 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 建立並插入新的 InlineImage 到這個 Position。

參數

名稱類型說明
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