Novedades en la API de ONLYOFFICE 9.4: guía para desarrolladores sobre las actualizaciones más recientes

La versión 9.4 de ONLYOFFICE introduce importantes mejoras en la API para integraciones, plugins personalizados y automatización de hojas de cálculo. Este artículo destaca las actualizaciones clave en la API de ONLYOFFICE Docs, la API de plugins y macros, y la API de JavaScript de Office, y explica lo que significan para los desarrolladores.

API de ONLYOFFICE Docs 9.4

Soporte para el idioma croata

El croata (hr) ha sido agregado a la lista de idiomas de interfaz compatibles. Si estás desarrollando aplicaciones localizadas para usuarios de habla croata, puedes incluirlo en tu configuración de idioma sin necesidad de soluciones alternativas.

Datos de rol y usuario en el evento onStartFilling

El evento onStartFilling ahora incluye un parámetro roles que contiene información sobre roles y usuarios. Esto facilita mucho la creación de experiencias de rellenado de formularios con conocimiento del rol, por ejemplo, dirigiendo a los usuarios a los campos de los que son responsables, o activando lógica condicional según quién esté rellenando el formulario y en qué capacidad.

function onStartFilling(event) {
  const roles = event.data;
  console.log("Roles:", roles);
}

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

Corrección de fugas de memoria en destroyEditor

Se ha corregido una fuga de memoria en el método destroyEditor. Anteriormente, invocar destroyEditor no limpiaba completamente los recursos asignados. Si tu aplicación crea y destruye instancias del editor con frecuencia, como en configuraciones de aplicaciones de una sola página o flujos de trabajo de vista previa de documentos, esta corrección mejora directamente la huella de memoria de tu integración con el tiempo.

Campo eliminado

Se ha eliminado el campo obsoleto editorConfig.customization.commentAuthorOnly. Si tu integración aún hace referencia a este parámetro, ahora es el momento de eliminarlo para evitar cualquier comportamiento inesperado.

Registro de comandos de plugins para facilitar la depuración

Una de las adiciones más prácticas para los desarrolladores de plugins es el registro de comandos de plugins. Activa la salida de depuración de comandos de plugins directamente en la consola del navegador. Si has pasado tiempo depurando el comportamiento de los plugins adivinando qué comandos se están ejecutando, esta función elimina una cantidad significativa de esa fricción. Te brinda visibilidad directa sobre el flujo de ejecución del plugin sin necesidad de instrumentar tu propio registro.

Bloqueo de plugins específicos al cargar

El nuevo parámetro editorConfig.plugins.disable te permite evitar que se carguen plugins específicos cuando se inicializa el editor. Esto es útil cuando estás incrustando el editor en un entorno controlado y deseas restringir la funcionalidad a lo que es relevante para tus usuarios, sin tener que modificar los archivos de los plugins en sí. Es un enfoque más limpio, a nivel de configuración, para gestionar la superficie de plugins.

Consulta el changelog completo de la API de Docs

API de plugins y macros de ONLYOFFICE 9.4

Nuevos métodos de control del cursor

Se han agregado dos nuevos métodos a window.Asc.plugin.executeMethod para la API de documentos:

• MoveCursorToField: mueve el cursor a un campo de formulario específico;
• MoveCursorOutsideField: mueve el cursor a una posición fuera del campo actual.

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

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

Estos son particularmente útiles para plugins que guían a los usuarios a través del rellenado de formularios o automatizan la navegación campo por campo en documentos. En lugar de depender de la interacción del usuario para avanzar a través de los campos, tu plugin puede controlar la ubicación del cursor de forma programática.

Mejor control de StartAction y EndAction

El método StartAction ahora acepta dos nuevos parámetros: lockScroll y keepSelection. El método EndAction gana scrollToTarget y cancel. Juntos, estos permiten a los plugins un control más detallado sobre el estado del editor durante la ejecución de macros. Puedes preservar la selección del usuario, evitar desplazamientos no deseados durante operaciones automatizadas, o cancelar una secuencia de acciones de manera limpia, todo lo cual contribuye a una experiencia de plugin más estable y predecible.

Consulta el changelog completo de la API de plugins y macros

API de JavaScript de Office 9.4

Esta es la parte más extensa de la versión 9.4. La API de JavaScript de Office gana nuevas capacidades en operaciones de documentos, gestión de datos de hojas de cálculo, controles de formularios, y más. Consulta la lista completa de nuevos métodos

Fusión de documentos

Se ha agregado un nuevo método Api/MergeDocuments a la API de documentos. Esto te permite combinar múltiples documentos en uno, una capacidad que ha sido frecuentemente solicitada para escenarios de automatización como la generación de informes, ensamblaje de contratos y procesamiento de documentos por lotes.

API de color unificada en todos los editores

El método Api/Color está disponible en las APIs de documentos, hojas de cálculo, presentaciones y PDF. Tener una interfaz de color consistente en los cuatro tipos de editores simplifica el código que necesita aplicar estilos a través de diferentes formatos de documentos. Ya no necesitas lógica de manejo de color específica de formato para operaciones comunes.

Soporte para formularios de firma

La versión 9.4 introduce la clase ApiSignatureForm, disponible tanto en la API de documentos como en la API de formularios. Junto con ella vienen los métodos GetValue y SetValue para leer y escribir datos de campos de firma. Esto abre el manejo programático de campos de firma que son útiles para flujos de trabajo que necesitan pre-poblar, validar o extraer datos de firma como parte de un proceso de procesamiento de documentos más amplio.

// El método GetValue de ApiSignatureForm retorna los datos de imagen de la firma almacenados en el formulario.

// Crear un formulario de firma, agregarlo al documento y leer su valor actual.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "Por favor firma aquí", "required": true, "placeholder": "Firma"});
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 del formulario de firma: " + value);
doc.Push(paragraph);

Además, el nuevo método Api/CreateSignatureForm en la API de formularios te permite crear campos de formulario de firma desde cero a través de código, en lugar de depender de la inserción manual.

Detección del estado del formulario

El método ApiFormBase/IsFilled, agregado tanto a la API de documentos como a la API de formularios, te permite verificar si un campo de formulario dado ha sido llenado. Esta es una adición sencilla pero importante para cualquier lógica de validación o envío. Inspecciona el estado de completado del formulario sin necesidad de analizar directamente el contenido de los campos.

Inspección del resaltado del formulario

Dos nuevos métodos (ApiDocument/GetFormsHighlight y ApiDocument/GetControlsHighlight) están disponibles en las APIs de documentos y formularios. Estos te permiten recuperar la configuración de resaltado actual aplicada a los campos de formulario y controles de contenido. Si tu integración gestiona la configuración de visualización del formulario o necesita reflejar los estados de resaltado en elementos de UI externos, estos métodos proporcionan el acceso de lectura que antes faltaba.

Extensa API de objeto de lista de hojas de cálculo

Esta es la adición más completa en 9.4. La API de hojas de cálculo incluye una clase completa ApiListObject para trabajar con objetos de tabla estructurados (objetos de lista), junto con clases de soporte para columnas, filas y ordenación.

Las capacidades clave incluyen:

• Crear y recuperar objetos de lista a través de ApiWorksheet/AddListObject y ApiWorksheet/GetListObjects
• Leer y escribir propiedades de tabla como nombre, nombre mostrado, texto alternativo, estilo, encabezados, totales y configuración de filtro automático
• Acceder a rangos de tabla que incluyen filas de encabezado, rangos del cuerpo de datos y filas totales
• Gestionar columnas y filas a través de ApiListColumn y ApiListRow, con métodos para nombres, índices, rangos, cálculo de totales y eliminación
• Soporte de ordenación a través de las nuevas clases ApiSort, ApiSortFields y ApiSortField — cubriendo orientación de ordenación, coincidencia de caso, criterios de ordenación (valor o color), prioridad y más

Si tu integración implica algún tipo de gestión de datos estructurados en hojas de cálculo, como importaciones de datos, creación dinámica de tablas, generación de informes. Esta adición expande significativamente lo que puedes hacer sin pedir a los usuarios que manipulen tablas manualmente.

Nuevos métodos de rellenado y fórmulas en hojas de cálculo

Se han agregado cuatro métodos de llenado direccional a ApiRange: FillDown, FillUp, FillRight, FillLeft.

Estos reflejan el comportamiento de rellenado de hojas de cálculo que los usuarios inician manualmente, ahora disponible para uso programático. Combinado con el nuevo método ApiRange/SetFormula, puedes crear automatización que construya rangos impulsados por fórmulas dinámicamente. Es útil para informes generados, hojas de cálculo plantilladas y automatización de entrada de datos.

El método Api/GetDefNames también ha sido agregado a la API de hojas de cálculo, dándote acceso a los nombres definidos (rangos nombrados) en un libro de trabajo.

Controles de formato de formularios de texto

La clase ApiTextForm obtiene cuatro nuevos métodos en ambas APIs, documentos y formularios:

• GetFormat/SetFormat: leer y aplicar una máscara de formato al campo de texto
• GetAllowedSymbols/SetAllowedSymbols: controlar qué caracteres pueden ingresar los usuarios

Estos son esenciales para construir formularios de entrada de datos validados, por ejemplo, imponiendo formatos de fecha, restringiendo la entrada a caracteres numéricos, o aplicando máscaras personalizadas para números de teléfono o IDs.

Inspección de propiedades de párrafo

Un conjunto de métodos Get ha sido agregado a ApiParaPr en la API de documentos, cubriendo:

• Propiedades de borde: superior, izquierdo, derecho, inferior, entre
• Paginação: GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl
• Lista: GetNumPr
• Pestañas: GetTabs
• Espaciado: GetContextualSpacing

Estos llenan un vacío que ha existido durante mucho tiempo. Podías establecer muchas de estas propiedades de forma programática, pero leerlas no siempre era posible. Puedes inspeccionar el formato del párrafo sin depender de soluciones alternativas, lo que es particularmente útil para herramientas de análisis de documentos y scripts de validación de plantillas.

Color de control de contenido

La clase ApiInlineLvlSdt en la API de documentos soporta los métodos SetColor y GetColor. Puedes asignar y leer colores de resaltado para controles de contenido en línea, lo que facilita la construcción de experiencias de formulario visualmente distintas o resaltar controles en función de su estado.

// ¿Cómo cambio el color de un control de contenido en línea en un documento?

// Aplica un color RGB específico para distinguir visualmente un control de contenido en un documento.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("Este es un control de contenido de texto en línea con un color de etiqueta azul.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);