Class Position | Apps Script | Google for Developers (original) (raw)
Class Position
Stay organized with collections Save and categorize content based on your preferences.
Position
A reference to a location in the document tab, relative to a specific element. The user's cursor is represented as a Position, among other uses. Scripts 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. const 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. const element = cursor.insertText('ಠ‿ಠ'); if (element) { element.setBold(true); } else { DocumentApp.getUi().alert('Cannot insert text here.'); } } else { DocumentApp.getUi().alert('Cannot find a cursor.'); }
Methods
| Method | Return type | Brief description |
|---|---|---|
| getElement() | Element | Gets the element that contains this Position. |
| getOffset() | Integer | Gets this Position's relative location within the element that contains it. |
| getSurroundingText() | Text | Creates an artificial Text element that represents the text and formatting of theParagraph or ListItem that contains the Position, either directly or through a chain of child elements. |
| getSurroundingTextOffset() | Integer | Gets the offset of this Position within the Text element returned by getSurroundingText(). |
| insertBookmark() | Bookmark | Creates and inserts a new Bookmark at this Position. |
| insertInlineImage(image) | InlineImage | Creates and inserts a new InlineImage at this Position from the specified image blob. |
| insertText(text) | Text | Inserts the specified text at this Position. |
Detailed documentation
getElement()
Gets the element that contains this Position. This will be either a [Text](/apps-script/reference/document/text)element or a container element like [Paragraph](/apps-script/reference/document/paragraph). In either case, the relative position within the element can be determined with [getOffset()](#getOffset%28%29).
Return
[Element](/apps-script/reference/document/element) — the container or [Text](/apps-script/reference/document/text) element in which this Position object is located
getOffset()
Gets this Position's relative location within the element that contains it. If the element is a [Text](/apps-script/reference/document/text) element, the offset is the number of characters before the Position (that is, the index of the character after this Position); for any other element, the offset is the number of child elements before this Position within the same container element (that is, the index of the child element after the Position).
Return
Integer — for [Text](/apps-script/reference/document/text) elements, the number of characters before this Position; for other elements, the number of child elements before this Position within the same container element
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
getSurroundingText()
Creates an artificial [Text](/apps-script/reference/document/text) element that represents the text and formatting of the[Paragraph](/apps-script/reference/document/paragraph) or [ListItem](/apps-script/reference/document/list-item) that contains the Position, either directly or through a chain of child elements. To determine the Position's offset in the returned Text element, use [getSurroundingTextOffset()](#getSurroundingTextOffset%28%29).
Return
[Text](/apps-script/reference/document/text) — an element equivalent to the result of calling [editAsText()](/apps-script/reference/document/paragraph#editAsText%28%29) on the [Paragraph](/apps-script/reference/document/paragraph) or [ListItem](/apps-script/reference/document/list-item) that contains the Position, either directly or through a chain of child elements
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
getSurroundingTextOffset()
Gets the offset of this Position within the [Text](/apps-script/reference/document/text) element returned by [getSurroundingText()](#getSurroundingText%28%29). The offset is the number of characters before the Position(that is, the index of the character after this Position).
Return
Integer — the number of characters before this Position in the [Paragraph](/apps-script/reference/document/paragraph) or [ListItem](/apps-script/reference/document/list-item) that contains the Position, either directly or through a chain of child elements
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
insertBookmark()
Creates and inserts a new [Bookmark](/apps-script/reference/document/bookmark) at this Position.
Return
[Bookmark](/apps-script/reference/document/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.currentonlyhttps://www.googleapis.com/auth/documents
insertInlineImage(image)
Creates and inserts a new [InlineImage](/apps-script/reference/document/inline-image) at this Position from the specified image blob.
Parameters
| Name | Type | Description |
|---|---|---|
| image | BlobSource | the image data to insert at this Position |
Return
[InlineImage](/apps-script/reference/document/inline-image) — the new image element, or null if the element in which this Position is located does not allow images to be inserted
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
insertText(text)
Inserts the specified text at this Position. This method creates a new [Text](/apps-script/reference/document/text)element, even if the string is inserted within an existing Text element, so that it is easy to style the new element.
Parameters
| Name | Type | Description |
|---|---|---|
| text | String | the string to insert at this Position |
Return
[Text](/apps-script/reference/document/text) — the new text element, or null if the element in which this Position is located does not allow text to be inserted
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
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.