一种包含文本和元素(例如表格和列表)的文档。
您可以使用 DocumentApp
打开或创建文档。
// Open a document by ID. var doc = DocumentApp.openById("<my-id>"); // Create and open a document. doc = DocumentApp.create("Document Title");
方法
详细文档
addBookmark(position)
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the document body and adds a paragraph. const paragraph = doc.getBody().appendParagraph('My new paragraph.'); // Creates a position at the first character of the paragraph text. const position = doc.newPosition(paragraph.getChild(0), 0); // Adds a bookmark at the first character of the paragraph text. const bookmark = doc.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
addEditor(emailAddress)
addEditor(user)
addEditors(emailAddresses)
addHeader()
添加文档标头部分(如果不存在)。
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Adds a header to the document. const header = doc.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 the document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.getBody().getTables(); for (var i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } doc.addNamedRange('Document 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
addViewer(emailAddress)
addViewer(user)
addViewers(emailAddresses)
getAs(contentType)
检索当前 Document
内容作为指定类型的 blob。
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the document as a PDF. const pdf = doc.getAs('application/pdf'); // Logs the name of the PDF to the console. console.log(pdf.getName());
参数
名称 | 类型 | 说明 |
---|---|---|
contentType | String | 要转换为的 MIME 类型;目前仅支持 'application/pdf' 。 |
返程
Blob
- 当前文档为 blob。
getBlob()
将当前 Document
内容检索为 blob。
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Retrieves the current document's contents as a blob and logs it to the console. console.log(doc.getBlob().getContentType());
返程
Blob
- 当前文档为 blob。
getBody()
检索活跃文档的 Body
。
文档可能包含不同类型的版块(例如 HeaderSection
、FooterSection
)。文档的有效版块为 Body
。
Document
中的元素方法会委托给活跃的 Body
。
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the document body. const body = doc.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. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the bookmark by its ID. const bookmark = doc.getBookmark('id.xyz654321'); // If the bookmark exists, 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 by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. const doc = DocumentApp.openById('abc123456'); // Gets all of the bookmarks in the document. const bookmarks = doc.getBookmarks(); // Logs the number of bookmarks in the document to the console. console.log(bookmarks.length);
返程
Bookmark[]
- 文档中 Bookmark
对象的数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getCursor()
获取活动文档中用户的光标。脚本只能访问正在运行脚本的用户的光标,且仅当该脚本绑定到文档时才能执行。
// Insert some text at the cursor position and make it bold. var 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. var element = cursor.insertText('ಠ‿ಠ'); if (element) { element.setBold(true); } else { DocumentApp.getUi().alert('Cannot insert text here.'); } } else { DocumentApp.getUi().alert('Cannot find a cursor.'); }
返程
Position
- 用户光标的表示法,如果用户未在文档中放置光标,或者脚本未绑定到文档,则为 null
。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getEditors()
getFootnotes()
检索文档正文中的所有 Footnote
元素。
调用 getFootnotes
会导致对文档元素进行迭代。对于大型文档,请避免对该方法进行不必要的调用。
// Opens the Docs file by its ID. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the first footnote. const footnote = doc.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. If you created your script from within // a Google Docs file, you can use DocumentApp.getActiveDocument() instead. // TODO(developer): Replace the ID with your own. const doc = DocumentApp.openById('abc123456'); // Gets the text of the document's header and logs it to the console. console.log(doc.getHeader().getText());
返程
HeaderSection
- 文档标头。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getId()
检索文档的唯一标识符。文档 ID 与 DocumentApp.openById()
一起使用以打开特定文档实例。
返程
String
- 文档的 ID
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getLanguage()
获取文档的语言代码。这就是文档编辑器的 File > Language 中显示的语言,它可能并不是文档包含的实际语言。
返程
String
- 文档语言;如果未定义,则为 null
。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getName()
检索文档的标题。
返程
String
- 文档标题
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
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
getSelection()
获取用户在活跃文档中所做的选择。脚本只能访问正在运行脚本的用户的选择,而且仅当该脚本绑定到文档时才能执行。
// Display a dialog box that tells the user how many elements are included in the selection. var selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { var elements = selection.getRangeElements(); DocumentApp.getUi().alert('Number of selected elements: ' + elements.length); } else { DocumentApp.getUi().alert('Nothing is selected.'); }
返程
Range
- 表示用户所做选择,如果用户未在文档中选择任何内容,或者仅选择了段落末尾、选择了段落末尾和新行,或者脚本未绑定到文档,该值为 null
。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getSupportedLanguageCodes()
获取 Google 文档文件支持的所有语言代码。
返程
String[]
- 语言代码数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getUrl()
检索网址以访问当前文档。
var doc = DocumentApp.getActiveDocument(); // Send out the link to open the document. MailApp.sendEmail("<email-address>", doc.getName(), doc.getUrl());
返程
String
- 用于访问当前文档的网址
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getViewers()
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.getActiveDocument(); var paragraph = doc.getBody().appendParagraph('My new paragraph.'); var position = doc.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 document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.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
removeEditor(emailAddress)
从 Document
的编辑者列表中移除指定用户。如果用户属于拥有常规访问权限的一类用户(例如,用户的整个网域共享了 Document
,或者用户有权访问的 Document
位于共享云端硬盘中),则此方法不会阻止用户访问 Document
。
对于云端硬盘文件,此操作还会将用户从查看者列表中移除。
参数
名称 | 类型 | 说明 |
---|---|---|
emailAddress | String | 要移除的用户的电子邮件地址。 |
返程
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeEditor(user)
从 Document
的编辑者列表中移除指定用户。如果用户属于拥有常规访问权限的一类用户(例如,用户的整个网域共享了 Document
,或者用户有权访问的 Document
位于共享云端硬盘中),则此方法不会阻止用户访问 Document
。
对于云端硬盘文件,此操作还会将用户从查看者列表中移除。
参数
名称 | 类型 | 说明 |
---|---|---|
user | User | 表示要移除的用户。 |
返程
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(emailAddress)
从 Document
的查看者和评论者列表中移除指定用户。如果用户是编辑者,而不是查看者或评论者,则此方法不会产生任何影响。此外,如果用户属于一类具有常规访问权限的用户,例如用户与其整个网域共享的 Document
,或者 Document
位于用户有权访问的共享云端硬盘中,此方法也不会阻止用户访问 Document
。
对于云端硬盘文件,此操作还会将用户从编辑者列表中移除。
参数
名称 | 类型 | 说明 |
---|---|---|
emailAddress | String | 要移除的用户的电子邮件地址。 |
返程
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(user)
从 Document
的查看者和评论者列表中移除指定用户。如果用户是编辑者(而非查看者),则此方法不会产生任何影响。此外,如果用户属于一类具备常规访问权限的用户,例如用户与其整个网域共享的 Document
,或者 Document
位于用户有权访问的共享云端硬盘中,此方法也不会阻止用户访问 Document
。
对于云端硬盘文件,此操作还会将用户从编辑者列表中移除。
参数
名称 | 类型 | 说明 |
---|---|---|
user | User | 表示要移除的用户。 |
返程
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
saveAndClose()
保存当前的 Document
。会导致系统刷新并应用待处理的更新。
每个打开的可修改 Document
的脚本执行结束时,系统会自动调用 saveAndClose()
方法。
已停业的Document
无法修改。使用 DocumentApp.openById()
可重新打开给定文档进行编辑。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setCursor(position)
根据 Position
,在活动文档中设置用户的光标。脚本只能访问正在运行脚本的用户的光标,且仅当该脚本绑定到文档时才能执行。
// Append a paragraph, then place the user's cursor after the first word of the new paragraph. var doc = DocumentApp.getActiveDocument(); var paragraph = doc.getBody().appendParagraph('My new paragraph.'); var position = doc.newPosition(paragraph.getChild(0), 2); doc.setCursor(position);
参数
名称 | 类型 | 说明 |
---|---|---|
position | Position | 新光标位置 |
返程
Document
- 此 Document
,用于链接
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setLanguage(languageCode)
设置文档的语言代码。这就是文档编辑器的 File > Language 中显示的语言,它可能并不是文档包含的实际语言。使用 getSupportedLanguageCodes()
可获取所有有效的语言代码。
参数
名称 | 类型 | 说明 |
---|---|---|
languageCode | String | 语言代码。 |
返程
Document
- 此 Document
,用于链接。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setName(name)
setSelection(range)
根据 Range
,设置活跃文档中用户的选择。脚本只能访问正在运行脚本的用户的选择,而且仅当该脚本绑定到文档时才能访问。
// Change the user's selection to a range that includes every table in the document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.getBody().getTables(); for (var i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } doc.setSelection(rangeBuilder.build());
参数
名称 | 类型 | 说明 |
---|---|---|
range | Range | 要选择一组新的元素 |
返程
Document
- 此 Document
,用于链接
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents