Class DocumentTab

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());

参数

名称类型说明
positionPosition新书签的位置。

返回

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());

参数

名称类型说明
nameString范围的名称,无需具有唯一性;范围名称必须为 介于 1 到 256 个字符之间。
rangeRange与名称关联的元素范围;该范围可以是搜索结果,也可以使用 newRange() 手动构建。

返回

NamedRange - NamedRange

授权

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

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

getBody()

检索标签页的 Body

标签页可以包含不同类型的部分(例如 HeaderSectionFooterSection)。标签页的活动部分是 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.');
}

参数

名称类型说明
idStringBookmark 的 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 一样。

参数

名称类型说明
idString范围的 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。为避免 脚本之间可能会发生意外冲突,请考虑为范围名称添加唯一字符串作为前缀。

参数

名称类型说明
nameString范围的名称,不一定是唯一的。

返回

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);

参数

名称类型说明
elementElement包含新创建的 Position 的元素;此值必须为 可以是 Text 元素,也可以是容器元素(例如 Paragraph)。
offsetInteger对于 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