O Google Apps Script permite criar e modificar de forma programática o Google Docs, bem como 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 o Documentos Google de duas maneiras amplas: qualquer script pode criar ou modificar um documento se o usuário do script tiver as permissões apropriadas para o documento, e um script também pode ser vinculado a um documento, o que dá ao script, habilidades especiais de alterar a interface do usuário ou responder quando o documento for aberto. Para criar um script vinculado a um contêiner no Documentos Google, faça o seguinte: Clique em Extensões > Apps Script.
Em ambos os casos, é simples interagir com um Documento Google por meio da interface Document Service, como no exemplo a seguir demonstra.
function createDoc() { var doc = DocumentApp.create('Sample Document'); var documentTab = doc.getTab('t.0').asDocumentTab(); var body = documentTab.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 e, em seguida,
recupera a guia com ID "t.0" (a primeira guia padrão), insere um parágrafo.
que contenha o mesmo texto que o nome do documento, estilos que o parágrafo como um
e anexa uma tabela com base nos valores em uma matriz bidimensional. O
poderia fazer essas alterações em um documento existente com a mesma facilidade
substituindo a chamada para DocumentApp.create()
com 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 do Documentos Google é estruturado
muito parecido com um documento HTML, ou seja, um documento é composto de um ou mais
Tabs
, cada uma contendo elementos
(como um Paragraph
ou
Table
) que geralmente contêm outras
os elementos. A maioria dos scripts que modificam um documento Google começa com uma chamada para
getTab()
e
asDocumentTab()
seguido por getBody()
,
porque Body
é um elemento central
que contém todos os outros elementos de uma guia, exceto o
HeaderSection
,
FooterSection
e quaisquer
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 certos tipos de elementos em outros. A árvore abaixo mostra qual podem estar contidos por um determinado tipo de elemento.
Os elementos mostrados em negrito podem ser inseridos; elementos que não estejam em negrito só podem ser mas manipuladas.
- Documento
- Guia
- 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
- FootnoteSection
- Guia
Substituir texto
O Apps Script é usado com frequência para substituir texto nos Documentos Google. Digamos que você tem um de dados cheia de informações do cliente e quiser gerar um relatório Documentos Google para cada cliente. (Esse tipo de operação também é chamado de merge.)
Há muitas maneiras de substituir texto, mas a mais simples é a
replaceText()
mostrado no exemplo abaixo. replaceText
suporta a maioria
dos recursos de expressão regular do JavaScript. A primeira função abaixo
adiciona várias linhas de texto de espaço reservado a um arquivo dos Documentos Google; no mundo real,
seria mais provável que você mesmo digitasse os espaços reservados no documento. O
a segunda função substitui os espaços reservados pelas propriedades definidas na
client
.
Observe que ambas as funções usam o
getActiveDocument()
, que só se aplica a scripts criados em um documento Google; em um
um script independente, use
DocumentApp.create()
,
openById()
,
ou openByUrl()
como alternativa.
Adicione alguns marcadores de posição
function createPlaceholders() { var body = DocumentApp.getActiveDocument().getTab('t.0').asDocumentTab().getBody(); body.appendParagraph('{name}'); body.appendParagraph('{address}'); body.appendParagraph('{city} {state} {zip}'); }
Substituir os marcadores de posição
function searchAndReplace() { var body = DocumentApp.getActiveDocument().getTab('t.0').asDocumentTab().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 o Documentos Google adicionando menus, caixas de diálogo e barras laterais. Porém, lembre-se de que um script só pode interagir com a interface a instância atual de um documento aberto, e somente se o script for bound para o documento.
Veja como adicionar menus personalizados e caixas de diálogo nos Documentos Google. Para saber mais sobre como criar interfaces personalizadas para uma caixa de diálogo ou barra lateral, consulte a guia do serviço HTML. Se você planeja publicar sua interface personalizada como parte de um complemento, siga as guia de estilo para manter a consistência com o estilo e layout dos Editores de arquivos Google.
Complementos para o Documentos Google
Complementos que podem ser executados dentro dos Documentos Google e podem ser instalados na loja de complementos do Documentos Google. Se você desenvolveu um script para o Documentos Google e quiser compartilhá-lo com o mundo, o Apps Script permite que você publicar seu script como para que outros usuários possam instalá-lo da loja de complementos.
Para acessar como você pode criar um complemento para o Documentos Google, consulte guia de início rápido para criar complementos do Documentos Google.
Gatilhos
Os scripts que estão vinculados a uma conta do Google
O documento pode usar um acionador simples para responder
ao evento onOpen
do documento, que
ocorre sempre que um usuário com acesso para editar o documento o abre no Google Docs.
Para configurar o gatilho, basta escrever uma função com o nome onOpen()
. Para obter um exemplo
desse acionador, consulte Menus personalizados no Google Workspace.
Embora o gatilho simples seja útil para adicionar menus, ele não pode usar apps
Serviços de script que exigem autorização.