Uma referência a um local no documento, relativo a um elemento específico. O cursor do usuário é
representado como um Position
, entre outros usos. Os scripts só podem acessar o cursor do usuário que está executando o script e apenas se o script estiver vinculado ao documento.
// Insert some text at the cursor position and make it bold. var 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. var element = cursor.insertText('ಠ‿ಠ'); if (element) { element.setBold(true); } else { DocumentApp.getUi().alert('Cannot insert text here.'); } } else { DocumentApp.getUi().alert('Cannot find a cursor.'); }
Métodos
Método | Tipo de retorno | Breve descrição |
---|---|---|
getElement() | Element | Recebe o elemento que contém esse Position . |
getOffset() | Integer | Recebe o local relativo desse Position dentro do elemento que o contém. |
getSurroundingText() | Text | Cria um elemento Text artificial que representa o texto e a formatação da
Paragraph ou da ListItem que contém o Position , seja diretamente ou por uma cadeia de elementos filhos. |
getSurroundingTextOffset() | Integer | Recebe o deslocamento dessa Position dentro do elemento Text retornado por getSurroundingText() . |
insertBookmark() | Bookmark | Cria e insere um novo Bookmark nesse Position . |
insertInlineImage(image) | InlineImage | Cria e insere um novo InlineImage neste Position do blob de imagem especificado. |
insertText(text) | Text | Insere o texto especificado neste Position . |
Documentação detalhada
getElement()
Recebe o elemento que contém esse Position
. Ele será um elemento Text
ou de contêiner, como Paragraph
. Em ambos os casos, a posição
relativa dentro do elemento pode ser determinada com getOffset()
.
Retorno
Element
: o contêiner ou elemento Text
em que esse objeto Position
está localizado.
getOffset()
Recebe o local relativo desse Position
dentro do elemento que o contém. Se o
elemento for Text
, o deslocamento será o número de caracteres antes de Position
(ou seja, o índice do caractere depois dessa Position
). Para qualquer outro
elemento, o deslocamento é o número de elementos filhos antes desse Position
dentro do
mesmo elemento de contêiner (ou seja, o índice do elemento filho após Position
).
Retorno
Integer
: para elementos Text
, o número de caracteres antes dessa Position
. Para
outros elementos, o número de elementos filhos antes dessa Position
no mesmo
elemento de contêiner
Autorização
Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getSurroundingText()
Cria um elemento Text
artificial que representa o texto e a formatação da
Paragraph
ou da ListItem
que contém o Position
, seja diretamente ou por uma cadeia de elementos filhos. Para determinar o deslocamento de Position
no elemento Text
retornado, use getSurroundingTextOffset()
.
Retorno
Text
: um elemento equivalente ao resultado da chamada de editAsText()
na Paragraph
ou no ListItem
que contém o Position
, seja diretamente ou por uma cadeia de elementos filhos
Autorização
Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getSurroundingTextOffset()
Recebe o deslocamento dessa Position
dentro do elemento Text
retornado por getSurroundingText()
. O deslocamento é o número de caracteres antes da Position
,
ou seja, o índice do caractere depois dessa Position
.
Retorno
Integer
: o número de caracteres antes dessa Position
na Paragraph
ou no ListItem
que contém o Position
, seja diretamente ou por uma cadeia de elementos filhos
Autorização
Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
insertBookmark()
insertInlineImage(image)
Cria e insere um novo InlineImage
neste Position
do blob de imagem especificado.
Parâmetros
Nome | Tipo | Descrição |
---|---|---|
image | BlobSource | os dados da imagem para inserir neste Position |
Retorno
InlineImage
: o novo elemento de imagem, ou null
se o elemento em que esse Position
está
localizado não permitir que imagens sejam inseridas
Autorização
Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
insertText(text)
Insere o texto especificado neste Position
. Esse método cria um novo elemento Text
, mesmo que a string seja inserida em um elemento Text
já existente, para
facilitar o estilo do novo elemento.
Parâmetros
Nome | Tipo | Descrição |
---|---|---|
text | String | a string a ser inserida neste Position |
Retorno
Text
: o novo elemento de texto, ou null
se o elemento em que esse Position
está localizado não permitir que texto seja inserido.
Autorização
Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents