Extensão dos Documentos Google

O Google Apps Script permite criar e modificar programaticamente documentos do Google, 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: qualquer script poderá criar ou modificar um documento se o usuário tiver as permissões adequadas, e um script também poderá ser vinculado a um documento, o que dá a ele habilidades especiais para 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, 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 novo documento no Google Drive do usuário, insere um parágrafo que contém o mesmo texto que o nome do documento, define o estilo como título e anexa uma tabela com base nos valores de uma matriz bidimensional. O script pode fazer essas alterações com a mesma facilidade em um documento existente, substituindo a chamada para DocumentApp.create() por DocumentApp.openById() ou openByUrl(). Para scripts criados dentro de um documento (vinculado 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, é composto por elementos (como uma 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 Body é um elemento principal que contém todos os outros elementos, exceto HeaderSection, FooterSection e 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 sem negrito só podem ser manipulados no lugar.

Substituir texto

O Apps Script costuma ser usado para substituir texto nos Documentos Google. Digamos que você tenha uma planilha cheia de informações de clientes e queira gerar um Documentos Google personalizado para cada cliente. Esse tipo de operação é geralmente chamado de mesclagem de e-mails.

Há muitas maneiras de substituir 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 marcador de posição a um documento Google. No mundo real, seria mais provável que você mesmo digite os marcadores no documento. A segunda função substitui os marcadores por propriedades definidas no objeto client.

Observe que ambas as funções usam o método getActiveDocument(), que só se aplica a scripts criados dentro de um documento 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. No entanto, lembre-se de que um script só pode interagir com a IU da instância atual de um documento aberto e apenas se ele 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ê está planejando 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 de arquivos Google.

Complementos para o Documentos Google

Os complementos são executados no Documentos Google e podem ser instalados na loja de complementos desse produto. Se você desenvolveu um script para o Documentos Google e quer compartilhá-lo com outras pessoas, o Apps Script permite publish um 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 documento Google podem usar um acionador simples para responder ao evento onOpen do documento. Isso ocorre sempre que um usuário com acesso para edição abre o arquivo 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 acionador simples seja útil para adicionar menus, ele não pode usar serviços do Apps Script que exigem autorização.