Menus personalizados no Google Workspace

Os scripts podem estender determinados produtos do Google adicionando elementos da interface do usuário que, quando clicados, executam uma função do Apps Script. O exemplo mais comum é executar um script em um item de menu personalizado nos Documentos, Planilhas, Apresentações ou Formulários Google, mas as funções de script também podem ser acionadas clicando em imagens e desenhos nas Planilhas Google.

Menus personalizados nos apps Documentos, Planilhas, Apresentações ou Formulários Google

O Apps Script pode adicionar novos menus nos apps Documentos, Planilhas, Apresentações ou Formulários Google, com cada item de menu vinculado a uma função em um script. Nos Formulários Google, os menus personalizados são visíveis apenas para um editor que abre o formulário para modificá-lo, não para um usuário que abre o formulário para responder.

Um script só pode criar um menu se estiver vinculado ao documento, à planilha ou ao formulário. Para mostrar o menu quando o usuário abrir um arquivo, escreva o código do menu em uma função onOpen().

O exemplo abaixo mostra como adicionar um menu com um item, seguido por um separador visual e um submenu que contém outro item. Nas Planilhas Google, a menos que você esteja usando a nova versão, é necessário usar a sintaxe addMenu() e não é possível usar submenus. Quando o usuário seleciona um item de menu, uma função correspondente abre uma caixa de diálogo alert. Para mais informações sobre os tipos de caixas de diálogo que você pode abrir, consulte o guia de caixas de diálogo e barras laterais.

function onOpen() {
  var ui = SpreadsheetApp.getUi();
  // Or DocumentApp, SlidesApp or FormApp.
  ui.createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addSeparator()
      .addSubMenu(ui.createMenu('Sub-menu')
          .addItem('Second item', 'menuItem2'))
      .addToUi();
}

function menuItem1() {
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp or FormApp.
     .alert('You clicked the first menu item!');
}

function menuItem2() {
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp or FormApp.
     .alert('You clicked the second menu item!');
}

Um documento, planilha, apresentação ou formulário só pode conter um menu com um nome específico. Se o mesmo script ou outro script adicionar um menu com o mesmo nome, o novo menu vai substituir o antigo. Os menus não podem ser removidos enquanto o arquivo está aberto, mas você pode escrever sua função onOpen() para pular o menu no futuro se uma determinada propriedade estiver definida.

Imagens e desenhos clicáveis nas Planilhas Google

Também é possível atribuir uma função do Apps Script a uma imagem ou desenho nas Planilhas Google, desde que o script esteja vinculado à planilha. O exemplo abaixo mostra como configurar isso.

1. Nas Planilhas Google, selecione o item de menu Extensões > Apps Script para criar um script vinculado à planilha.

2. Apague o código no editor de script (se houver algum) e cole o código abaixo.

     function showMessageBox() {
       Browser.msgBox('You clicked it!');
     }
   

3. Volte para as Planilhas e insira uma imagem ou um desenho selecionando Inserir > Imagem ou Inserir > Desenho.

4. Depois de inserir a imagem ou o desenho, clique nele. Um pequeno seletor de menu suspenso aparece no canto superior direito. Clique nele e escolha Atribuir script.

5. Na caixa de diálogo que aparece, digite o nome da função do Apps Script que você quer executar sem parênteses. Neste caso, showMessageBox. Clique em OK.

6. Clique na imagem ou no desenho novamente. A função agora é executada.