Ampliar o Documentos Google

Com o Google Apps Script, é possível criar e modificar documentos 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 o Documentos de duas maneiras gerais: qualquer script pode criar ou modificar um documento se o usuário tiver as permissões adequadas para ele. Além disso, um script 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, clique em Extensões > Apps Script.

Em qualquer um dos casos, é possível interagir com um documento do Google Docs usando o serviço de documentos do Apps Script, como demonstra o exemplo a seguir.

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 anterior cria um novo documento no Google Drive do usuário, 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 cabeçalho e anexa uma tabela com base nos valores em uma matriz bidimensional. O script também pode fazer essas mudanças em um documento atual 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

Na perspectiva do Apps Script, um documento do Google Docs é estruturado de maneira muito parecida com um documento HTML. Ou seja, um documento é composto por um ou mais objetos Tab, cada um deles 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, o 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 a seguir 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 no Documentos. Suponha que você tenha uma planilha cheia de informações de clientes e queira gerar um documento personalizado para cada um deles. Esse tipo de operação é chamado de mala direta.

É possível substituir texto usando o método replaceText, que é compatível com a maioria dos recursos de expressão regular do JavaScript. No exemplo a seguir, a primeira função adiciona texto de marcador de posição ao documento, e a segunda substitui esse texto por propriedades de um objeto client.

Essas duas funções usam os métodos getActiveDocument e getActiveTab, que só se aplicam a scripts criados em um documento do Google Docs. Em um script independente, use DocumentApp.create, openById ou openByUrl, combinado com Document.getTab.

Adicionar alguns marcadores de posição

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Substitua 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

É possível personalizar o app Documentos adicionando menus personalizados, caixas de diálogo e barras laterais. Um script só pode interagir com a interface do documento a que está vinculado.

Para saber mais sobre como criar interfaces personalizadas com HTML e CSS, consulte o guia do serviço HTML. Se você planeja publicar sua interface como um complemento, siga o guia de estilo para garantir que a aparência seja consistente com o editor do Google Docs.

Complementos para o Google Docs

Os complementos são executados no Google Docs e podem ser instalados na loja de complementos do Docs. Se você desenvolveu um script para o Google Docs 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 criar um complemento do Documentos, consulte o 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 abre o arquivo nos Documentos.

Para configurar o gatilho, escreva uma função chamada onOpen. Para ver um exemplo desse gatilho, consulte Menus personalizados no Google Workspace. Embora o gatilho seja útil para adicionar menus, ele não pode usar nenhum serviço do Apps Script que exija autorização.