Extensão dos Documentos Google

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 do Google Docs através Apps Script 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 o 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. A 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() e Document.getActiveTab().

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 Objetos Tab, cada um contendo elementos (como uma Paragraph ou Table) que geralmente contêm outras os elementos. A maioria dos scripts que modificam um documento do Google Docs 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.

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. A a segunda função substitui os espaços reservados pelas propriedades definidas na client.

Observe que ambas as funções usam o getActiveDocument() e getActiveTab() métodos, que só se aplicam a scripts criados dentro de um documento do Google Docs; em um script independente, use DocumentApp.create(), openById(), ou openByUrl(), combinado com Document.getTab(), como alternativa.

Adicione 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}');
}

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 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 e o 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.