Class Position

Posição

Uma referência a um local na guia no documento, em relação a um elemento específico. O cursor do usuário é representado como uma Position, entre outros usos. Os scripts só podem acessar o cursor do usuário que está executando o script e somente se o script estiver vinculado ao documento.

// 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.');
}

Métodos

Método	Tipo de retorno	Breve descrição
getElement()	Element	Recebe o elemento que contém essa Position.
getOffset()	Integer	Recebe o local relativo dessa Position no elemento que a contém.
getSurroundingText()	Text	Cria um elemento Text artificial que representa o texto e a formatação do Paragraph ou ListItem que contém a Position, diretamente ou por uma cadeia de elementos filhos.
getSurroundingTextOffset()	Integer	Recebe o deslocamento desse Position no elemento Text retornado por getSurroundingText().
insertBookmark()	Bookmark	Cria e insere um novo Bookmark nessa Position.
insertInlineImage(image)	InlineImage|null	Cria e insere um novo InlineImage nessa Position do blob de imagem especificado.
insertText(text)	Text|null	Insere o texto especificado nessa Position.

Documentação detalhada

getElement()

Recebe o elemento que contém essa Position. Esse será um elemento Text ou um elemento de contêiner, como Paragraph. Em ambos os casos, a posição relativa dentro do elemento pode ser determinada com getOffset().

Retornar

Element — o contêiner ou elemento Text em que esse objeto Position está localizado

---

getOffset()

Recebe o local relativo dessa Position no elemento que a contém. Se o elemento for um elemento Text, o deslocamento será o número de caracteres antes da Position (ou seja, o índice do caractere após essa Position). Para qualquer outro elemento, o deslocamento será o número de elementos filhos antes dessa Position no mesmo elemento de contêiner (ou seja, o índice do elemento filho após a Position).

Retornar

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 do Paragraph ou ListItem que contém a Position, diretamente ou por uma cadeia de elementos filhos. Para determinar o deslocamento do Position no elemento Text retornado, use getSurroundingTextOffset().

Retornar

Text — um elemento equivalente ao resultado da chamada de editAsText() no Paragraph ou ListItem que contém a Position, 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 desse Position no elemento Text retornado por getSurroundingText(). O deslocamento é o número de caracteres antes da Position (ou seja, o índice do caractere após essa Position).

Retornar

Integer — o número de caracteres antes dessa Position no Paragraph ou ListItem que contém a Position, 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()

Cria e insere um novo Bookmark nessa Position.

Retornar

Bookmark — o novo marcador

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

---

insertInlineImage(image)

Cria e insere uma nova InlineImage nessa Position do blob de imagem especificado.

Parâmetros

Nome	Tipo	Descrição
image	BlobSource	os dados da imagem a serem inseridos nessa Position

Retornar

InlineImage|null — o novo elemento de imagem ou null se o elemento em que este Position está localizado não permitir a inserção de imagens

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 nessa Position. Esse método cria um novo Text elemento, mesmo que a string seja inserida em um elemento Text existente, para facilitar a aplicação de estilo ao novo elemento.

Parâmetros

Nome	Tipo	Descrição
text	String	a string a ser inserida nessa Position

Retornar

Text|null — o novo elemento do texto ou null se o elemento em que este Position estiver localizado não permitir a inserção de texto

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