Class Position
Page Summary
A
Positionrepresents a location in a document relative to a specific element.Scripts can only access the cursor of the user running the script if the script is bound to the document.
The
Positionclass includes methods to get the containing element, its offset, surrounding text, insert bookmarks, inline images, and text.Methods like
getOffset(),getSurroundingText(), and insertion methods may require specific authorization scopes.
A reference to a location in the document tab, relative to a specific element. The user's cursoris represented as aPosition, among other uses. Scripts can only access the cursor of theuser who is running the script, and only if the script isbound to the document.
// Insert some text at the cursor position and make it bold.constcursor=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.constelement=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 |
|---|---|---|
get | Element | Gets the element that contains thisPosition. |
get | Integer | Gets thisPosition's relative location within the element that contains it. |
get | Text | Creates an artificialText element that represents the text and formatting of theParagraph orList that contains thePosition, either directly or through a chain of child elements. |
get | Integer | Gets the offset of thisPosition within theText element returned byget. |
insert | Bookmark | Creates and inserts a newBookmark at thisPosition. |
insert | Inline | Creates and inserts a newInline at thisPosition from the specified imageblob. |
insert | Text|null | Inserts the specified text at thisPosition. |
Detailed documentation
getElement()
Gets the element that contains thisPosition. This will be either aTextelement or a container element likeParagraph. In either case, the relativeposition within the element can be determined withget.
Return
Element — the container orText element in which thisPosition object is located
getOffset()
Gets thisPosition's relative location within the element that contains it. If theelement is aText element, the offset is the number of characters before thePosition (that is, the index of the character after thisPosition); for any otherelement, the offset is the number of child elements before thisPosition within thesame container element (that is, the index of the child element after thePosition).
Return
Integer — forText elements, the number of characters before thisPosition; for other elements, the number of child elements before thisPosition within the same container element
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
getSurroundingText()
Creates an artificialText element that represents the text and formatting of theParagraph orList that contains thePosition, either directly or through a chain of child elements. To determine thePosition's offset in the returnedText element, useget.
Return
Text — an element equivalent to the result of callingedit on theParagraph orList that contains thePosition, either directly or through a chain of child elements
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
getSurroundingTextOffset()
Gets the offset of thisPosition within theText element returned byget. The offset is the number of characters before thePosition(that is, the index of the character after thisPosition).
Return
Integer — the number of characters before thisPosition in theParagraph orList that contains thePosition, either directly or through a chain of child elements
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
insertBookmark()
insertInlineImage(image)
Creates and inserts a newInline at thisPosition from the specified imageblob.
Parameters
| Name | Type | Description |
|---|---|---|
image | Blob | the image data to insert at thisPosition |
Return
Inline — the new image element, ornull if the element in which thisPosition is located does not allow images to be inserted
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://www.googleapis.com/auth/documents
insertText(text)
Inserts the specified text at thisPosition. This method creates a newTextelement, even if the string is inserted within an existingText element, so that it iseasy to style the new element.
Parameters
| Name | Type | Description |
|---|---|---|
text | String | the string to insert at thisPosition |
Return
Text|null — the new text element, ornull if the element in which thisPosition is located does not allow text to be inserted
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/documents.currentonlyhttps://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.