Menus personalizados no Google Workspace

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

Menus personalizados no Google Docs, Planilhas, Apresentações ou Formulários

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

Somente scripts vinculados podem criar menus. Para mostrar o menu quando o usuário abrir um arquivo, escreva o código do menu em uma função onOpen.

O exemplo a seguir mostra como adicionar um menu com um item, seguido por um separador visual e um submenu que contém outro item. Quando o usuário seleciona um dos itens de menu, uma função correspondente abre uma caixa de diálogo de alerta. Para mais informações sobre os tipos de caixas de diálogo que podem ser abertas, consulte o guia de caixas de diálogo e barras laterais.

function onOpen() {
  const 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, uma planilha, uma apresentação ou um formulário só pode conter um menu com um determinado nome. Se o mesmo script ou outro script adicionar um menu com o mesmo nome, o novo menu vai substituir o antigo. Não é possível remover menus 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.

Os complementos do editor também podem ter itens de menu, mas usam regras especiais para definição.

Imagens e desenhos clicáveis nas Planilhas Google

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

1. No app Planilhas, 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() {
  SpreadsheetApp.getUi().alert('You clicked it!');
}

1. Volte para as Planilhas e insira uma imagem ou um desenho selecionando Inserir > Imagem ou Inserir > Desenho.
2. Depois de inserir a imagem ou o desenho, clique nele. Um pequeno menu suspenso aparece no canto superior direito. Clique nele e escolha Atribuir script.
3. 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.
4. Clique na imagem ou no desenho de novo. A função é executada.

A execução do script só é acionada ao clicar na imagem ou desenhar em um navegador da Web. O script não é executado se a imagem ou o desenho for clicado em dispositivos móveis.