Com o Google Apps Script, você pode criar e modificar arquivos do Documentos Google de maneira programática, além de personalizar a interface do usuário com novos menus, caixas de diálogo e barras laterais.
Conceitos básicos
O Apps Script pode interagir com o Documentos Google de duas maneiras amplas: qualquer script pode criar ou modificar um documento se o usuário tiver as permissões adequadas para ele, e um script também pode ser vinculado a um documento, o que dá ao script capacidades especiais de alterar a interface do usuário ou responder quando o documento é aberto. Para criar um script vinculado a um contêiner no Documentos Google, clique em Extensões > Apps Script.
Em ambos os casos, é simples interagir com um documento Google usando o serviço de documentos do Apps Script, como demonstrado no exemplo a seguir.
function createDoc() { var doc = DocumentApp.create('Sample Document'); var body = doc.getBody(); var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']]; body.insertParagraph(0, doc.getName()) .setHeading(DocumentApp.ParagraphHeading.HEADING1); table = body.appendTable(rowsData); table.getRow(0).editAsText().setBold(true); }
O script acima cria um novo documento no Google Drive do usuário, insere um parágrafo que contém o mesmo texto que o nome do documento, define esse parágrafo como um título e anexa uma tabela com base nos valores em uma matriz bidimensional. O script poderia fazer essas alterações em um
documento atual com facilidade substituindo a chamada para
DocumentApp.create()
por DocumentApp.openById()
ou openByUrl()
.
Para scripts criados dentro de um documento (vinculados a contêineres), use
DocumentApp.getActiveDocument()
.
Estrutura de um documento
Do ponto de vista do Apps Script, um Documento Google é estruturado como um documento HTML, ou seja, um documento Google é composto por elementos (como Paragraph
ou Table
) que geralmente contêm outros elementos. A maioria dos scripts que modificam um documento Google começa com uma chamada para
getBody()
, porque o
Body
é um elemento mestre que
contém todos os outros elementos, exceto
HeaderSection
, FooterSection
e qualquer
Footnotes
.
No entanto, existem regras sobre quais tipos de elementos podem conter outros tipos. Além disso, o serviço de documentos no Apps Script só pode inserir determinados tipos de elementos. A árvore abaixo mostra quais elementos podem estar contidos por um determinado tipo de elemento.
Os elementos mostrados em negrito podem ser inseridos, os elementos não negrito só podem ser manipulados no local.
- Documento
- Corpo
- HeaderSection
- ListItem
- HorizontalRule
- InlineDrawing
- InlineImage
- Texto
- UnsupportedElement (número da página etc.)
- Parágrafo
- HorizontalRule
- InlineDrawing
- InlineImage
- Texto
- UnsupportedElement (número da página etc.)
- Tabela
- ListItem
- footerSection
- ListItem
- HorizontalRule
- InlineDrawing
- InlineImage
- Texto
- UnsupportedElement (número da página etc.)
- Parágrafo
- HorizontalRule
- InlineDrawing
- InlineImage
- Texto
- UnsupportedElement (número da página etc.)
- Tabela
- ListItem
- Nota de rodapé
Substituir texto
O Apps Script é usado com frequência para substituir texto nos Documentos Google. Digamos que você tenha uma planilha cheia de informações de clientes e queira gerar um documento Google personalizado para cada um deles. Esse tipo de operação é geralmente chamado de mesclagem de e-mails.
Há muitas maneiras de substituir texto, mas a mais simples é o método
replaceText()
mostrado no exemplo abaixo. replaceText
é compatível com a maioria dos recursos de expressão regular do JavaScript. A primeira função abaixo adiciona várias linhas de texto de marcador de posição a um arquivo dos Documentos Google. No mundo real, é mais provável que você mesmo digite os marcadores de posição no documento. A
segunda função substitui os marcadores de posição pelas propriedades definidas no
objeto client
.
Observe que ambas as funções usam o método
getActiveDocument()
,
que se aplica apenas a scripts criados dentro de um documento Google. Em um
script independente, use
DocumentApp.create()
,
openById()
ou
openByUrl()
.
Adicione alguns marcadores de posição
function createPlaceholders() { var body = DocumentApp.getActiveDocument().getBody(); body.appendParagraph('{name}'); body.appendParagraph('{address}'); body.appendParagraph('{city} {state} {zip}'); }
Substituir os marcadores de posição
function searchAndReplace() { var body = DocumentApp.getActiveDocument() .getBody(); var client = { name: 'Joe Script-Guru', address: '100 Script Rd', city: 'Scriptville', state: 'GA', zip: 94043 }; body.replaceText('{name}', client.name); body.replaceText('{address}', client.address); body.replaceText('{city}', client.city); body.replaceText('{state}', client.state); body.replaceText('{zip}', client.zip); }
Menus e interfaces do usuário personalizados
Você pode personalizar os Documentos Google adicionando menus, caixas de diálogo e barras laterais. No entanto, lembre-se de que um script só poderá interagir com a interface da instância atual de um documento aberto e somente se o script estiver vinculado ao documento.
Saiba como adicionar menus personalizados e caixas de diálogo aos Documentos Google. Para saber mais sobre como criar interfaces personalizadas para uma caixa de diálogo ou barra lateral, consulte o guia para o serviço HTML. Se você planeja publicar sua interface personalizada como parte de um complemento, siga o guia de estilo para manter a consistência com o estilo e o layout dos Editores de arquivos Google.
Complementos para o Documentos Google
Complementos são executados dentro dos Documentos Google e podem ser instalados a partir da loja de complementos do Documentos Google. Se você desenvolveu um script para o Documentos Google e quer compartilhá-lo com o mundo, o Apps Script permite publish o script como um complemento para que outros usuários possam instalá-lo da loja de complementos.
Para saber como criar um complemento para o Documentos Google, consulte o guia de início rápido para criar complementos do Documentos Google.
Gatilhos
Os scripts vinculados a um documento
Google podem usar um acionador simples para responder
ao evento onOpen
do documento, que
ocorre sempre que um usuário com acesso para edição o abre nos Documentos Google.
Para configurar o gatilho, basta escrever uma função com o nome onOpen()
. Para conferir um exemplo
desse gatilho, consulte Menus personalizados no Google Workspace.
Embora o gatilho simples seja útil para adicionar menus, ele não pode usar nenhum serviço do Apps Script que exija autorização.