O que há de novo na API ONLYOFFICE 9.4: guia do desenvolvedor para as últimas atualizações

A versão 9.4 da ONLYOFFICE introduz melhorias significativas na API para integrações, plugins personalizados e automação de planilhas. Este artigo destaca as principais atualizações da API ONLYOFFICE Docs, da API de Plugins e Macros, e da API JavaScript do Office, explicando o que elas significam para os desenvolvedores.

API ONLYOFFICE Docs 9.4

Suporte ao idioma croata

O croata (hr) foi adicionado à lista de idiomas de interface suportados. Se você está desenvolvendo aplicativos localizados para usuários que falam croata, pode incluí-lo na sua configuração de idioma sem soluções alternativas.

Dados de função e usuário no evento onStartFilling

O evento onStartFilling agora inclui um parâmetro roles que transporta informações sobre função e usuário. Isso facilita muito a construção de experiências de preenchimento de formulários conscientes da função, por exemplo, direcionando usuários para os campos dos quais são responsáveis, ou acionando lógica condicional com base em quem está preenchendo o formulário e em que capacidade.

function onStartFilling(event) {
  const roles = event.data;
  console.log("Funções:", roles);
}

const config = {
  // ...
  events: {
    onStartFilling,
  },
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);

Correção de vazamento de memória no destroyEditor

Um vazamento de memória no método destroyEditor foi corrigido. Anteriormente, chamar destroyEditor não limpava completamente os recursos alocados. Se sua aplicação cria e destrói instâncias de editor frequentemente, como em configurações de aplicativos de página única ou em fluxos de trabalho de visualização de documentos, essa correção melhora diretamente a pegada de memória da sua integração ao longo do tempo.

Campo removido

O campo obsoleto editorConfig.customization.commentAuthorOnly foi removido. Se sua integração ainda faz referência a esse parâmetro, agora é hora de removê-lo para evitar qualquer comportamento inesperado.

Registro de comandos de plugins para depuração mais fácil

Uma das adições mais práticas para desenvolvedores de plugins é o registro de comandos de plugins. Habilite a saída de depuração de comandos de plugins diretamente no console do navegador. Se você gastou tempo depurando o comportamento de plugins adivinhando quais comandos estão realmente sendo acionados, esse recurso remove uma quantidade significativa dessa fricção. Ele fornece visibilidade direta no fluxo de execução do plugin sem precisar instrumentar seu próprio registro.

Bloqueando plugins específicos no carregamento

O novo parâmetro editorConfig.plugins.disable permite que você evite que plugins específicos sejam carregados quando o editor é inicializado. Isso é útil quando você está incorporando o editor em um ambiente controlado e deseja restringir a funcionalidade ao que é relevante para seus usuários, sem precisar modificar os arquivos do plugin em si. É uma abordagem mais limpa, em nível de configuração, para gerenciar a superfície do plugin.

Veja o changelog completo da API Docs

API de Plugins e Macros ONLYOFFICE 9.4

Novos métodos de controle de cursor

Dois novos métodos foram adicionados a window.Asc.plugin.executeMethod para a API de Documentos:

• MoveCursorToField: move o cursor para um campo de formulário específico;
• MoveCursorOutsideField: move o cursor para uma posição fora do campo atual.

Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);

Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);

Esses métodos são especialmente úteis para plugins que guiam os usuários pelo preenchimento de formulários ou automatizam a navegação campo a campo em documentos. Em vez de depender da interação do usuário para avançar pelos campos, seu plugin pode controlar a colocação do cursor programaticamente.

Controle aprimorado de StartAction e EndAction

O método StartAction aceita dois novos parâmetros: lockScroll e keepSelection. O método EndAction ganha scrollToTarget e cancel. Juntos, esses recursos fornecem aos plugins maior controle sobre o estado do editor durante a execução de macros. Você pode preservar a seleção do usuário, evitar rolagens indesejadas durante operações automatizadas ou cancelar uma sequência de ações de forma limpa — tudo isso contribui para uma experiência de plugin mais estável e previsível.

Veja o changelog completo da API de Plugins e Macros

API JavaScript do Office 9.4

Esta é a parte mais expansiva do lançamento da versão 9.4. A API JavaScript do Office ganha novas capacidades em operações de documentos, gerenciamento de dados de planilhas, controles de formulário e mais. Veja a lista completa de novos métodos

Mesclagem de documentos

Um novo método Api/MergeDocuments foi adicionado à API de Documentos. Isso permite que você combine múltiplos documentos em um – uma capacidade que tem sido frequentemente solicitada para cenários de automação, como geração de relatórios, montagem de contratos e processamento em lote de documentos.

API de Cor Unificada em todos os editores

O método Api/Color está disponível nas APIs de Documentos, Planilhas, Apresentações e PDF. Ter uma interface de cor consistente em todos os quatro tipos de editores simplifica o código que precisa aplicar estilos por meio de diferentes formatos de documentos. Você não precisa mais de lógica de manipulação de cor específica para cada formato para operações comuns.

Suporte a formulários de assinatura

A versão 9.4 apresenta a classe ApiSignatureForm, disponível tanto na API de Documentos quanto na API de Formulários. Junto com ela, vêm os métodos GetValue e SetValue para leitura e escrita de dados de campos de assinatura. Isso abre a manipulação programática de campos de assinatura, que são úteis para fluxos de trabalho que precisam pré-preencher, validar ou extrair dados de assinatura como parte de um pipeline de processamento de documentos maior.

// O método GetValue da ApiSignatureForm retorna os dados da imagem da assinatura armazenada no formulário.

// Crie um formulário de assinatura, adicione-o ao documento e leia seu valor atual.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "Por favor, assine aqui", "required": true, "placeholder": "Assinatura"});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("Valor do formulário de assinatura: " + value);
doc.Push(paragraph);

Além disso, o novo método Api/CreateSignatureForm na API de Formulários permite que você crie campos de formulário de assinatura do zero por meio de código, em vez de depender da inserção manual.

Detecção de estado de formulário

O método ApiFormBase/IsFilled, adicionado tanto à API de Documentos quanto à API de Formulários, permite que você verifique se um determinado campo de formulário foi preenchido. Esta é uma adição simples, mas importante para qualquer lógica de validação ou submissão. Inspecione o estado de preenchimento do formulário sem precisar analisar diretamente o conteúdo dos campos.

Inspeção de destaque de formulário

Dois novos métodos (ApiDocument/GetFormsHighlight e ApiDocument/GetControlsHighlight) estão disponíveis nas APIs de Documentos e Formulários. Estes permitem que você recupere as configurações de destaque atuais aplicadas aos campos de formulário e aos controles de conteúdo. Se sua integração gerencia a configuração de exibição de formulários ou precisa refletir estados de destaque em elementos de UI externos, esses métodos fornecem o acesso de leitura que estava ausente anteriormente.

Extensa API de Objeto de Lista de Planilhas

Esta é a adição mais rica em recursos na versão 9.4. A API de Planilhas inclui uma classe completa ApiListObject para trabalhar com objetos de tabela estruturada (objetos de lista), juntamente com classes de suporte para colunas, linhas e ordenação.

As principais capacidades incluem:

• Criar e recuperar objetos de lista por meio de ApiWorksheet/AddListObject e ApiWorksheet/GetListObjects
• Ler e escrever propriedades de tabela como nome, nome de exibição, texto alternativo, estilo, cabeçalhos, totais e configurações de filtro automático
• Acessar intervalos de tabela incluindo linhas de cabeçalho, intervalos de corpo de dados e linhas de totais
• Gerenciar colunas e linhas por meio de ApiListColumn e ApiListRow, com métodos para nomes, índices, intervalos, cálculo de totais e exclusão
• Suporte a ordenação por meio das novas classes ApiSort, ApiSortFields e ApiSortField — cobrindo orientação de ordenação, sensibilidade a maiúsculas, critérios de ordenação (valor ou cor), prioridade e mais

Se sua integração envolve qualquer tipo de gerenciamento de dados estruturados em planilhas, como importações de dados, criação dinâmica de tabelas e geração de relatórios, essa adição expande significativamente o que você pode fazer sem pedir aos usuários que manipulem tabelas manualmente.

Novos métodos de Preenchimento e Fórmula em Planilhas

Quatro métodos de preenchimento direcional foram adicionados a ApiRange: FillDown, FillUp, FillRight, FillLeft.

Esses métodos replicam o comportamento de preenchimento de planilhas que os usuários acionam manualmente, agora disponível para uso programático. Combinado com o novo método ApiRange/SetFormula, você pode construir automações que criam intervalos baseados em fórmulas dinamicamente. Isso é útil para relatórios gerados, planilhas modeladas e automação de entradas de dados.

O método Api/GetDefNames também foi adicionado à API de Planilhas, dando a você acesso aos nomes definidos (intervalos nomeados) em uma pasta de trabalho.

Controles de formatação de formulário de texto

A classe ApiTextForm ganha quatro novos métodos tanto nas APIs de Documentos quanto de Formulários:

• GetFormat/SetFormat: ler e aplicar uma máscara de formato ao campo de texto
• GetAllowedSymbols/SetAllowedSymbols: controlar quais caracteres os usuários podem inserir

Esses métodos são essenciais para a construção de formulários de entrada de dados validados, por exemplo, impondo formatos de data, restringindo entradas a caracteres numéricos ou aplicando máscaras personalizadas para números de telefone ou IDs.

Inspeção de propriedades de parágrafo

Um conjunto de métodos Get foi adicionado a ApiParaPr na API de Documentos, cobrindo:

• Propriedades de borda: superior, esquerda, direita, inferior, entre
• Paginação: GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl
• Lista: GetNumPr
• Guias: GetTabs
• Espaçamento: GetContextualSpacing

Esses métodos preenchem uma lacuna que existia há bastante tempo. Você poderia definir muitas dessas propriedades programaticamente, mas ler seus valores nem sempre era possível. Você pode inspecionar a formatação de parágrafos sem depender de soluções alternativas, o que é particularmente útil para ferramentas de análise de documentos e scripts de validação de modelos.

Cor do Controle de Conteúdo

A classe ApiInlineLvlSdt na API de Documentos suporta os métodos SetColor e GetColor. Você pode atribuir e ler cores de destaque para controles de conteúdo inline, facilitando a construção de experiências de formulário visualmente distintas ou destacando controles com base em seu estado.

// Como eu mudo a cor de um controle de conteúdo inline em um documento?

// Aplique uma cor RGB específica para distinguir visualmente um controle de conteúdo em um documento.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("Este é um controle de conteúdo de texto inline com uma cor de etiqueta azul.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);