Bibliotecas

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

Acessar uma biblioteca

Para incluir uma biblioteca no seu projeto, você precisa ter pelo menos o nível da visualização acesso a ele. Se você não é o autor da biblioteca que deseja incluir, entrar em contato com o autor e solicitar acesso.

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

Adicionar uma biblioteca ao seu projeto de script

1. À esquerda do editor do Apps Script, ao lado de "Bibliotecas", clique em "Adicionar um" biblioteca add.
2. No "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. 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 consulte a biblioteca. Por exemplo, se você defini-lo como Test, será possível chame um método dessa biblioteca da seguinte maneira: Test.libraryMethod().
6. Clique em Adicionar.

Usar uma biblioteca

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

Para abrir a documentação de referência de uma biblioteca incluída, siga estas etapas:

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

Remover uma biblioteca

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

Atualizar uma biblioteca

É possível mudar a versão da biblioteca ou atualizar 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 as etapas abaixo.

1. Criar uma implantação com controle de versão do seu script.
2. Compartilhe pelo menos o acesso no nível da visualização com todos os usuários em potencial da biblioteca.
3. Forneça a esses usuários o ID do script, que pode ser encontrado no Projeto de configuração settings.

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. Se você quiser que um ou mais métodos de seu script não fiquem visíveis (nem utilizável) para os usuários da sua biblioteca, é possível encerrar o nome do método com uma sublinhado. Por exemplo, myPrivateMethod_().
3. Somente 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 biblioteca, mas que não é acessível pelos usuários.

4. Se você quiser que os usuários da biblioteca usem o preenchimento automático do editor de script e a documentação gerada automaticamente, é necessário ter 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 quando você está trabalhando com bibliotecas: compartilhados e não compartilhados. Um recurso compartilhado significa que tanto a biblioteca quanto 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:

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 oferecer acesso aos recursos não compartilhados com funções explícitas que operam neles. Aqui está um exemplo de uma função que você incluiria da biblioteca para expor as propriedades de script:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

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

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

Recurso	Compartilhado*	Não compartilhado**	Observações
Bloquear			A mesma instância é visível para todos, inclusive os scripts quando criada no da biblioteca.
Propriedades do script			A mesma instância é visível para todos, inclusive os scripts quando criada no da biblioteca.
Cache			A mesma instância fica visível para todos, incluindo scripts, quando criada na biblioteca.
Gatilhos			Gatilhos simples criados na biblioteca não são acionados pelo script.
ScriptApp
UiApp
Propriedades do usuário
Gerador de registros e transcrição de execução
Sites, planilhas e outros contêineres			Uma chamada para getActive() retorna o contêiner do incluindo script.
MailApp e GmailApp
* Isso significa que a biblioteca não tem a própria instância do recurso e, em vez disso, usa o que foi criado pelo script que a invocou. ** Isso significa que a biblioteca tem uma instância própria do recurso/recurso e que todos os scripts que usam a biblioteca compartilhem e tenham 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.

Depurar uma biblioteca

Ao usar o depurador em um projeto que inclui uma biblioteca que você pode entrar em uma função da biblioteca incluída. O código aparece no depuração no modo somente leitura e na versão correta.