Bibliotecas

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

Aviso: um script que usa uma biblioteca não é executado tão rapidamente como seria se todo o código estivesse contido em um único projeto de script. As bibliotecas podem tornar o desenvolvimento e a manutenção mais convenientes, mas use-as com moderação em projetos em que a velocidade é essencial. Devido a esse problema, o uso da biblioteca precisa ser limitado em complementos.

Ter acesso a uma biblioteca

Para incluir uma biblioteca no projeto, você precisa ter pelo menos acesso de visualização. Se você não é o autor da biblioteca que quer incluir, entre em contato com o autor e solicite acesso.

É necessário o ID do script da biblioteca que você quer incluir. Quando você tiver acesso à biblioteca, poderá encontrar 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 da biblioteca.
3. Clique em Pesquisar.
   Se você encontrar um erro, verifique se tem pelo menos acesso no nível da visualização ao projeto que está tentando incluir.
4. Clique no menu suspenso Versão e selecione a versão da biblioteca a ser usada.
5. Verifique se o nome do "Identificador" padrão é o que você quer usar com essa biblioteca. Esse é o nome que o script usa para se referir à biblioteca. Por exemplo, se você a definir como Test, poderá chamar um método dessa biblioteca desta maneira: Test.libraryMethod().
   Se você usar um nome de identificador que corresponda ao nome de um serviço já existente, como MailApp, ou uma biblioteca adicionada anteriormente, a biblioteca adicionada mais recentemente modificará o serviço ou a biblioteca existente.
6. Clique em Adicionar.

Usar uma biblioteca

Use a biblioteca incluída como você usaria 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.

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 > Abrir em uma nova guia.

Remover uma biblioteca

À esquerda do editor de script, ao lado do nome da biblioteca, clique em More (Mais) > Remove > Remove library (Remover biblioteca).

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

.

Atualizar uma biblioteca

Você pode 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. Crie uma implantação com controle de versão do script.
2. Compartilhe pelo menos o acesso no nível da vista com todos os usuários em potencial da biblioteca.
3. Forneça a esses usuários o ID do script, que pode ser encontrado na página Configurações do projeto.

Práticas recomendadas

Aqui estão algumas diretrizes a serem seguidas 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 do seu script não fiquem visíveis (nem utilizáveis) para os usuários da biblioteca, encerre 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 explicitamente definidas no objeto global. Por exemplo, Object.defineProperty() com enumerable definido como false cria um símbolo que pode ser usado na sua biblioteca, mas esse símbolo não pode ser acessado 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, será necessário ter uma documentação no estilo JSDoc para todas as suas funções. Confira 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

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

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

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

No diagrama a seguir, ilustramos 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
Cadeado			A mesma instância fica visível para todos os scripts, quando criada na biblioteca.
Propriedades do script			A mesma instância fica visível para todos os scripts, quando criada na biblioteca.
Cache			A mesma instância fica visível para todos os scripts, quando criada na biblioteca.
Gatilhos			Acionadores simples criados na biblioteca não são acionados pelo script de inclusão.
ScriptApp
UiApp
Propriedades do usuário
Registrador e transcrição de execução
Sites, Planilhas e outros contêineres			Uma chamada para getActive() retorna o contêiner do script incluído.
MailApp e GmailApp
* Isso significa que a biblioteca não tem uma instância própria do recurso/recurso e, em vez disso, usa a que foi criada 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 compartilham e têm acesso a essa mesma instância.

Testar uma biblioteca

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

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

Depurar uma biblioteca

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