Extensão dos Documentos Google

Com o Google Apps Script, você pode criar e modificar documentos do Google Docs de forma 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 gerais: qualquer script pode criar ou modificar um documento se o usuário do script tiver as permissões adequadas para o documento. Além disso, um script também pode ser vinculado a um documento, o que dá a ele habilidades especiais para 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, é fácil interagir com um documento do Google Docs pelo Document Service do Apps Script, como demonstrado no exemplo abaixo.

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 o ID t.0 (a primeira guia padrão), insere um parágrafo que contém o mesmo texto do nome do documento, estiliza esse parágrafo como um título e anexa uma tabela com base nos valores em uma matriz bidimensional. O script pode fazer essas mudanças em um documento existente com a mesma facilidade, substituindo a chamada para DocumentApp.create() por DocumentApp.openById() ou openByUrl(). Para scripts criados em um documento (vinculados a contêineres), use DocumentApp.getActiveDocument() e Document.getActiveTab().

Estrutura de um documento

Do ponto de vista do Apps Script, um documento do Google Docs é estruturado de forma semelhante a um documento HTML, ou seja, é composto por um ou mais objetos Tab, cada um contendo elementos (como um Paragraph ou Table) que geralmente contêm outros elementos. A maioria dos scripts que modificam um documento do Google Docs começa com uma chamada para getTab() e asDocumentTab() seguida por getBody(), porque o Body é um elemento principal que contém todos os outros elementos em uma guia, exceto o HeaderSection, FooterSection e qualquer Footnotes.

No entanto, há 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 em outros elementos. A árvore abaixo mostra quais elementos podem ser contidos por um determinado tipo de elemento.

Os elementos em negrito podem ser inseridos. Os elementos sem negrito só podem ser manipulados no lugar.

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 personalizado do Google Docs para cada um deles. Esse tipo de operação é frequentemente chamado de mesclagem de e-mails.

Há muitas maneiras de substituir o texto, mas a mais simples é o método replaceText() mostrado no exemplo abaixo. O replaceText oferece suporte à 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 documento do Google Docs. No mundo real, seria mais provável que você digitasse os marcadores no documento. A segunda função substitui os marcadores de posição por propriedades definidas no objeto client.

Ambas as funções usam os métodos getActiveDocument() e getActiveTab(), que se aplicam apenas a scripts criados em um documento do Documentos Google. Em um script independente, use DocumentApp.create(), openById() ou openByUrl(), combinados com Document.getTab().

Adicionar marcadores de posição

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().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().getActiveTab().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 os Documentos Google adicionando menus, caixas de diálogo e barras laterais. No entanto, um script só pode 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 seus Documentos Google. Para saber mais sobre como criar interfaces personalizadas para uma caixa de diálogo ou 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 do editor do Documentos Google.

Complementos para os Documentos Google

Os complementos são executados nos Documentos Google e podem ser instalados na loja de complementos do app. Se você desenvolveu um script para os Documentos Google e quer compartilhar com o mundo, o Apps Script permite publicar seu script como um complemento para que outros usuários possam instalá-lo na loja de complementos.

Para saber como criar um complemento para o Documentos Google, consulte Guia de início rápido para criar complementos do Documentos.

Gatilhos

Os scripts vinculados a um documento do Google podem usar um gatilho simples para responder ao evento onOpen do documento, que ocorre sempre que um usuário com acesso de edição ao documento o abre no Documentos do Google.

Para configurar o acionador, basta escrever uma função chamada onOpen(). Para conferir um exemplo desse acionador, consulte Menus personalizados no Google Workspace. Embora o acionador simples seja útil para adicionar menus, ele não pode usar nenhum serviço do Apps Script que exija autorização.