Google Apps Script

Class Document

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

MethodReturn typeBrief description
addBookmark(position)BookmarkAdds a Bookmark at the given Position.
addEditor(emailAddress)DocumentAdds the given user to the list of editors for the Document.
addEditor(user)DocumentAdds the given user to the list of editors for the Document.
addEditors(emailAddresses)DocumentAdds the given array of users to the list of editors for the Document.
addFooter()FooterSectionAdds a document footer section, if none exists.
addHeader()HeaderSectionAdds a document header section, if none exists.
addNamedRange(name, range)NamedRangeAdds a new NamedRange, which is a Range that has a name and ID to allow later retrieval.
addViewer(emailAddress)DocumentAdds the given user to the list of viewers for the Document.
addViewer(user)DocumentAdds the given user to the list of viewers for the Document.
addViewers(emailAddresses)DocumentAdds the given array of users to the list of viewers for the Document.
getAs(contentType)BlobRetrieves the current Document contents as a blob of the specified type.
getBlob()BlobRetrieves the current Document contents as a blob.
getBody()BodyRetrieves the active document's Body.
getBookmark(id)BookmarkGets the Bookmark with the given ID.
getBookmarks()Bookmark[]Gets all Bookmark objects in the document.
getCursor()PositionGets the user's cursor in the active document.
getEditors()User[]Gets the list of editors for this Document.
getFooter()FooterSectionRetrieves the document's footer section, if one exists.
getFootnotes()Footnote[]Retrieves all the Footnote elements in the document body.
getHeader()HeaderSectionRetrieves the document's header section, if one exists.
getId()StringRetrieves the document's unique identifier.
getName()StringRetrieves the title of the document.
getNamedRangeById(id)NamedRangeGets 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()RangeGets the user's selection in the active document.
getUrl()StringRetrieves the URL to access the current document.
getViewers()User[]Gets the list of viewers and commenters for this Document.
newPosition(element, offset)PositionCreates a new Position, which is a reference to a location in the document, relative to a specific element.
newRange()RangeBuilderCreates a builder used to construct Range objects from document elements.
removeEditor(emailAddress)DocumentRemoves the given user from the list of editors for the Document.
removeEditor(user)DocumentRemoves the given user from the list of editors for the Document.
removeViewer(emailAddress)DocumentRemoves the given user from the list of viewers and commenters for the Document.
removeViewer(user)DocumentRemoves the given user from the list of viewers and commenters for the Document.
saveAndClose()voidSaves the current Document.
setCursor(position)DocumentSets the user's cursor in the active document, given a Position.
setName(name)DocumentSets the document title.
setSelection(range)DocumentSets the user's selection in the active document, given a Range.

Detailed documentation

addBookmark(position)

Adds a Bookmark at the given Position.

Parameters

NameTypeDescription
positionPositionthe position of the new bookmark

Return

Bookmark — the new bookmark


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

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

Document — this Document, for chaining


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

NameTypeDescription
userUsera representation of the user to add

Return

Document — this Document, for chaining


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

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

Document — this Document, for chaining


addFooter()

Adds a document footer section, if none exists.

Return

FooterSection — the document footer


addHeader()

Adds a document header section, if none exists.

Return

HeaderSection — the document header


addNamedRange(name, range)

Adds a new NamedRange, which is a Range that has a name and ID to allow later retrieval. 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. Once a NamedRange has been added to a document, it cannot be modified, only removed.

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.

// 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

NameTypeDescription
nameStringthe name for the range, which does not need to be unique; range names must be at least 1 character, and no more than 256 characters
rangeRangethe 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 new NamedRange


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

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

Document — this Document, for chaining


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

NameTypeDescription
userUsera representation of the user to add

Return

Document — this Document, for chaining


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

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

Document — this Document, for chaining


getAs(contentType)

Retrieves the current Document contents as a blob of the specified type.

Parameters

NameTypeDescription
contentTypeStringthe MIME type to convert to; currently only 'application/pdf' is supported

Return

Blob — the current document as a blob


getBlob()

Retrieves the current Document contents as a blob.

Return

Blob — the current document as a blob


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


getBookmark(id)

Gets the Bookmark with the given ID. This method returns null if no such Bookmark exists.

Parameters

NameTypeDescription
idStringthe ID for the Bookmark

Return

Bookmark — the Bookmark with the given ID, or null if no such Bookmark exists


getBookmarks()

Gets all Bookmark objects in the document.

Return

Bookmark[] — an array of the Bookmark objects in the document


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


getEditors()

Gets the list of editors for this Document. If the user who executes the script does not have edit access to the Document, this method throws an exception.

Return

User[] — an array of users with edit permission


getFooter()

Retrieves the document's footer section, if one exists.

Return

FooterSection — the document footer


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


getHeader()

Retrieves the document's header section, if one exists.

Return

HeaderSection — the document header


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


getName()

Retrieves the title of the document.

Return

String — the document title


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

NameTypeDescription
idStringthe range's ID, which is unique within the document

Return

NamedRange — the NamedRange with the given ID, or null if no such range exists


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


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

NameTypeDescription
nameStringthe range's name, which is not necessarily unique

Return

NamedRange[] — an array of the NamedRange objects in the document with the given name


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 or if the script is not bound to the document


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


getViewers()

Gets the list of viewers and commenters for this Document. If the user who executes the script does not have edit access to the Document, this method throws an exception.

Return

User[] — an array of users with view or comment permission


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

NameTypeDescription
elementElementthe element that will contain the new Position; this must be either a Text element or a container element like Paragraph
offsetIntegerfor 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


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


removeEditor(emailAddress)

Removes the given user from the list of editors for the Document. This method does not 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.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

Document — this Document, for chaining


removeEditor(user)

Removes the given user from the list of editors for the Document. This method does not 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.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

Document — this Document, for chaining


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 does not 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.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

Document — this Document for chaining


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 does not 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.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

Document — this Document for chaining


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 Document.

A closed Document cannot be edited. Use DocumentApp.openById() to reopen a given document for editing.


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

NameTypeDescription
positionPositionthe new cursor location

Return

Document — this Document, for chaining


setName(name)

Sets the document title.

Parameters

NameTypeDescription
nameStringthe new document title

Return

Document — the current document


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

NameTypeDescription
rangeRangethe new range of elements to select

Return

Document — this Document, for chaining

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.