此页面由 Cloud Translation API 翻译。

Class DocumentTab

文档标签页，其中包含富文本和表格、列表等元素。

使用 Document.getTabs()[tabIndex].asDocumentTab() 检索文档标签页。

// Get a specific document tab based on the tab ID.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 在文档中是唯一的，就像 HTML 中的 ID 一样。添加 NamedRange 后，您无法对其进行修改，只能将其移除。

访问该标签页的任何脚本都可以访问 NamedRange。为避免脚本之间意外发生冲突，不妨考虑为范围名称添加唯一字符串前缀。

// Creates a named range that includes every table in a tab by its ID.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let 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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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；如果标签页中不存在此类 Bookmark，则返回 null。

授权

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

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

`getBookmarks()`

获取标签页中的所有 Bookmark 对象。

// Opens the Docs file and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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 and retrieves the tab by its IDs. If you created your
// script from within a Google Docs file, you can use
// DocumentApp.getActiveDocument().getActiveTab() instead.
// TODO(developer): Replace the IDs with your own.
const documentTab =
    DocumentApp.openById('123abc').getTab('123abc').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。如果标签页中不存在此类 NamedRange，此方法会返回 null。名称不一定是唯一的，即使在不同标签页中也是如此；同一文档中的多个不同范围可以共用相同的名称，就像 HTML 中的类一样。相比之下，ID 在标签页中是唯一的，就像 HTML 中的 ID 一样。

参数

名称	类型	说明
`id`	`String`	范围的 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 中的 ID 一样。

任何访问该标签页的脚本都可以访问 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.
// TODO(developer): Replace the IDs with your own.
const doc = DocumentApp.openById('123abc');
const documentTab = doc.getTab('123abc').asDocumentTab();
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
const 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.
// TODO(developer): Replace the IDs with your own.
const doc = DocumentApp.openById('123abc');
const documentTab = doc.getTab('123abc').asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let 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