Scripts vinculados a contêineres

Um script é vinculado a um arquivo dos apps Planilhas, Documentos, Apresentações ou Formulários Google se ele foi criado com base nesse documento em vez de um script independente. O arquivo a que um script vinculado está anexado é chamado de "contêiner". Os scripts vinculados geralmente se comportam como scripts independentes, exceto que eles não aparecem no Google Drive, não podem ser separados do arquivo a que estão vinculados e ganham alguns privilégios especiais sobre o arquivo principal.

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

Observação: os scripts vinculados são efetivamente 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 Google Documentos, Planilhas ou Apresentações, abra um documento 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 Google Formulários, abra um formulário e clique em Mais > Editor de scripts. 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 scripts vinculados se refiram ao arquivo principal sem mencionar o ID do arquivo.
• O getUi permite que scripts vinculados acessem a interface do usuário do arquivo principal para adicionar menus, caixas de diálogo e barras laterais personalizados.
• Nas Planilhas Google, getActiveSheet(), getActiveRange() e getActiveCell() permitem que o script determine a planilha atual do usuário, o intervalo de células selecionado ou a célula individual selecionada. setActiveSheet(sheet) e setActiveRange(range) permitem que o script mude essas seleções.
• Nos Documentos Google, getActiveTab(), getCursor() e getSelection() permitem que o script determine a guia atual do usuário, a posição do cursor ou o texto selecionado. setActiveTab(tabId), setCursor(position) e setSelection(range) permitem que o script mude essas seleções.

Para mais informações, consulte o guia para estender as Planilhas Google ou o guia para estender o Google Docs.

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

Menus, caixas de diálogo e barras laterais personalizadas

Os scripts vinculados podem personalizar os apps Planilhas, Documentos e 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 pode afetar a interface de outro.

Os complementos também podem adicionar menus, caixas de diálogo e barras laterais personalizados. Recomendamos desenvolver complementos usando scripts independentes.

Gatilhos

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 de edição. Como todos os tipos de scripts, eles também podem usar gatilhos instaláveis.

Funções personalizadas

Uma função personalizada é uma função em um script vinculado às 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, mas 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 a ele. Os colaboradores que têm apenas acesso de leitura não podem abrir o editor de scripts. No entanto, se eles fizerem uma cópia do arquivo de contêiner, se tornarão proprietários 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 do contêiner. O proprietário do contêiner assume a propriedade de um novo projeto de script, independente de quem o criou.