Uma biblioteca é um projeto de script cujas funções podem ser reutilizadas em outros scripts.
Ter acesso a uma biblioteca
Para incluir uma biblioteca no seu projeto, você precisa ter pelo menos acesso no nível da visualização. Se você não for o autor da biblioteca que quer incluir, entre em contato com o autor e solicite acesso.
Você precisa do ID do script da biblioteca que 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
- À esquerda do editor do Apps Script, ao lado de "Bibliotecas", clique em Adicionar uma biblioteca .
- No campo "ID do script", cole o ID da biblioteca.
- Clique em Pesquisar.
- Clique no menu suspenso Version e selecione a versão da biblioteca que você quer usar.
- Verifique se o nome do "Identificador" padrão é o que você quer
usar com essa biblioteca. Esse é o nome que seu script usa para
se referir à biblioteca. Por exemplo, se você configurá-la como
Test
, poderá chamar um método dessa biblioteca da seguinte maneira:Test.libraryMethod()
. - Clique em Adicionar.
Usar uma biblioteca
Use a biblioteca incluída como faria com um serviço padrão. Por
exemplo, se Test
for o identificador da sua biblioteca, digite
Test
imediatamente após um ponto para ver a lista de métodos na biblioteca.
A documentação de referência de uma biblioteca incluída pode ser aberta seguindo estas etapas:
À esquerda do editor de scripts, ao lado do nome da biblioteca, clique em Mais
> Abrir em uma nova guia.Remover uma biblioteca
À esquerda do editor de scripts, ao lado do nome da biblioteca, clique em Mais
> Remover > Remover biblioteca.Atualizar uma biblioteca
Você pode mudar a versão da biblioteca ou atualizar o identificador dela.
- À esquerda do editor, em "Bibliotecas", clique no nome da biblioteca.
- Faça as mudanças e clique em Salvar.
Criar e compartilhar uma biblioteca
Para usar e compartilhar seu projeto de script como biblioteca, siga as etapas abaixo.
- Crie uma implantação com controle de versão do script.
- Compartilhe pelo menos o nível de visualização com todos os usuários em potencial da biblioteca.
- Forneça a esses usuários o ID do script, que pode ser encontrado na página Configurações do projeto .
Práticas recomendadas
Veja algumas diretrizes a serem seguidas ao escrever uma biblioteca:
- Escolha um nome significativo para o projeto, porque ele é usado como identificador padrão quando sua biblioteca é incluída por outras pessoas.
- 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_()
. - Somente propriedades enumeráveis globais podem ser vistas pelos 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()
comenumerable
definido comofalse
cria um símbolo que pode ser usado na sua biblioteca, mas esse símbolo não pode ser acessado pelos usuários. 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 a documentação no estilo JSDoc para todas as suas 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 do recurso
Há dois tipos de recursos quando você está trabalhando com bibliotecas: compartilhada e não compartilhada. Um recurso compartilhado significa que a biblioteca e o script incluídos 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 somente à instância do recurso. No entanto, uma biblioteca pode fornecer acesso aos recursos não compartilhados por ter funções explícitas que funcionam neles. Veja um exemplo de uma função que você incluiria na 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 das propriedades de script:
Esta tabela lista os recursos compartilhados e não compartilhados para sua referência:
Recurso | Compartilhada* | Não compartilhado** | Observações |
---|---|---|---|
Cadeado | A mesma instância fica visível para todos, inclusive para os scripts criados na biblioteca. | ||
Propriedades do script | A mesma instância fica visível para todos, inclusive para os scripts criados na biblioteca. | ||
Cache | A mesma instância fica visível para todos, inclusive para os scripts criados na biblioteca. | ||
Acionadores | Gatilhos simples criados na biblioteca não são acionados pelo script de inclusão. | ||
Aplicativo de script | |||
App de IU |
|
||
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 a própria instância do
recurso/recurso e, em vez disso, está usando a instância criada pelo script
que a invocou.
** Isso significa que a biblioteca tem a própria instância 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 sua biblioteca, use a implantação principal. Qualquer pessoa que tenha 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, você pode entrar em uma função da biblioteca incluída. O código é exibido no depurador no modo somente visualização e na versão correta.