Macros ou funções de IA? Entendendo as ferramentas do ONLYOFFICE

O ONLYOFFICE oferece maneiras poderosas de automatizar seu trabalho com documentos usando macros e funções de IA — ajudando você a economizar tempo, reduzir o esforço manual e trabalhar com mais eficiência.

Ambos ajudam você a trabalhar de forma mais rápida e inteligente, mas funcionam de maneira diferente e atendem a necessidades diferentes. Seja você um desenvolvedor criando soluções personalizadas ou apenas alguém que deseja trabalhar com mais eficiência, este guia ajudará você a escolher a ferramenta certa para suas necessidades.

Compreender os conceitos básicos

O que são macros do ONLYOFFICE?

As macros do ONLYOFFICE são pequenos scripts que automatizam tarefas repetitivas em documentos, planilhas e apresentações. Elas utilizam JavaScript e o Office API, permitindo que você formate conteúdo, atualize dados e crie fluxos de trabalho personalizados diretamente no editor.

Como usar macros:

1. Abra a guia Exibir e clique em Macros.
2. Escreva código JavaScript usando o Office API
3. Clique em Executar para executar a macro.
4. O script manipula o documento diretamente

Observação! Desde a versão 7.1, as macros são executadas em modo estrito. Isso significa que você deve declarar todas as variáveis com let ou const antes de usá-las. Não é possível usar as funções window, document ou alert.

Exemplo: Linhas da tabela de cores

(function () {
  let worksheet = Api.GetActiveSheet();
  for (let i = 1; i < 200; i += 2) {
    let rowOdd = i,
      rowEven = i + 1;
    worksheet.GetRange(
      "A" + rowOdd + ":S" + rowOdd).SetFillColor(Api.CreateColorFromRGB(138, 181, 155)
      );
    worksheet.GetRange(
      "A" + rowEven + ":S" + rowEven).SetFillColor(Api.CreateColorFromRGB(216, 227, 220)
      );
  }
})();

Esta macro colore 200 linhas alternadamente em menos de um segundo — uma tarefa que levaria algum tempo para ser feita manualmente.

O que são as funções de IA do ONLYOFFICE?

As funções de IA conectam o ONLYOFFICE a modelos de IA como o ChatGPT. Elas permitem que você execute ações em documentos com base em IA usando prompts, para que o editor possa realizar operações automatizadas com base na sua solicitação. As funções de IA fazem parte do plug-in de IA (atualmente em versão beta), introduzido na versão 2.4.2.

Setup

1. Clone o repositório onlyoffice.github.io  para sua máquina local.
2. Escreva sua função de IA na pasta helpers (sdkjs-plugins/content/ai/.dev/helpers).
3. Dependendo do tipo de editor, coloque-o na pata cell, slide, ou word.
4. Atualize a versão atual do plug-in de IA em config.js para evitar problemas de cache
   (por exemplo, 3.0.3 → 3.0.4).
5. Execute o arquivo helpers.py .
6. Selecione todos os arquivos do plugin na pasta ai , (sdkjs-plugins/content/ai), compacte-os e renomeie o arquivo para ai.plugin.
7. Coloque o arquivo de volta em sdkjs-plugins/content/ai/deploy.
8. Envie as alterações.
9. Crie seu site GitHub Pages a partir deste repositório (consulte a documentação do GitHub Pages).
10. Prepare um link para sua loja personalizada acrescentando /store/index.html para a URL do GitHub Pages:
    https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html
11. Vá para Plugins → Gerenciador de Plugins.
12. Clique no ícone Loja (</>) no canto superior direito do Gerenciador de Plug-ins e insira a URL personalizada da sua loja.
13. Atualize o plugin de IA.

Observação! Para obter instruções mais detalhadas, acesse este link artigo.

Como usar as funções de IA

1. Configure seu provedor de IA e chave API, se necessário.
2. Pressione Ctrl + / para abrir o chat da IA.
3. Digite o que desejar (por exemplo, “Explique este texto”).
4. A IA seleciona a função certa e realiza o trabalho.
5. O resultado aparece no seu documento.

As funções de IA memorizam sua conversa. Você pode fazer perguntas complementares ou refinar os resultados. Pressione Ctrl + Alt + / para recomeçar.

Exemplo: Adicionar comentários de IA

A função commentText adiciona comentários inteligentes ao texto selecionado:

1. Selecione algum texto no seu documento.
2. Pressione Ctrl + / para abrir o chat da IA.
3. Digite: “Explique este texto”.
4. Press Enter.

A IA lê seu texto, gera uma explicação e a adiciona como um comentário em seu documento.

Veja como funciona nos bastidores:

// Simplified structure of an AI Function
func.call = async function (params) {
  // 1. Get the selected text
  let text = await Asc.Editor.callCommand(function () {
    let doc = Api.GetDocument();
    let range = doc.GetRangeBySelect();
    return range ? range.GetText() : "";
  });
  // 2. Ask the AI model
  let requestEngine = AI.Request.create(AI.ActionType.Chat);
  let argPrompt = params.prompt + ":\n" + text;
  // 3. Add the AI's answer as a comment
  await requestEngine.chatRequest(argPrompt, false, async function (data) {
    await Asc.Editor.callCommand(function () {
      let doc = Api.GetDocument();
      let range = doc.GetRangeBySelect();
      range.AddComment(data, model, "uid" + model);
    });
  });
};

Você pode ver o texto completo da função commentText aqui.

Por que as funções de IA são mais flexíveis

AI functions invoke CallCommand separately (see lines in the code above), which lets you execute custom logic before and after document operations. This makes them perfect for AI integration – you can send requests to the AI model, process the response, and then update the document. The Macros app wraps everything within CallCommand, which is simpler but less flexible.

Principais diferenças

As macros destinam-se à manipulação direta de documentos offline. As funções de IA destinam-se à integração de modelos de IA com o ONLYOFFICE.

Veja como eles se comparam:

Aspecto	Macros	Funções de IA
Configuração	Fácil – já integrado	Mais complexo – configuração do provedor de IA + funções personalizadas
Custo	Gratuito	Pago (custos do provedor de IA)
Internet	Funciona offline	Requer uma conexão com um serviço de IA
Pré-requisitos	JavaScript + API do Office	JavaScript + API do Office + alterações do agente de IA
Curva de Aprendizagem	Íngreme para quem não é programador	Íngreme para quem não é programador
Consistência dos resultados	Sempre o mesmo resultado	Pode variar
Flexibilidade	Limitado – envolto em CallCommand	Mais flexível – invocar CallCommand separadamente
Desempenho	Rápido – execução direta	Variável – depende do tempo de resposta da IA
Suporte à versão	Disponível desde as primeiras versões	Beta (desde a versão 2.4.2)
Ideal para	Desenvolvedores, controle preciso, automação offline	Tarefas assistidas por IA, operações com documentos e processamento
Privacidade	Execução local apenas	Dados enviados para um serviço externo de IA

Quando usar cada ferramenta

Macros

Escolha macros quando precisar manipular documentos diretamente:

• Trabalho offline – não é necessária conexão com a Internet.
• Sem custos – automatize o quanto quiser gratuitamente.
• Operações diretas em documentos – formatação, manipulação de dados, cálculos.
• Resultados exatos – a mesma entrada sempre produz o mesmo resultado.
• Prototipagem rápida – escreva código e teste imediatamente no editor.
• Trabalho de produção – relatórios financeiros, documentos de conformidade, fluxos de trabalho automatizados.

Funções de IA

Escolha funções de IA quando sua automação precisar de recursos de IA:

• Integração de modelos de IA – conecte-se a serviços de IA e utilize seus resultados.
• Automação de documentos – aplique os resultados da IA diretamente ao documento.
• Processamento de contexto – lida com o conteúdo tendo em conta a seleção ou a estrutura do documento.
• Lógica avançada – necessidade de flexibilidade para executar código personalizado antes/depois das operações do documento.

Conclusão

As macros e as funções de IA do ONLYOFFICE têm finalidades diferentes. A principal diferença é simples:

As macros servem para manipular documentos diretamente. São gratuitas, funcionam offline e são perfeitas para qualquer automação que não necessite de IA. Use-as para formatação, cálculos, manipulação de dados e fórmulas personalizadas.

As funções de IA servem para integrar modelos de IA ao ONLYOFFICE. Elas são mais complexas de desenvolver do que as macros, exigem internet e custos com provedores de IA, mas são a escolha certa quando você precisa de recursos de IA. Use-as para gerar conteúdo, processar documentos e automatizar tarefas documentais com IA.

A ONLYOFFICE continua aprimorando ambas as ferramentas. As macros estão ganhando novos recursos, como funções assíncronas. As funções de IA estão saindo da versão beta com maior confiabilidade e mais recursos. Compreender ambas as ferramentas permite que você aproveite todo o potencial da automação da ONLYOFFICE.