Class RangeBuilder  |  Apps Script  |  Google for Developers (original) (raw)

Class RangeBuilder

Stay organized with collections Save and categorize content based on your preferences.

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

Method Return type Brief description
addElement(element) RangeBuilder Adds an entire Element to this RangeBuilder.
addElement(textElement, startOffset, endOffsetInclusive) RangeBuilder Adds a partial Text element to this RangeBuilder.
addElementsBetween(startElement, endElementInclusive) RangeBuilder Adds two entire elements, and all elements between them, to this RangeBuilder.
addElementsBetween(startTextElement, startOffset, endTextElementInclusive, endOffsetInclusive) RangeBuilder Adds two partial Text elements, and all elements between them, to the RangeBuilder.
addRange(range) RangeBuilder Adds the contents of another Range to this RangeBuilder.
build() Range Constructs 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).

Deprecated methods

Method Return type Brief description
getSelectedElements() RangeElement[] Gets all elements that the user has selected in the open instance of the document, including any partially selected Textelements.

Detailed documentation

addElement(element)

Adds an entire [Element](/apps-script/reference/document/element) to this RangeBuilder.

Parameters

Name Type Description
element Element the element to be added

Return

[RangeBuilder](#) — this builder, for chaining

Scripts that use this method require authorization with one or more of the following scopes:

addElement(textElement, startOffset, endOffsetInclusive)

Adds a partial [Text](/apps-script/reference/document/text) element to this RangeBuilder.

Parameters

Name Type Description
textElement Text the text element to be partially added
startOffset Integer the number of characters before the first character to be included (that is, the index of the first character in the range)
endOffsetInclusive Integer the 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:

addElementsBetween(startElement, endElementInclusive)

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

Parameters

Name Type Description
startElement Element the first element to be added
endElementInclusive Element the 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:

addElementsBetween(startTextElement, startOffset, endTextElementInclusive, endOffsetInclusive)

Adds two partial [Text](/apps-script/reference/document/text) elements, and all elements between them, to the RangeBuilder.

Parameters

Name Type Description
startTextElement Text the first text element to be partially added
startOffset Integer the number of characters before the first character of startTextElement to be included (that is, the index of the first character in the range)
endTextElementInclusive Text the last text element to be partially added
endOffsetInclusive Integer the 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:

addRange(range)

Adds the contents of another Range to this RangeBuilder.

Parameters

Name Type Description
range Range the 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:

build()

Constructs a Range from the settings applied to the builder.

Return

[Range](/apps-script/reference/document/range) — the newly constructed range

getRangeElements()

Gets all elements in this Range, including any partial [Text](/apps-script/reference/document/text) elements (for example, in the case of a selection that includes only part of a Text element). To determine whether aText element is only partially included in the range, see [RangeElement.isPartial()](/apps-script/reference/document/range-element#isPartial%28%29).

Return

[RangeElement[]](/apps-script/reference/document/range-element) — 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:

Deprecated methods

getSelectedElements()

Deprecated. Renamed to [getRangeElements()](#getRangeElements%28%29).

Gets all elements that the user has selected in the open instance of the document, including any partially selected [Text](/apps-script/reference/document/text)elements.

Return

[RangeElement[]](/apps-script/reference/document/range-element) — an array of selected or partially selected 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:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-12-03 UTC.