Scripts vinculados a contêineres

Um script será vinculado a um arquivo do Planilhas, Documentos, Apresentações ou Formulários Google se tiver sido criado a partir desse documento, e não como um script autônomo. O arquivo ao qual um script vinculado está anexado é chamado de "contêiner". Os scripts vinculados geralmente se comportam como scripts independentes, exceto que não aparecem no Google Drive, não podem ser desanexados do arquivo a que estão vinculados e recebem alguns privilégios especiais sobre o arquivo pai.

Os scripts também podem ser vinculados ao Google Sites, mas eles quase sempre são implantados como apps da Web. Os scripts vinculados ao Planilhas, Documentos, Apresentações ou Formulários Google também podem se tornar apps da Web, embora isso não seja comum.

Observação :na verdade, os scripts vinculados são complementos não publicados que funcionam apenas para o arquivo a que estão vinculados.

Criar um script vinculado

Documentos, Planilhas ou Apresentações Google

Para criar um script vinculado no Documentos, Planilhas ou Apresentações Google, abra um arquivo no Documentos, uma planilha no Planilhas ou uma apresentação no Apresentações e clique em Extensões > Apps Script. Para reabrir o script no futuro, faça o mesmo ou abra o script no painel do Apps Script.

Formulários Google

Para criar um script vinculado no Formulários Google, abra um formulário e clique em Mais > Editor de script. Para reabrir o script no futuro, faça o mesmo ou abra o script no painel do Apps Script.

Observação: a ferramenta clasp não pode criar scripts vinculados, mas pode cloná-los e editá-los.

Métodos especiais

Os scripts vinculados podem chamar alguns métodos que os scripts independentes não podem:

• getActiveSpreadsheet(), getActiveDocument(), getActivePresentation() e getActiveForm() permitem que os scripts vinculados consultem o arquivo pai sem se referir ao ID do arquivo.
• O getUi permite que scripts vinculados acessem a interface do usuário do arquivo pai para adicionar menus, caixas de diálogo e barras laterais personalizados.
• No Planilhas Google, getActiveSheet(), getActiveRange() e getActiveCell() permitem que o script determine a planilha atual, o intervalo de células ou a célula individual selecionada. setActiveSheet(sheet) e setActiveRange(range) permitem que o script altere essas seleções.
• No Documentos Google, getCursor() e getSelection() permitem que o script determine a posição do cursor do usuário ou do texto selecionado. setCursor(position) e setSelection(range) permitem que o script altere esses locais.

Para mais informações, consulte o guia sobre como estender o Planilhas Google ou o guia para estender o Documentos Google.

Observação: esses métodos estão disponíveis apenas para scripts vinculados executados no editor de scripts, nos itens de menu, nas caixas de diálogo, nas barras laterais ou nos acionadores. Quando um script vinculado é executado como um app da Web ou por meio da API Apps Script, esses métodos não estão disponíveis.

Menus, caixas de diálogo e barras laterais personalizados

Os scripts vinculados podem personalizar o Planilhas, o Documentos e o Formulários Google adicionando menus personalizados e caixas de diálogo ou barras laterais. No entanto, um script só pode interagir com a interface do usuário da instância atual de um arquivo aberto. Ou seja, um script vinculado a um documento não afeta a interface do usuário de outro documento.

Os complementos também podem incluir menus, caixas de diálogo e barras laterais personalizadas. É recomendável desenvolver complementos usando scripts independentes.

Complementos

Os complementos são executados no Gmail, no Planilhas, no Documentos, no Apresentações e no Formulários Google. Se você desenvolveu um script vinculado ou independente e quer compartilhá-lo com o mundo todo, o Apps Script permite publicá-lo como um complemento para que outros usuários possam instalá-lo a partir da loja de complementos.

Acionadores

Os scripts vinculados podem usar acionadores simples, como a função especial onOpen(), que é executada automaticamente sempre que um arquivo é aberto por um usuário com acesso para editar. Como todos os tipos de scripts, eles também podem usar acionadores instaláveis.

Funções personalizadas

Uma função personalizada é uma função em um script vinculado ao Planilhas Google que você chama diretamente de uma célula usando a sintaxe =myFunctionName(). As funções personalizadas são semelhantes às centenas de funções integradas do Planilhas, como AVERAGE ou SUM, exceto pelo fato de que você define o comportamento da função personalizada.

Acesso a scripts vinculados

Somente usuários com permissão para editar um contêiner podem executar o script vinculado. Os colaboradores que só têm acesso para visualização não podem abrir o editor de scripts. No entanto, se fizerem uma cópia do arquivo de contêiner, eles se tornarão o proprietário da cópia e poderão ver e executar uma cópia do script.

Para saber como compartilhar o arquivo de contêiner de um script, consulte Compartilhar arquivos do Google Drive.

Todos os scripts vinculados a contêineres usam a mesma lista de acesso de proprietário, leitor e editor definida para o arquivo de contêiner. O proprietário do contêiner assume a propriedade de um novo projeto de script, independentemente de quem o criou.