Class RangeBuilder

  • RangeBuilder helps construct Range objects, defining sections within a Google Doc, using various methods to specify elements or portions of text.

  • You can add entire or partial elements to the Range using addElement, addElementsBetween, or by incorporating existing Range objects with addRange.

  • The build method finalizes the Range construction, enabling you to apply formatting or other operations to the designated content.

  • getRangeElements provides access to all elements within the Range, including partially selected text elements for granular control and manipulation.
RangeBuilder

A builder used to construct Range objects from document elements. 

// Change the user's selection to a range that includes every table in the
// active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

Methods

MethodReturn typeBrief description
addElement(element)RangeBuilderAdds an entire Element to this RangeBuilder.
addElement(textElement, startOffset, endOffsetInclusive)RangeBuilderAdds a partial Text element to this RangeBuilder.
addElementsBetween(startElement, endElementInclusive)RangeBuilderAdds two entire elements, and all elements between them, to this RangeBuilder.
addElementsBetween(startTextElement, startOffset, endTextElementInclusive, endOffsetInclusive)RangeBuilderAdds two partial Text elements, and all elements between them, to the RangeBuilder.
addRange(range)RangeBuilderAdds the contents of another Range to this RangeBuilder.
build()RangeConstructs a Range from the settings applied to the builder.
getRangeElements()RangeElement[]Gets all elements in this Range, including any partial Text elements (for example, in the case of a selection that includes only part of a Text element).

Detailed documentation

addElement(element)

Adds an entire Element to this RangeBuilder.

Parameters

NameTypeDescription
elementElementthe element to be added

Return

RangeBuilder — this builder, 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

addElement(textElement, startOffset, endOffsetInclusive)

Adds a partial Text element to this RangeBuilder.

Parameters

NameTypeDescription
textElementTextthe text element to be partially added
startOffsetIntegerthe number of characters before the first character to be included (that is, the index of the first character in the range)
endOffsetInclusiveIntegerthe number of characters before the last character to be included (that is, the index of the last character in the range)

Return

RangeBuilder — this builder, 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

addElementsBetween(startElement, endElementInclusive)

Adds two entire elements, and all elements between them, to this RangeBuilder.

Parameters

NameTypeDescription
startElementElementthe first element to be added
endElementInclusiveElementthe last element to be added

Return

RangeBuilder — this builder, 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

addElementsBetween(startTextElement, startOffset, endTextElementInclusive, endOffsetInclusive)

Adds two partial Text elements, and all elements between them, to the RangeBuilder.

Parameters

NameTypeDescription
startTextElementTextthe first text element to be partially added
startOffsetIntegerthe number of characters before the first character of startTextElement to be included (that is, the index of the first character in the range)
endTextElementInclusiveTextthe last text element to be partially added
endOffsetInclusiveIntegerthe number of characters before the last character of endTextElementInclusive to be included (that is, the index of the last character in the range)

Return

RangeBuilder — this builder, 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

addRange(range)

Adds the contents of another Range to this RangeBuilder.

Parameters

NameTypeDescription
rangeRangethe range whose elements should be added

Return

RangeBuilder — this builder, 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

build()

Constructs a Range from the settings applied to the builder.

Return

Range — the newly constructed range

getRangeElements()

Gets all elements in this Range, including any partial Text elements (for example, in the case of a selection that includes only part of a Text element). To determine whether a Text element is only partially included in the range, see RangeElement.isPartial().

Return

RangeElement[] — an array of elements, in the order they appear 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

Deprecated methods