Class NamedRange

  • A NamedRange is a Range with a name and ID for later retrieval; names are not unique, but IDs are unique within the tab.

  • Once added to a tab, a NamedRange cannot be modified, only removed.

  • NamedRanges can be accessed by any script accessing the tab, and prefixing names with a unique string can help avoid conflicts.

  • The available methods for a NamedRange are getId(), getName(), getRange(), and remove().

NamedRange

ARange that has a name and ID to allow later retrieval. Names are notnecessarily unique; several different ranges in the same tab may share the same name, much like aclass in HTML. By contrast, IDs are unique within the tab, like an ID in HTML. Once aNamedRange has been added to a tab, it cannot be modified, only removed.

ANamedRange can be accessed by any script that accesses the tab. To avoid unintendedconflicts between scripts, consider prefixing range names with a unique string.

// Create a named range that includes every table in the active tab.constdocumentTab=DocumentApp.getActiveDocument().getActiveTab().asDocumentTab();constrangeBuilder=documentTab.newRange();consttables=documentTab.getBody().getTables();for(leti=0;i <tables.length;i++){rangeBuilder.addElement(tables[i]);}documentTab.addNamedRange('myUniquePrefix-tables',rangeBuilder.build());

Methods

MethodReturn typeBrief description
getId()StringGets the ID of thisNamedRange.
getName()StringGets the name of thisNamedRange.
getRange()RangeGets the range of elements associated with thisNamedRange.
remove()voidRemoves thisNamedRange from the tab.

Detailed documentation

getId()

Gets the ID of thisNamedRange. The ID is unique within the tab.

Return

String — The range's ID, which is unique within the tab.

getName()

Gets the name of thisNamedRange. The name is not necessarily unique.

Return

String — The range's name, which is not necessarily unique.

Authorization

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

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getRange()

Gets the range of elements associated with thisNamedRange.

Return

Range — The range of elements associated with the name and ID.

Authorization

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

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

remove()

Removes thisNamedRange from the tab. This method doesn't delete the contents of therange; it merely the removes the reference. Calling this method on aNamedRange thathas already been removed has no effect.

Authorization

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

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

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

Last updated 2025-12-11 UTC.