O Google Apps Script permite 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.
Noções básicas
O Apps Script pode interagir com os Documentos Google de duas maneiras amplas: qualquer script pode criar ou modificar um documento se o usuário tiver as permissões apropriadas, e um script também pode ser vinculado a um documento, o que dá ao script habilidades especiais para alterar a interface do usuário ou responder quando o documento é aberto. Para criar um script vinculado a contêiner no Documentos Google, clique em Extensões > Apps Script.
Nos dois casos, é simples interagir com um arquivo dos Documentos Google usando o serviço de documentos do Apps Script, conforme 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 documento no Google Drive do usuário e, em seguida, insere
um parágrafo com o mesmo texto que o nome do documento, estiliza esse
parágrafo como título e anexa uma tabela com base nos valores em uma
matriz bidimensional. O script pode fazer essas mudanças em um
documento atual com a mesma 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 arquivo do Documentos Google é estruturado como um documento HTML,
ou seja, um arquivo do Documentos Google é composto de elementos (como uma
Paragraph
ou
Table
) que muitas vezes contêm outros
elementos. A maioria dos scripts que modificam um arquivo do Documentos Google começa com uma chamada para getBody()
, porque 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 ser incluídos em um determinado tipo de elemento.
Os elementos mostrados em negrito podem ser inseridos. Os elementos sem negrito só podem ser manipulados no lugar.
- Documento
- Corpo
- HeaderSection
- ListItem
- HorizontalRule
- InlineDrawing
- Imagem inline
- Texto
- SupportedElement (número da página etc.)
- Parágrafo
- HorizontalRule
- InlineDrawing
- Imagem inline
- Texto
- SupportedElement (número da página etc.)
- Tabela
- ListItem
- footerSection
- ListItem
- HorizontalRule
- InlineDrawing
- Imagem inline
- Texto
- SupportedElement (número da página etc.)
- Parágrafo
- HorizontalRule
- InlineDrawing
- Imagem inline
- Texto
- SupportedElement (número da página etc.)
- Tabela
- ListItem
- Nota de rodapé
Substituindo texto
O Apps Script geralmente é usado para substituir texto nos Documentos Google. Digamos que você tenha uma planilha cheia de informações de clientes e queira gerar um arquivo do Documentos Google personalizado para cada um. Esse tipo de operação é geralmente chamado de mesclagem de e-mails.
Há muitas maneiras de substituir o texto, mas o mais simples é o
método replaceText()
mostrado no exemplo abaixo. replaceText
oferece suporte à maioria
dos recursos de expressão regular do JavaScript. A primeira função abaixo
adiciona várias linhas de texto marcador de posição a um arquivo dos Documentos Google. No mundo real, é mais
provável que você mesmo digite os marcadores no documento. A
segunda função substitui os marcadores por propriedades definidas no
objeto client
.
Essas duas funções usam o método
getActiveDocument()
,
que só se aplica a scripts criados dentro de um arquivo dos Documentos Google. Em um
script independente, use
DocumentApp.create()
,
openById()
ou
openByUrl()
.
Adicionar 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. Lembre-se, no entanto, de que um script só pode interagir com a IU da instância atual de um documento aberto e somente se o script estiver vinculado ao documento.
Veja como adicionar menus personalizados e caixas de diálogo aos seus Documentos Google. Para saber mais sobre como criar interfaces personalizadas para uma caixa de diálogo ou uma barra lateral, consulte o guia do 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 os Documentos Google
Os complementos são executados dentro dos Documentos Google e podem ser instalados na loja de complementos do Documentos Google. Se você desenvolveu um script para Documentos Google e quer compartilhá-lo com o mundo, o Apps Script permite que você publique seu script como um complemento para que outros usuários possam instalá-lo da loja de complementos.
Para saber como criar um complemento para os Documentos Google, consulte o guia de início rápido para criar complementos do Documentos Google.
Gatilhos
Os scripts vinculados a um arquivo
do Documentos Google podem usar um acionador simples para responder
ao evento onOpen
do documento, que
ocorre sempre que um usuário com acesso para editar o abre nos Documentos Google.
Para configurar o gatilho, basta escrever uma função chamada onOpen()
. Para conferir um exemplo
desse acionador, consulte Menus personalizados no Google Workspace.
Embora o gatilho simples seja útil para adicionar menus, ele não pode usar serviços do Apps Script que exigem autorização.