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
.Adicionar uma biblioteca ao seu projeto de script
- À esquerda do editor do Apps Script, ao lado de "Bibliotecas", clique em "Adicionar um" biblioteca .
- No "ID do script" , cole o ID do script da biblioteca.
- Clique em Pesquisar.
- Clique no menu suspenso Versão e selecione a versão da biblioteca. usar.
- Verifique se o "Identificador" padrão nome é aquela que você quer
usar com esta 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()
. - 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.
A documentação de referência de uma biblioteca incluída pode ser aberta seguindo estas etapas:
À esquerda do editor de script, ao lado do nome da biblioteca, clique em Mais
> Abra em uma nova guia.Remover uma biblioteca
À esquerda do editor de script, ao lado do nome da biblioteca, clique em Mais
> Remover > Remover biblioteca.Atualizar uma biblioteca
É possível 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 uma biblioteca, siga as etapas abaixo.
- Criar uma implantação com controle de versão do seu script.
- Compartilhe pelo menos o acesso no nível da 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 no Projeto de configuração .
Práticas recomendadas
Aqui estão algumas diretrizes a serem seguidas ao escrever uma biblioteca:
- Escolha um nome significativo para o projeto, já que ele é usado como o identificador padrão quando sua biblioteca é incluída por outras pessoas.
- 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_()
. - Somente propriedades globais enumeráveis são visíveis para usuários da biblioteca. Isso inclui a função
declarações, 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 em 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 um arquivo estilo JSDoc documentação 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. A diagrama a seguir ilustra um recurso compartilhado usando o exemplo de Propriedades do usuário:
Um recurso não compartilhado significa que tanto a biblioteca quanto o script que o incluiu acesso integrado apenas à própria instância do recurso. No entanto, uma biblioteca pode fornecem acesso a recursos não compartilhados com funções explícitas que operá-las. 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 é visível para todos, inclusive os scripts quando criada no da biblioteca. | ||
Gatilhos | Gatilhos simples criados na biblioteca não são acionados pelo script. | ||
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
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 nível de editor acesso 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 o depurador em modo somente leitura e na versão correta.