本頁面由 Cloud Translation API 翻譯而成。

Class DocumentTab

文件分頁，包含 RTF 格式和元素 (例如表格和清單)。

使用 Document.getTabs()[tabIndex].asDocumentTab() 擷取文件分頁。

// Get a specific document tab based on the tab ID.
var documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

方法

方法	傳回類型	簡短說明
`addBookmark(position)`	`Bookmark`	在指定的 `Position` 新增 `Bookmark`。
`addFooter()`	`FooterSection`	如果沒有任何分頁頁尾區段，則會新增分頁頁尾區段。
`addHeader()`	`HeaderSection`	如果不存在，就會新增分頁標頭區段。
`addNamedRange(name, range)`	`NamedRange`	新增 `NamedRange`，這是一個有名稱和 ID 的 `Range` 。
`getBody()`	`Body`	擷取分頁的 `Body`。
`getBookmark(id)`	`Bookmark`	取得具有指定 ID 的 `Bookmark`。
`getBookmarks()`	`Bookmark[]`	取得分頁中的所有 `Bookmark` 物件。
`getFooter()`	`FooterSection`	擷取分頁的頁尾區段 (如果有的話)。
`getFootnotes()`	`Footnote[]`	擷取分頁主體中的所有 `Footnote` 元素。
`getHeader()`	`HeaderSection`	擷取分頁標頭區段 (如果有的話)。
`getNamedRangeById(id)`	`NamedRange`	取得具有指定 ID 的 `NamedRange`。
`getNamedRanges()`	`NamedRange[]`	取得分頁中的所有 `NamedRange` 物件。
`getNamedRanges(name)`	`NamedRange[]`	取得分頁中具有特定名稱的所有 `NamedRange` 物件。
`newPosition(element, offset)`	`Position`	建立新的 `Position`，其參照分頁中位置的參照 (相對於特定元素
`newRange()`	`RangeBuilder`	建立可透過分頁元素建構 `Range` 物件的建構工具。

內容詳盡的說明文件

`addBookmark(position)`

在指定的 Position 新增 Bookmark。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the tab body and adds a paragraph.
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');

// Creates a position at the first character of the paragraph text.
const position = documentTab.newPosition(paragraph.getChild(0), 0);

// Adds a bookmark at the first character of the paragraph text.
const bookmark = documentTab.addBookmark(position);

// Logs the bookmark ID to the console.
console.log(bookmark.getId());

參數

名稱	類型	說明
`position`	`Position`	新書籤的位置。

回攻員

Bookmark：新的書籤。

授權

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

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

`addFooter()`

如果沒有任何分頁頁尾區段，則會新增分頁頁尾區段。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Adds a footer to the tab.
const footer = documentTab.addFooter();

// Sets the footer text to 'This is a footer.'
footer.setText('This is a footer');

回攻員

FooterSection：分頁頁尾。

授權

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

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

`addHeader()`

如果不存在，就會新增分頁標頭區段。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Adds a header to the tab.
const header = documentTab.addHeader();

// Sets the header text to 'This is a header.'
header.setText('This is a header');

回攻員

HeaderSection：分頁標頭。

授權

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

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

`addNamedRange(name, range)`

新增 NamedRange，這是一個有名稱和 ID 的 Range 。名稱不一定會重複 (即使是不同分頁中)。這個網路中的同一份文件可以共用相同名稱，就跟 HTML 中的類別很類似。相反地而非文件中的 ID新增 NamedRange 後，將無法修改，只能移除。

任何可存取分頁的指令碼都可以存取 NamedRange。避免無意間請考慮使用不重複的字串，在範圍名稱前面加上專屬字串。

// Creates a named range that includes every table in the tab with tab ID 't.0'.
var documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();
var rangeBuilder = documentTab.newRange();
var tables = documentTab.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
documentTab.addNamedRange('Tab t.0 tables', rangeBuilder.build());

參數

名稱	類型	說明
`name`	`String`	範圍名稱 (可以重複)。範圍名稱必須為長度介於 1 到 256 個字元之間。
`range`	`Range`	要與名稱建立關聯的元素範圍；範圍可以是搜尋結果，也可以使用 `newRange()` 手動建構。

回攻員

NamedRange - NamedRange。

授權

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

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

`getBody()`

擷取分頁的 Body。

分頁可以包含不同類型的版面 (例如 HeaderSection、FooterSection)。分頁的有效部分是 Body。

DocumentTab 中的元素方法會委派給 Body。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the tab body.
const body = documentTab.getBody();

// Gets the body text and logs it to the console.
console.log(body.getText());

回攻員

Body：分頁的「內文」部分。

授權

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

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

`getBookmark(id)`

取得具有指定 ID 的 Bookmark。如果這個分頁內沒有這類 Bookmark，這個方法會傳回 null。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the bookmark by its ID.
const bookmark = documentTab.getBookmark('id.xyz654321');

// If the bookmark exists within the tab, logs the character offset of its position to the
// console. Otherwise, logs 'No bookmark exists with the given ID.' to the console.
if (bookmark) {
  console.log(bookmark.getPosition().getOffset());
} else {
  console.log('No bookmark exists with the given ID.');
}

參數

名稱	類型	說明
`id`	`String`	`Bookmark` 的 ID。

回攻員

Bookmark — 具有指定 ID 的 Bookmark，如果不能，則nullBookmark 存在於分頁中

授權

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

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

`getBookmarks()`

取得分頁中的所有 Bookmark 物件。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets all of the bookmarks in the tab.
const bookmarks = documentTab.getBookmarks();

// Logs the number of bookmarks in the tab to the console.
console.log(bookmarks.length);

回攻員

Bookmark[] - 分頁中的 Bookmark 物件陣列。

授權

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

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

`getFooter()`

擷取分頁的頁尾區段 (如果有的話)。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the text of the tab's footer and logs it to the console.
console.log(documentTab.getFooter().getText());

回攻員

FooterSection：分頁的頁尾。

授權

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

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

`getFootnotes()`

擷取分頁主體中的所有 Footnote 元素。

呼叫 getFootnotes 會疊代分頁元素。如果是大型分頁避免對這個方法發出不必要的呼叫。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the first footnote.
const footnote = documentTab.getFootnotes()[0];

// Logs footnote contents to the console.
console.log(footnote.getFootnoteContents().getText());

回攻員

Footnote[]：分頁的註腳。

授權

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

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

`getHeader()`

擷取分頁標頭區段 (如果有的話)。

// Opens the Docs file by its ID and retrieves the tab with ID 't.0'. If you created your
// script from within a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the doc ID and the tab ID with your own.
const documentTab = DocumentApp.openById('abc123456').getTab('t.0').asDocumentTab();

// Gets the text of the tab's header and logs it to the console.
console.log(documentTab.getHeader().getText());

回攻員

HeaderSection：分頁的標頭。

授權

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

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

`getNamedRangeById(id)`

取得具有指定 ID 的 NamedRange。如果沒有，這個方法會傳回 null 分頁中有「NamedRange」名稱不一定會重複，即使是不同分頁中也是如此；同一份文件中多個不同的範圍的名稱可能會共用相同的名稱，這就像 HTML。相反地，此分頁中的 ID 不可重複，例如 HTML 中的 ID。

參數

名稱	類型	說明
`id`	`String`	範圍 ID (分頁中為專屬 ID)。

回攻員

NamedRange：具有指定 ID 的 NamedRange；如果沒有這個範圍，則傳回 null 標籤。

授權

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

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

`getNamedRanges()`

取得分頁中的所有 NamedRange 物件。

存取分頁的任何指令碼都可以存取 NamedRange。為了避免指令碼之間意外發生衝突，建議您使用不重複的字串為範圍名稱命名。

回攻員

NamedRange[]：分頁中的 NamedRange 物件陣列，可能包含多個名稱相同的範圍

授權

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

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

`getNamedRanges(name)`

取得分頁中具有特定名稱的所有 NamedRange 物件。名稱不一定同一文件中有多個不同的範圍名稱就類似於 HTML 中的類別相反地，分頁中的 ID 不可重複，在 HTML。

存取分頁的任何指令碼都可以存取 NamedRange。為了避免指令碼之間意外發生衝突，建議您使用不重複的字串為範圍名稱命名。

參數

名稱	類型	說明
`name`	`String`	範圍名稱 (不一定是唯一值)。

回攻員

NamedRange[] — 分頁標籤中具有特定名稱的 NamedRange 物件陣列。

授權

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

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

`newPosition(element, offset)`

建立新的 Position，其參照分頁中位置的參照 (相對於特定元素使用者的遊標以 Position 表示和其他用途。

// Append a paragraph, then place the user's cursor after the first word of the new paragraph.
var doc = DocumentApp.openById('abc123456');
var documentTab = doc.getTab('t.0').asDocumentTab();
var paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
var position = documentTab.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

參數

名稱	類型	說明
`element`	`Element`	要加入新建立 `Position` 的元素，這必須是 `Text` 元素或 `Paragraph` 等容器元素。
`offset`	`Integer`	如果是 `Text` 元素，則 `Position` 前方的字元數；如果是其他元素，則事件中 `Position` 之前的子元素數量相同容器元素

回攻員

Position：新的 Position。

授權

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

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

`newRange()`

建立可透過分頁元素建構 Range 物件的建構工具。

// Change the user's selection to a range that includes every table in the tab.
var doc = DocumentApp.openById('abc123456');
var documentTab = doc.getTab('t.0').asDocumentTab();
var rangeBuilder = documentTab.newRange();
var tables = documentTab.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

回攻員

RangeBuilder：新的建構工具。

授權

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

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