A document, containing rich text and elements such as tables and lists.
Documents may be opened or created using DocumentApp
.
// Open a document by ID. var doc = DocumentApp.openById("<my-id>"); // Create and open a document. doc = DocumentApp.create("Document Title");
Methods
Method | Return type | Brief description |
---|---|---|
addBookmark(position) | Bookmark | Adds a Bookmark at the given Position . |
addEditor(emailAddress) | Document | Adds the given user to the list of editors for the Document . |
addEditor(user) | Document | Adds the given user to the list of editors for the Document . |
addEditors(emailAddresses) | Document | Adds the given array of users to the list of editors for the Document . |
addFooter() | FooterSection | Adds a document footer section, if none exists. |
addHeader() | HeaderSection | Adds a document header section, if none exists. |
addNamedRange(name, range) | NamedRange | Adds a NamedRange , which is a Range that has a name and ID to use for
later retrieval. |
addViewer(emailAddress) | Document | Adds the given user to the list of viewers for the Document . |
addViewer(user) | Document | Adds the given user to the list of viewers for the Document . |
addViewers(emailAddresses) | Document | Adds the given array of users to the list of viewers for the Document . |
getAs(contentType) | Blob | Retrieves the current Document contents as a blob of the specified type. |
getBlob() | Blob | Retrieves the current Document contents as a blob. |
getBody() | Body | Retrieves the active document's Body . |
getBookmark(id) | Bookmark | Gets the Bookmark with the given ID. |
getBookmarks() | Bookmark[] | Gets all Bookmark objects in the document. |
getCursor() | Position | Gets the user's cursor in the active document. |
getEditors() | User[] | Gets the list of editors for this Document . |
getFooter() | FooterSection | Retrieves the document's footer section, if one exists. |
getFootnotes() | Footnote[] | Retrieves all the Footnote elements in the document body. |
getHeader() | HeaderSection | Retrieves the document's header section, if one exists. |
getId() | String | Retrieves the document's unique identifier. |
getLanguage() | String | Gets the document's language code. |
getName() | String | Retrieves the title of the document. |
getNamedRangeById(id) | NamedRange | Gets the NamedRange with the given ID. |
getNamedRanges() | NamedRange[] | Gets all NamedRange objects in the document. |
getNamedRanges(name) | NamedRange[] | Gets all NamedRange objects in the document with the given name. |
getSelection() | Range | Gets the user's selection in the active document. |
getSupportedLanguageCodes() | String[] | Gets all language codes that are supported in Google Docs files. |
getUrl() | String | Retrieves the URL to access the current document. |
getViewers() | User[] | Gets the list of viewers and commenters for this Document . |
newPosition(element, offset) | Position | Creates a new Position , which is a reference to a location in the document, relative to
a specific element. |
newRange() | RangeBuilder | Creates a builder used to construct Range objects from document elements. |
removeEditor(emailAddress) | Document | Removes the given user from the list of editors for the Document . |
removeEditor(user) | Document | Removes the given user from the list of editors for the Document . |
removeViewer(emailAddress) | Document | Removes the given user from the list of viewers and commenters for the Document . |
removeViewer(user) | Document | Removes the given user from the list of viewers and commenters for the Document . |
saveAndClose() | void | Saves the current Document . |
setCursor(position) | Document | Sets the user's cursor in the active document, given a Position . |
setLanguage(languageCode) | Document | Sets the document's language code. |
setName(name) | Document | Sets the document title. |
setSelection(range) | Document | Sets the user's selection in the active document, given a Range . |
Detailed documentation
addBookmark(position)
Adds a Bookmark
at the given Position
.
Parameters
Name | Type | Description |
---|---|---|
position | Position | the position of the new bookmark |
Return
Bookmark
— the new bookmark
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addEditor(emailAddress)
Adds the given user to the list of editors for the Document
. If the user was already
on the list of viewers, this method promotes the user out of the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addEditor(user)
Adds the given user to the list of editors for the Document
. If the user was already
on the list of viewers, this method promotes the user out of the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addEditors(emailAddresses)
Adds the given array of users to the list of editors for the Document
. If any of the
users were already on the list of viewers, this method promotes them out of the list of
viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddresses | String[] | An array of email addresses of the users to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addHeader()
Adds a document header section, if none exists.
Return
HeaderSection
— the document header
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addNamedRange(name, range)
Adds a NamedRange
, which is a Range
that has a name and ID to use for
later retrieval. Names aren't necessarily unique; several different ranges in the same document
can share the same name, much like a class in HTML. By contrast, IDs are unique within the
document, like an ID in HTML. After you add a NamedRange
to a document, you can't
modify it, you can only remove it.
Any script that accesses the document can access a NamedRange
. To avoid unintended
conflicts between scripts, consider prefixing range names with a unique string.
// 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());
Parameters
Name | Type | Description |
---|---|---|
name | String | The name for the range, which doesn't need to be unique; range names must be between 1-256 characters. |
range | Range | The range of elements to associate with the name; the range can be the active selection, a search result, or manually constructed with newRange() . |
Return
NamedRange
— The NamedRange
.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addViewer(emailAddress)
Adds the given user to the list of viewers for the Document
. If the user was already
on the list of editors, this method has no effect.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addViewer(user)
Adds the given user to the list of viewers for the Document
. If the user was already
on the list of editors, this method has no effect.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
addViewers(emailAddresses)
Adds the given array of users to the list of viewers for the Document
. If any of the
users were already on the list of editors, this method has no effect for them.
Parameters
Name | Type | Description |
---|---|---|
emailAddresses | String[] | An array of email addresses of the users to add. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getAs(contentType)
Retrieves the current Document
contents as a blob of the specified type.
Parameters
Name | Type | Description |
---|---|---|
contentType | String | the MIME type to convert to; currently only 'application/pdf' is
supported |
Return
Blob
— the current document as a blob
getBlob()
getBody()
Retrieves the active document's Body
.
Documents may contain different types of sections (e.g. HeaderSection
, FooterSection
). The active section for a document is the Body
.
Element methods in Document
delegate to the active Body
.
Return
Body
— the active document body section
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getBookmark(id)
Gets the Bookmark
with the given ID. This method returns null
if no such Bookmark
exists.
Parameters
Name | Type | Description |
---|---|---|
id | String | the ID for the Bookmark |
Return
Bookmark
— the Bookmark
with the given ID, or null
if no such Bookmark
exists
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getBookmarks()
Gets all Bookmark
objects in the document.
Return
Bookmark[]
— an array of the Bookmark
objects in the document
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getCursor()
Gets the user's cursor in the active document. A script can only access the cursor of the user who is running the script, and only if the script is bound to the document.
// 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.'); }
Return
Position
— A representation of the user's cursor, or null
if the user does not have a
cursor placed in the document or if the script is not bound to the document.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getEditors()
Gets the list of editors for this Document
.
Return
User[]
— An array of users with edit permission.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getFootnotes()
Retrieves all the Footnote
elements in the document body.
Calls to getFootnotes
cause an iteration over the document's elements. For large
documents, avoid unnecessary calls to this method.
Return
Footnote[]
— the document footnotes
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getHeader()
Retrieves the document's header section, if one exists.
Return
HeaderSection
— the document header
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getId()
Retrieves the document's unique identifier. The document ID is used with DocumentApp.openById()
to open a specific document instance.
Return
String
— the document's ID
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getLanguage()
Gets the document's language code. This is the language shown in the document editor's File > Language, which may not be the actual language that the document contains.
Return
String
— The document language, or null
if not defined.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getName()
Retrieves the title of the document.
Return
String
— the document title
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getNamedRangeById(id)
Gets the NamedRange
with the given ID. This method returns null
if no such
NamedRange
exists. Names are not necessarily unique; several different ranges in the
same document may share the same name, much like a class in HTML. By contrast, IDs are unique
within the document, like an ID in HTML.
Parameters
Name | Type | Description |
---|---|---|
id | String | the range's ID, which is unique within the document |
Return
NamedRange
— the NamedRange
with the given ID, or null
if no such range exists
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getNamedRanges()
Gets all NamedRange
objects in the document.
A NamedRange
can be accessed by any script that accesses the document. To avoid
unintended conflicts between scripts, consider prefixing range names with a unique string.
Return
NamedRange[]
— an array of the NamedRange
objects in the document, possibly including multiple
ranges with the same name
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getNamedRanges(name)
Gets all NamedRange
objects in the document with the given name. Names are not
necessarily unique; several different ranges in the same document may share the same name, much
like a class in HTML. By contrast, IDs are unique within the document, like an ID in HTML.
A NamedRange
can be accessed by any script that accesses the document. To avoid
unintended conflicts between scripts, consider prefixing range names with a unique string.
Parameters
Name | Type | Description |
---|---|---|
name | String | the range's name, which is not necessarily unique |
Return
NamedRange[]
— an array of the NamedRange
objects in the document with the given name
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getSelection()
Gets the user's selection in the active document. A script can only access the selection of the user who is running the script, and only if the script is bound to the document.
// 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.'); }
Return
Range
— A representation of the user's selection, or null
if the user does not have
anything selected in the document, if only the end of a paragraph is selected, if only the
end of a paragraph and a new line are selected, or if the script is not bound to the
document.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getSupportedLanguageCodes()
Gets all language codes that are supported in Google Docs files.
Return
String[]
— An array of language codes.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getUrl()
Retrieves the URL to access the current document.
var doc = DocumentApp.getActiveDocument(); // Send out the link to open the document. MailApp.sendEmail("<email-address>", doc.getName(), doc.getUrl());
Return
String
— the URL to access the current document
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getViewers()
Gets the list of viewers and commenters for this Document
.
Return
User[]
— An array of users with view or comment permission.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
newPosition(element, offset)
Creates a new Position
, which is a reference to a location in the document, relative to
a specific element. The user's cursor is represented as a Position
, among other uses.
// 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);
Parameters
Name | Type | Description |
---|---|---|
element | Element | the element that will contain the new Position ; this must be either a
Text element or a container element like Paragraph |
offset | Integer | for Text elements, the number of characters before the Position ;
for other elements, the number of child elements before the Position within the
same container element |
Return
Position
— the new Position
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
newRange()
Creates a builder used to construct Range
objects from document elements.
// 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());
Return
RangeBuilder
— the new builder
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeEditor(emailAddress)
Removes the given user from the list of editors for the Document
. This method doesn't
block users from accessing the Document
if they belong to a class of users who have
general access—for example, if the Document
is shared with the user's entire
domain, or if the Document
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to remove. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeEditor(user)
Removes the given user from the list of editors for the Document
. This method doesn't
block users from accessing the Document
if they belong to a class of users who have
general access—for example, if the Document
is shared with the user's entire
domain, or if the Document
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to remove. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(emailAddress)
Removes the given user from the list of viewers and commenters for the Document
. This
method has no effect if the user is an editor, not a viewer or commenter. This method also
doesn't block users from accessing the Document
if they belong to a class of users who
have general access—for example, if the Document
is shared with the user's
entire domain, or if the Document
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of editors.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to remove. |
Return
Document
— This Document
for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(user)
Removes the given user from the list of viewers and commenters for the Document
. This
method has no effect if the user is an editor, not a viewer. This method also doesn't block
users from accessing the Document
if they belong to a class of users who have general
access—for example, if the Document
is shared with the user's entire domain, or
if the Document
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of editors.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to remove. |
Return
Document
— This Document
for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
saveAndClose()
Saves the current Document
. Causes pending updates to be flushed and applied.
The saveAndClose()
method is automatically invoked at the end of script execution
for each open editable Document
.
A closed Document
can't be edited. Use DocumentApp.openById()
to reopen a
given document for editing.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setCursor(position)
Sets the user's cursor in the active document, given a Position
. A script can only
access the cursor of the user who is running the script, and only if the script is bound to the document.
// 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);
Parameters
Name | Type | Description |
---|---|---|
position | Position | the new cursor location |
Return
Document
— this Document
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setLanguage(languageCode)
Sets the document's language code. This is the language shown in the document editor's File
> Language, which may not be the actual language that the document contains. Use getSupportedLanguageCodes()
to get all the valid language codes.
Parameters
Name | Type | Description |
---|---|---|
languageCode | String | The language code. |
Return
Document
— This Document
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setName(name)
Sets the document title.
Parameters
Name | Type | Description |
---|---|---|
name | String | the new document title |
Return
Document
— the current document
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setSelection(range)
Sets the user's selection in the active document, given a Range
. A script can
only access the selection of the user who is running the script, and only if the script is bound to the document.
// 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());
Parameters
Name | Type | Description |
---|---|---|
range | Range | the new range of elements to select |
Return
Document
— this Document
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents