Class Document

Adds a Bookmark at the given 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());

}

Parameters

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

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

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

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

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

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

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

Adds a document footer section, if none exists.

// 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 footer to the document.
const footer = doc.addFooter();

// Sets the footer text to 'This is a footer.'
footer.setText('This is a footer');

Return

FooterSection — The document footer.

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

Adds a document header section, if none exists.

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

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

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

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

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

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

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

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

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

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

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

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

Parameters

Return

Blob — The current document as a blob.

Retrieves the current Document contents as a 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());

Return

Blob — The current document as a blob.

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.

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

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

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

// 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.');
}

Parameters

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

Gets all Bookmark objects in the document.

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

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

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

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

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

// 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 footer and logs it to the console.
console.log(doc.getFooter().getText());

Return

FooterSection — The document footer.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sets the document title.

Parameters

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

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

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