Macros do Planilhas Google

Com o Planilhas Google, é possível gravar macros que duplicam uma série específica de interações da IU que você define. Depois de gravar uma macro, você pode vinculá-la a um atalho de teclado no formato Ctrl+Alt+Shift+Number. É possível usar esse atalho para executar rapidamente as etapas exatas da macro novamente, normalmente em um lugar diferente ou em dados diferentes. Também é possível ativar a macro no menu Extensões > Macros do Planilhas Google.

Quando você grava uma macro, o Planilhas Google cria automaticamente uma função do Apps Script (a função da macro) que replica as etapas da macro. A função da macro é adicionada a um projeto do Apps Script vinculado à planilha, em um arquivo chamado macros.gs. Caso já exista um arquivo de projeto vinculado à página com esse nome, a função da macro será anexada a ele. O Planilhas Google também atualiza automaticamente o manifesto do projeto de script, registrando o nome e o atalho de teclado atribuídos à macro.

Como todas as macros registradas são definidas inteiramente no Apps Script, é possível editá-las diretamente no editor do Apps Script. É possível até mesmo gravar macros do zero no Apps Script ou transformar funções que você já gravou em macros.

Como criar macros no Apps Script

Você pode usar funções escritas no Apps Script e usá-las como funções macro. A maneira mais fácil de fazer isso é importando uma função existente do editor do Planilhas Google.

Como alternativa, é possível criar macros no editor do Apps Script seguindo estas etapas:

  1. Na IU do Planilhas Google, selecione Extensions > Apps Script para abrir o script vinculado à planilha no editor do AApps Script.
  2. Escreva a função da macro. As funções de macro não precisam aceitar argumentos nem retornar valores.
  3. Edite o manifesto do script para criar a macro e vinculá-la à função da macro. Atribua um atalho e um nome exclusivos a ele.
  4. Salve o projeto de script. A macro estará disponível para uso na planilha.
  5. Teste a função da macro na página para verificar se ela funciona conforme o esperado.

Como editar macros

Para editar macros anexadas a uma página, faça o seguinte:

  1. Na IU do Planilhas Google, selecione Extensões > Macros > Gerenciar macros.
  2. Encontre a macro que você quer editar e selecione > Editar macro. Isso abre o editor do Apps Script para o arquivo de projeto que contém a função da macro.
  3. Edite a função da macro para alterar o comportamento dela.
  4. Salve o projeto de script. A macro estará disponível para uso na planilha.
  5. Teste a função da macro na página para verificar se ela funciona conforme o esperado.

Como importar funções como macros

Se já houver um script vinculado a uma página, importe uma função no script como uma nova macro e atribua a ela um atalho de teclado. Para isso, edite o arquivo de manifesto e adicione outro elemento à propriedade sheets.macros[].

Como alternativa, siga estas etapas para importar uma função como uma macro da IU do Planilhas:

  1. Na IU do Planilhas Google, selecione Extensões > Macros > Importar.
  2. Selecione uma função na lista apresentada e clique em Adicionar função.
  3. Selecione para fechar a caixa de diálogo.
  4. Selecione Extensões > Macros > Gerenciar macros.
  5. Localize a função que você acabou de importar na lista. Atribua um atalho de teclado exclusivo à macro. Também é possível alterar o nome da macro aqui. O padrão é o nome da função.
  6. Clique em Atualizar para salvar a configuração da macro.

Estrutura do manifesto para macros

O snippet de exemplo do arquivo de manifesto a seguir mostra a seção de um manifesto que define as macros do Planilhas Google. A seção sheets do manifesto define o nome e o atalho de teclado atribuídos à macro e o nome da função da macro.

  {
    ...
    "sheets": {
      "macros": [{
        "menuName": "QuickRowSum",
        "functionName": "calculateRowSum",
        "defaultShortcut": "Ctrl+Alt+Shift+1"
      }, {
        "menuName": "Headerfy",
        "functionName": "updateToHeaderStyle",
        "defaultShortcut": "Ctrl+Alt+Shift+2"
      }]
    }
  }

Consulte o guia Estrutura do manifesto para mais detalhes sobre como os manifestos do Apps Script são criados. As seções do Planilhas e da Macro descrevem os campos que definem as macros do Planilhas.

Práticas recomendadas

Ao criar ou gerenciar macros no Apps Script, é recomendável aderir às diretrizes a seguir.

  1. As macros têm melhor desempenho quando são leves. Sempre que possível, limite o número de ações realizadas por uma macro.
  2. As macros são mais adequadas para operações de gravação que precisam ser repetidas com frequência com pouca ou nenhuma configuração. Para outras operações, considere usar um item de menu personalizado.
  3. Lembre-se sempre de que os atalhos de teclado de macros precisam ser exclusivos, e uma página pode ter apenas dez macros com atalhos por vez. Qualquer macro adicional só pode ser executada no menu Extensões > Macros.
  4. As macros que fazem alterações em uma única célula podem ser aplicadas a um intervalo de células. Para isso, selecione o intervalo completo e, em seguida, ative a macro. Isso significa que geralmente é desnecessário criar macros que duplicam a mesma operação em um intervalo predefinido de células.

O que não é possível fazer

Há algumas restrições sobre o que você pode fazer com macros:

Usar macros fora dos scripts vinculados

As macros são definidas em scripts vinculados a Planilhas Google específicas. As definições de macro são ignoradas se definidas em um script autônomo ou app da Web.

Definir macros nos complementos do Planilhas

Não é possível distribuir definições de macro usando um complemento do Planilhas. Todas as definições de macro em um projeto de complemento do Planilhas serão ignoradas pelos usuários desse complemento.

Distribuir macros em bibliotecas de script

Não é possível distribuir definições de macro usando as bibliotecas do Apps Script.

Usar macros fora do Planilhas Google

As macros são um recurso do Planilhas Google e não existem no Documentos, Formulários ou Apresentações Google.