Ampliar o Documentos Google

O Google Apps Script permite que você crie e modifique 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 o Google Docs de duas maneiras: 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 puder ser vinculado a um documento, o que concede a ele a capacidade especial 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 arquivo do Documentos Google por meio do 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 desse parágrafo como título e anexa uma tabela com base nos valores em uma matriz bidimensional. O script também pode facilmente fazer essas mudanças em um documento existente, substituindo a chamada para DocumentApp.create() por DocumentApp.openById() ou openByUrl(). Para scripts criados em um documento (vinculado ao contêiner), 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 por elementos (como Paragraph ou Table) que geralmente 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, 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. A árvore abaixo mostra quais elementos podem ser contidos em um determinado tipo de elemento.

Os elementos mostrados em negrito podem ser inseridos. Elementos não negrito só podem ser manipulados no local.

Como substituir texto

O Apps Script costuma ser usado para substituir texto no 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 deles. Em geral, esse tipo de operação é chamado de mesclagem de e-mails.

Há muitas maneiras de substituir texto, mas o 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 arquivo do Documentos Google. No mundo real, seria mais provável que você digitasse os marcadores de posição no documento por conta própria. A segunda função substitui os marcadores pelas propriedades definidas no objeto client.

Ambas as funções usam o método getActiveDocument(), que só se aplica a scripts criados em um arquivo dos Documentos Google. Em scripts independentes, use DocumentApp.create(), openById() ou openByUrl().

Adicionar 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 personalizados e interfaces do usuário

Você pode personalizar os Documentos Google adicionando menus, caixas de diálogo e barras laterais. No entanto, um script só pode interagir com a IU da instância atual de um documento aberto e somente se o script estiver vinculado a ele.

Veja como adicionar menus personalizados e caixas de diálogo ao seu Documentos Google. Para saber mais sobre a criação de 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 do Documentos Google

Os complementos são executados no 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 publicá-lo como um complemento para que outros usuários possam instalá-lo na loja de complementos.

Para ver como você pode criar um complemento para o Documentos Google, consulte o guia de início rápido para criar complementos do Documentos.

Acionadores

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

Para configurar o gatilho, basta escrever uma função chamada onOpen(). Para ver um exemplo desse gatilho, 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.