此页面由 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.
var documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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.
var documentTab = DocumentApp.openById(DOCUMENT_ID).getTab(TAB_ID).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 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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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(DOCUMENT_ID).getTab(TAB_ID).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，在该标签页中是唯一的。

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.
// TODO(developer): Replace the IDs with your own.
var doc = DocumentApp.openById(DOCUMENT_ID);
var documentTab = doc.getTab(TAB_ID).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.
// TODO(developer): Replace the IDs with your own.
var doc = DocumentApp.openById(DOCUMENT_ID);
var documentTab = doc.getTab(TAB_ID).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