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建立代表 Position 所含文字和格式的人工 Text 元素，無論是直接或透過一連串子項元素。ParagraphListItem
getSurroundingTextOffset()Integer取得 getSurroundingText() 傳回的 Text 元素中，這個 Position 的偏移。
insertBookmark()Bookmark建立並在這個 Position 插入新的 Bookmark。
insertInlineImage(image)InlineImage|null從指定的圖片 Blob，在這個 Position 建立並插入新的 InlineImage。
insertText(text)Text|null在 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()

建立代表 Position 所含文字和格式的人工 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)

從指定的圖片 Blob，在這個 Position 建立並插入新的 InlineImage。

參數

名稱類型說明
imageBlobSource要插入這個 Position 的圖片資料

回攻員

InlineImage|null：新的圖片元素；如果這個 Position 所在的元素不允許插入圖片，則為 null

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

insertText(text)

在 Position 插入指定文字。即使字串是插入現有的 Text 元素中，這個方法也會建立新的 Text 元素，方便您為新元素設定樣式。

參數

名稱類型說明
textString要插入這個 Position 的字串

回攻員

Text|null：新文字元素，或 null (如果 Position 所在的元素不允許插入文字)

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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