Bibliotecas

Uma biblioteca é um projeto de script cujas funções podem ser reutilizadas em outros scripts.

Um script que usa uma biblioteca não é executado tão rápido quanto se todo o código estivesse contido em um único projeto de script. Embora as bibliotecas possam tornar o desenvolvimento e a manutenção mais convenientes, use-as com moderação em projetos em que a velocidade é essencial. Devido a esse problema, o uso da biblioteca precisa ser limitado nos complementos do Google Workspace.

Acessar uma biblioteca

Para incluir uma biblioteca no seu projeto, é necessário ter pelo menos acesso de visualização a ela. Se você não for o autor da biblioteca que quer incluir, entre em contato com ele e peça acesso.

Você precisa do ID do script da biblioteca que quer incluir. Quando você tiver acesso à biblioteca, encontre o ID do script na página Configurações do projeto .

Adicionar uma biblioteca ao projeto de script

  1. À esquerda do editor do Apps Script, ao lado de "Bibliotecas", clique em Adicionar uma biblioteca .
  2. No campo "ID do script", cole o ID do script da biblioteca.
  3. Clique em Pesquisar.
  4. Clique no menu suspenso Versão e selecione a versão da biblioteca que você quer usar.
  5. Verifique se o nome padrão "Identifier" é o que você quer usar com essa biblioteca. Esse é o nome que seu script usa para se referir à biblioteca. Por exemplo, se você definir como Test, chame um método dessa biblioteca da seguinte maneira: Test.libraryMethod.
  6. Clique em Adicionar.

Usar uma biblioteca

Use a biblioteca incluída como se fosse um serviço padrão. Por exemplo, se Test for o identificador da sua biblioteca, digite Test imediatamente seguido por um ponto para ver a lista de métodos na biblioteca.

Abra a documentação de referência de uma biblioteca incluída seguindo estas etapas:

À esquerda do editor de script, ao lado do nome da biblioteca, clique em Mais > Abrir em uma nova guia.

Remover uma biblioteca

À esquerda do editor de script, ao lado do nome da biblioteca, clique em Mais > Remover > Remover biblioteca.

Se uma biblioteca for excluída pelo autor, você ainda precisará removê-la da sua lista de bibliotecas incluídas.

Atualizar uma biblioteca

Mude a versão da biblioteca ou atualize o identificador dela.

  1. À esquerda do editor, em "Bibliotecas", clique no nome da biblioteca.
  2. Faça as mudanças e clique em Salvar.

Criar e compartilhar uma biblioteca

Para usar e compartilhar seu projeto de script como uma biblioteca, siga estas etapas:

  1. Crie uma implantação versionada do seu script.
  2. Compartilhe pelo menos o acesso de visualização com todos os usuários em potencial da biblioteca.
  3. Dê a esses usuários o ID do script, que pode ser encontrado na página Configurações do projeto .

Práticas recomendadas

Confira algumas diretrizes a seguir ao escrever uma biblioteca:

  1. Escolha um nome significativo para o projeto, já que ele é usado como o identificador padrão quando sua biblioteca é incluída por outras pessoas.
  2. Para que um ou mais métodos do script não fiquem visíveis (nem utilizáveis) para os usuários da biblioteca, termine o nome do método com um sublinhado. Por exemplo, myPrivateMethod_.
  3. Apenas propriedades globais enumeráveis ficam visíveis para os usuários da biblioteca. Isso inclui declarações de função, variáveis criadas fora de uma função com var e propriedades definidas explicitamente no objeto global. Por exemplo, Object.defineProperty() com enumerable definido como false cria um símbolo que pode ser usado na sua biblioteca, mas que não é acessível aos usuários.

  4. Para garantir que os usuários da biblioteca possam usar o preenchimento automático do editor de script e a documentação gerada automaticamente, inclua a documentação no estilo JSDoc para todas as funções. Veja um exemplo:

    /**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Escopo de recursos

Há dois tipos de recursos ao trabalhar com bibliotecas: compartilhados e não compartilhados. Um recurso compartilhado significa que a biblioteca e o script de inclusão têm acesso integrado à mesma instância do recurso. O diagrama a seguir ilustra um recurso compartilhado usando o exemplo de propriedades do usuário:

Recurso compartilhado

Um recurso não compartilhado significa que a biblioteca e o script de inclusão têm acesso integrado apenas à instância do recurso. No entanto, uma biblioteca pode fornecer acesso aos recursos não compartilhados com funções explícitas que operam neles. Confira um exemplo de função que você incluiria na biblioteca para expor as propriedades de script dela:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

O diagrama a seguir ilustra um recurso não compartilhado usando o exemplo de propriedades de script:

Exemplo de um recurso não compartilhado

Esta tabela lista os recursos compartilhados e não compartilhados para sua referência:

Recurso Compartilhada* Não compartilhado** Observações
Bloquear A mesma instância fica visível para todos, incluindo scripts, quando criada na biblioteca.
Propriedades do script A mesma instância fica visível para todos, incluindo scripts, quando criada na biblioteca.
Cache A mesma instância fica visível para todos, incluindo scripts, quando criada na biblioteca.
Gatilhos Os acionadores simples criados na biblioteca não são acionados pelo script incluído.
ScriptApp
UiApp
Propriedades do usuário
Logger e transcrição de execução
Sites, Planilhas e outros contêineres Uma chamada para getActive retorna o contêiner do incluindo o script.
MailApp e GmailApp
* Isso significa que a biblioteca não tem uma instância própria do recurso e, em vez disso, está usando a criada pelo script que a invocou.
** Isso significa que a biblioteca tem a própria instância do recurso/funcionalidade e que todos os scripts que usam a biblioteca compartilham e têm acesso a essa mesma instância.

Testar uma biblioteca

Para testar sua biblioteca, use a implantação principal. Qualquer pessoa com acesso de editor ao script pode usar a implantação principal.

Você ainda precisa ter pelo menos uma versão da biblioteca salva.

Depurar uma biblioteca

Ao depurar um script que inclui uma biblioteca, não é possível entrar no código da biblioteca nem definir pontos de interrupção nela. Se você tentar entrar em uma função de biblioteca no modo de depuração, o depurador vai pular a função e passar para a próxima linha no script de chamada.

Usar HEAD (modo de desenvolvimento) para a versão da biblioteca não permite entrar na biblioteca nem atingir pontos de interrupção nela.

Para depurar o código da biblioteca, use um dos seguintes métodos:

  • Depurar no projeto da biblioteca: abra o projeto de script da biblioteca no editor do Apps Script. Para testar funções de biblioteca com argumentos específicos, crie uma função "test" temporária no projeto da biblioteca que chame as funções da biblioteca e execute essa função de teste no modo de depuração.
  • Registro: use console.log() nas funções da biblioteca para gerar informações nos registros de execução. Quando a biblioteca é chamada por outro script, esses registros aparecem nos registros de execução do script de chamada.