Macros do Planilhas Google

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

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

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

Como criar macros no Apps Script

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

Também é possível criar macros no editor do Apps Script seguindo estas etapas:

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

Edição de 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 no arquivo de projeto que contém a função de macro.
  3. Edite a função da macro para alterar o comportamento dela.
  4. Salve o projeto de script. Depois disso, a macro vai ficar disponível para uso na planilha.
  5. Teste a função da macro na página para verificar se ela funciona conforme o esperado.

Importação de funções como macros

Se já houver um script vinculado a uma página, você poderá import uma função no script como uma nova macro e atribuir um atalho de teclado a ela. Para fazer isso, edite o arquivo de manifesto e adicione outro elemento à propriedade sheets.macros[] (link em inglês).

Como alternativa, siga estas etapas para importar uma função como macro da interface 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 na lista a função que você acabou de importar. 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 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 dela.

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

Consulte o recurso de manifesto de macro do Planilhas para mais detalhes sobre como esses manifestos são construídos.

Práticas recomendadas

Ao criar ou gerenciar macros no Apps Script, é recomendável seguir as 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 que uma macro realiza.
  2. As macros são mais adequadas para operações de rotina 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 macro precisam ser únicos, e uma determinada página só pode ter dez macros com atalhos por vez. Outras macros só podem ser executadas 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 selecionando primeiro o intervalo completo e, em seguida, ativando a macro. Isso significa que muitas vezes não é necessário criar macros que dupliquem 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 as 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 serão ignoradas se estiverem definidas em um script independente ou app da Web.

Definir macros nos complementos das Planilhas Google

Não é possível distribuir definições de macro usando um complemento das Planilhas Google. Todas as definições de macro em um projeto de complemento das Planilhas sã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 apenas um recurso do Planilhas Google e não existem nos Documentos, Formulários e Apresentações Google.