Google Apps Script

Class Text

An element representing a rich text region. All text in a Document is contained within Text elements. A Text element can be contained within an Equation, EquationFunction, ListItem, or Paragraph, but cannot itself contain any other element. For more information on document structure, see the guide to extending Google Docs.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Use editAsText to obtain a single text element containing
 // all the characters in the document.
 var text = body.editAsText();

 // Insert text at the beginning of the document.
 text.insertText(0, 'Inserted text.\n');

 // Insert text at the end of the document.
 text.appendText('\nAppended text.');

 // Make the first half of the document blue.
 text.setForegroundColor(0, text.getText().length / 2, '#00FFFF');
 

Methods

MethodReturn typeBrief description
appendText(text)TextAppends the specified text at the given character offset.
copy()TextReturns a detached, deep copy of the current element.
deleteText(startOffset, endOffsetInclusive)TextDeletes a range of text.
editAsText()TextObtains a Text version of the current element, for editing.
findText(searchPattern)RangeElementSearches the contents of the element for the specified text pattern using regular expressions.
findText(searchPattern, from)RangeElementSearches the contents of the element for the specified text pattern, starting from a given search result.
getAttributes()ObjectRetrieves the element's attributes.
getAttributes(offset)ObjectRetrieves the attributes at the specified character offset.
getBackgroundColor()StringRetrieves the background color setting.
getBackgroundColor(offset)StringRetrieves the background color at the specified character offset.
getFontFamily()FontFamilyRetrieves the font family setting.
getFontFamily(offset)FontFamilyRetrieves the font family at the specified character offset.
getFontSize()IntegerRetrieves the font size setting.
getFontSize(offset)IntegerRetrieves the font size at the specified character offset.
getForegroundColor()StringRetrieves the foreground color setting.
getForegroundColor(offset)StringRetrieves the foreground color at the specified character offset.
getLinkUrl()StringRetrieves the link url.
getLinkUrl(offset)StringRetrieves the link url at the specified character offset.
getNextSibling()ElementRetrieves the element's next sibling element.
getParent()ContainerElementRetrieves the element's parent element.
getPreviousSibling()ElementRetrieves the element's previous sibling element.
getText()StringRetrieves the contents of the element as a text string.
getTextAttributeIndices()Integer[]Retrieves the set of text indices that correspond to the start of distinct text formatting runs.
getType()ElementTypeRetrieves the element's ElementType.
insertText(offset, text)TextInserts the specified text at the given character offset.
isAtDocumentEnd()BooleanDetermines whether the element is at the end of the Document.
isBold()BooleanRetrieves the bold setting.
isBold(offset)BooleanRetrieves the bold setting at the specified character offset.
isItalic()BooleanRetrieves the italic setting.
isItalic(offset)BooleanRetrieves the italic setting at the specified character offset.
isStrikethrough()BooleanRetrieves the strikethrough setting.
isStrikethrough(offset)BooleanRetrieves the strikethrough setting at the specified character offset.
isUnderline()BooleanRetrieves the underline setting.
isUnderline(offset)BooleanRetrieves the underline setting at the specified character offset.
merge()TextMerges the element with the preceding sibling of the same type.
removeFromParent()TextRemoves the element from its parent.
replaceText(searchPattern, replacement)ElementReplaces all occurrences of a given text pattern with a given replacement string, using regular expressions.
setAttributes(startOffset, endOffsetInclusive, attributes)TextApplies the specified attributes to the given character range.
setAttributes(attributes)TextSets the element's attributes.
setBackgroundColor(startOffset, endOffsetInclusive, color)TextSets the background color for the specified character range.
setBackgroundColor(color)TextSets the background color.
setBold(bold)TextSets the bold setting.
setBold(startOffset, endOffsetInclusive, bold)TextSets the bold setting for the specified character range.
setFontFamily(family)TextSets the font family.
setFontFamily(startOffset, endOffsetInclusive, family)TextSets the font family for the specified character range.
setFontSize(size)TextSets the font size.
setFontSize(startOffset, endOffsetInclusive, size)TextSets the font size for the specified character range.
setForegroundColor(startOffset, endOffsetInclusive, color)TextSets the foreground color for the specified character range.
setForegroundColor(color)TextSets the foreground color.
setItalic(italic)TextSets the italic setting.
setItalic(startOffset, endOffsetInclusive, italic)TextSets the italic setting for the specified character range.
setLinkUrl(startOffset, endOffsetInclusive, url)TextSets the link url for the specified character range.
setLinkUrl(url)TextSets the link url.
setStrikethrough(strikethrough)TextSets the strikethrough setting.
setStrikethrough(startOffset, endOffsetInclusive, strikethrough)TextSets the strikethrough setting for the specified character range.
setText(text)TextSets the text contents.
setUnderline(underline)TextSets the underline setting.
setUnderline(startOffset, endOffsetInclusive, underline)TextSets the underline setting for the specified character range.

Detailed documentation

appendText(text)

Appends the specified text at the given character offset.

Parameters

NameTypeDescription
textStringthe text to append

Return

Text — the current element


copy()

Returns a detached, deep copy of the current element.

Any child elements present in the element are also copied. The new element will not have a parent.

Return

Text — the new copy


deleteText(startOffset, endOffsetInclusive)

Deletes a range of text.

Parameters

NameTypeDescription
startOffsetIntegerthe character offset of the first character to delete
endOffsetInclusiveIntegerthe character offset of the last character to delete

Return

Text — the current element


editAsText()

Obtains a Text version of the current element, for editing.

Use editAsText for manipulating the elements contents as rich text. The editAsText mode ignores non-text elements (such as InlineImage and HorizontalRule).

Child elements fully contained within a deleted text range are removed from the element.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Insert two paragraphs separated by a paragraph containing an
 // horizontal rule.
 body.insertParagraph(0, "An editAsText sample.");
 body.insertHorizontalRule(0);
 body.insertParagraph(0, "An example.");

 // Delete " sample.\n\n An" removing the horizontal rule in the process.
 body.editAsText().deleteText(14, 25);
 

Return

Text — a text version of the current element


findText(searchPattern)

Searches the contents of the element for the specified text pattern using regular expressions.

A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.

The provided regular expression pattern is independently matched against each text block contained in the current element.

Parameters

NameTypeDescription
searchPatternStringthe pattern to search for

Return

RangeElement — a search result indicating the position of the search text, or null if there is no match


findText(searchPattern, from)

Searches the contents of the element for the specified text pattern, starting from a given search result.

A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.

The provided regular expression pattern is independently matched against each text block contained in the current element.

Parameters

NameTypeDescription
searchPatternStringthe pattern to search for
fromRangeElementthe search result to search from

Return

RangeElement — a search result indicating the next position of the search text, or null if there is no match


getAttributes()

Retrieves the element's attributes.

The result is an object containing a property for each valid element attribute where each property name corresponds to an item in the DocumentApp.Attribute enumeration.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Append a styled paragraph.
 var par = body.appendParagraph('A bold, italicized paragraph.');
 par.setBold(true);
 par.setItalic(true);

 // Retrieve the paragraph's attributes.
 var atts = par.getAttributes();

 // Log the paragraph attributes.
 for (var att in atts) {
   Logger.log(att + ":" + atts[att]);
 }
 

Return

Object — the element's attributes


getAttributes(offset)

Retrieves the attributes at the specified character offset.

The result is an object containing a property for each valid text attribute where each property name corresponds to an item in the DocumentApp.Attribute enumeration.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Object — the element's attributes


getBackgroundColor()

Retrieves the background color setting.

Return

String — the background color, or null if the element contains multiple values for this attribute


getBackgroundColor(offset)

Retrieves the background color at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

String — the background color


getFontFamily()

Retrieves the font family setting.

Return

FontFamily — the font family, or null if the element contains multiple values for this attribute


getFontFamily(offset)

Retrieves the font family at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

FontFamily — the font family


getFontSize()

Retrieves the font size setting.

Return

Integer — the font size, or null if the element contains multiple values for this attribute


getFontSize(offset)

Retrieves the font size at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Integer — the font size


getForegroundColor()

Retrieves the foreground color setting.

Return

String — the foreground color, or null if the element contains multiple values for this attribute


getForegroundColor(offset)

Retrieves the foreground color at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

String — the foreground color


getLinkUrl()

Retrieves the link url.

Return

String — the link url, or null if the element contains multiple values for this attribute


getLinkUrl(offset)

Retrieves the link url at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

String — the link url


getNextSibling()

Retrieves the element's next sibling element.

The next sibling has the same parent and follows the current element.

Return

Element — the next sibling element


getParent()

Retrieves the element's parent element.

The parent element contains the current element.

Return

ContainerElement — the parent element


getPreviousSibling()

Retrieves the element's previous sibling element.

The previous sibling has the same parent and precedes the current element.

Return

Element — the previous sibling element


getText()

Retrieves the contents of the element as a text string.

Return

String — the contents of the element as text string


getTextAttributeIndices()

Retrieves the set of text indices that correspond to the start of distinct text formatting runs.

Return

Integer[] — the set of text indices at which text formatting changes


getType()

Retrieves the element's ElementType.

Use getType() to determine the exact type of a given element.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Obtain the first element in the document body.

 var firstChild = body.getChild(0);

 // Use getType() to determine the element's type.
 if (firstChild.getType() == DocumentApp.ElementType.PARAGRAPH) {
   Logger.log('The first element is a paragraph.');
 } else {
   Logger.log('The first element is not a paragraph.');
 }
 

Return

ElementType — the element type


insertText(offset, text)

Inserts the specified text at the given character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset at which to insert
textStringthe text to insert

Return

Text — the current element


isAtDocumentEnd()

Determines whether the element is at the end of the Document.

Return

Boolean — whether the element is at the end of the document


isBold()

Retrieves the bold setting.

Return

Boolean — whether the text is bold, or null if the element contains multiple values for this attribute


isBold(offset)

Retrieves the bold setting at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Boolean — the bold setting


isItalic()

Retrieves the italic setting.

Return

Boolean — whether the text is italic, or null if the element contains multiple values for this attribute


isItalic(offset)

Retrieves the italic setting at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Boolean — the italic setting


isStrikethrough()

Retrieves the strikethrough setting.

Return

Boolean — whether the text is strikethrough, or null if the element contains multiple values for this attribute


isStrikethrough(offset)

Retrieves the strikethrough setting at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Boolean — the strikethrough setting


isUnderline()

Retrieves the underline setting.

Return

Boolean — whether the text is underlined, or null if the element contains multiple values for this attribute


isUnderline(offset)

Retrieves the underline setting at the specified character offset.

Parameters

NameTypeDescription
offsetIntegerthe character offset

Return

Boolean — the underline setting


merge()

Merges the element with the preceding sibling of the same type.

Only elements of the same ElementType may be merged. Any child elements contained in the current element are moved to the preceding sibling element.

The current element is removed from the document.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Append two paragraphs to the document.
 var par1 = body.appendParagraph('Paragraph 1.');
 var par2 = body.appendParagraph('Paragraph 2.');

 // Merge the newly added paragraphs into a single paragraph.
 par2.merge();
 

Return

Text — the merged element


removeFromParent()

Removes the element from its parent.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Remove all images in the document body.
 var imgs = body.getImages();
 for (var i = 0; i < imgs.length; i++) {
   imgs[i].removeFromParent();
 }
 

Return

Text — the removed element


replaceText(searchPattern, replacement)

Replaces all occurrences of a given text pattern with a given replacement string, using regular expressions.

A subset of the JavaScript regular expression features are not fully supported, such as capture groups and mode modifiers.

The provided regular expression pattern is independently matched against each text block contained in the current element.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Clear the text surrounding "Apps Script", with or without text.
 body.replaceText("^.*Apps ?Script.*$", "Apps Script");
 

Parameters

NameTypeDescription
searchPatternStringthe regex pattern to search for
replacementStringthe text to use as replacement

Return

Element — the current element


setAttributes(startOffset, endOffsetInclusive, attributes)

Applies the specified attributes to the given character range.

The specified attributes parameter must be an object where each property name is an item in the DocumentApp.Attribute enumeration and each property value is the new value to be applied.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
attributesObjectthe element's attributes

Return

Text — the current element


setAttributes(attributes)

Sets the element's attributes.

The specified attributes parameter must be an object where each property name is an item in the DocumentApp.Attribute enumeration and each property value is the new value to be applied.

 
var body = DocumentApp.getActiveDocument().getBody();

 // Define a custom paragraph style.
 var style = {};
 style[DocumentApp.Attribute.HORIZONTAL_ALIGNMENT] =
     DocumentApp.HorizontalAlignment.RIGHT;
 style[DocumentApp.Attribute.FONT_FAMILY] =
     DocumentApp.FontFamily.CALIBRI;
 style[DocumentApp.Attribute.FONT_SIZE] = 18;
 style[DocumentApp.Attribute.BOLD] = true;

 // Append a plain paragraph.
 var par = body.appendParagraph('A paragraph with custom style.');

 // Apply the custom style.
 par.setAttributes(style);
 

Parameters

NameTypeDescription
attributesObjectthe element's attributes

Return

Text — the current element


setBackgroundColor(startOffset, endOffsetInclusive, color)

Sets the background color for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
colorStringthe background color

Return

Text — the current element


setBackgroundColor(color)

Sets the background color.

Parameters

NameTypeDescription
colorStringthe background color

Return

Text — the current element


setBold(bold)

Sets the bold setting.

Parameters

NameTypeDescription
boldBooleanthe bold setting

Return

Text — the current element


setBold(startOffset, endOffsetInclusive, bold)

Sets the bold setting for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
boldBooleanthe bold setting

Return

Text — the current element


setFontFamily(family)

Sets the font family.

Parameters

NameTypeDescription
familyFontFamilythe font family

Return

Text — the current element


setFontFamily(startOffset, endOffsetInclusive, family)

Sets the font family for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
familyFontFamilythe font family

Return

Text — the current element


setFontSize(size)

Sets the font size.

Parameters

NameTypeDescription
sizeIntegerthe font size

Return

Text — the current element


setFontSize(startOffset, endOffsetInclusive, size)

Sets the font size for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
sizeIntegerthe font size

Return

Text — the current element


setForegroundColor(startOffset, endOffsetInclusive, color)

Sets the foreground color for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
colorStringthe foreground color

Return

Text — the current element


setForegroundColor(color)

Sets the foreground color.

Parameters

NameTypeDescription
colorStringthe foreground color

Return

Text — the current element


setItalic(italic)

Sets the italic setting.

Parameters

NameTypeDescription
italicBooleanthe italic setting

Return

Text — the current element


setItalic(startOffset, endOffsetInclusive, italic)

Sets the italic setting for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
italicBooleanthe italic setting

Return

Text — the current element


setLinkUrl(startOffset, endOffsetInclusive, url)

Sets the link url for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
urlStringthe link url

Return

Text — the current element


setLinkUrl(url)

Sets the link url.

Parameters

NameTypeDescription
urlStringthe link url

Return

Text — the current element


setStrikethrough(strikethrough)

Sets the strikethrough setting.

Parameters

NameTypeDescription
strikethroughBooleanthe strikethrough setting

Return

Text — the current element


setStrikethrough(startOffset, endOffsetInclusive, strikethrough)

Sets the strikethrough setting for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
strikethroughBooleanthe strikethrough setting

Return

Text — the current element


setText(text)

Sets the text contents.

Parameters

NameTypeDescription
textStringthe new text contents

Return

Text — the current element


setUnderline(underline)

Sets the underline setting.

Parameters

NameTypeDescription
underlineBooleanthe underline setting

Return

Text — the current element


setUnderline(startOffset, endOffsetInclusive, underline)

Sets the underline setting for the specified character range.

Parameters

NameTypeDescription
startOffsetIntegerthe text range's start offset
endOffsetInclusiveIntegerthe text range's end offset
underlineBooleanthe underline setting

Return

Text — the current element

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.