Integración de intercambio de archivos

Para abrir Excel en Univer, conviértelo primero en datos que pueda leer el editor. Para exportarlo, convierte los datos editados de nuevo en Excel. El módulo servidor @univerjs-pro/exchange-node realiza la conversión; el navegador sube archivos, abre documentos y descarga resultados.

Sin edición colaborativa

Por ejemplo, un usuario sube Excel, lo edita en la página y descarga el resultado como Excel.

1. El navegador sube el archivo y el servidor lo convierte a datos Univer y los devuelve.
2. El navegador abre una hoja con esos datos para editarla.
3. Al exportar, envía los datos editados al servidor, que genera Excel para descargar.

No requiere servicio de colaboración. La «instantánea» de las API del navegador es el conjunto de datos usado aquí. Su importación y exportación siguen necesitando conversión en el servidor. Para guardar el trabajo y retomarlo después, la aplicación debe almacenar esos datos.

Consulta Importación y exportación de Office para instalar y usar el módulo. Empieza allí también si solo necesitas procesar archivos en Node.js.

Con edición colaborativa

Por ejemplo, un usuario importa Excel, comparte el documento con compañeros, lo edita con ellos y lo exporta después.

1. El servidor convierte el archivo subido y guarda el resultado como documento colaborativo.
2. Devuelve un ID; el navegador lo abre y los demás usuarios se unen mediante el mismo ID.
3. Al exportar, el servidor lee el contenido más reciente y genera Excel para descargar.

El unitId de las API del navegador es ese ID. Completa primero la integración de colaboración y ejecuta el ejemplo Exchange, que incluye el código de navegador, servidor y conversión para seguirlo conjuntamente.

Espera a que se sincronicen las ediciones antes de exportar o podrían faltar cambios recientes. Consulta Office Exchange del lado servidor en Módulos de extensión para leer y convertir documentos colaborativos.

Conectar los botones de importación y exportación

Cuando funcione la conversión del servidor, conéctala a la página:

• Menús Univer o API Facade: registra File Endpoint y Exchange Endpoint como en el ejemplo Exchange, y configura los plugins del navegador.
• Botones propios: llama a las API de tu aplicación. Tras importar, abre los datos o el ID devueltos; tras exportar, descarga el archivo generado.

Consulta la configuración en Sheets, Docs, Slides, Boards, Bases y PDFs. El ejemplo colaborativo usa Sheets. Para otros productos, consulta Importación y exportación de Office y los formatos de tu versión.

Comprobar la integración

Importa un archivo real de la aplicación, edítalo y expórtalo. Ábrelo en Office y revisa cambios, fórmulas, imágenes y diseño. En colaboración, verifica además que otros usuarios abran el mismo documento y que su contenido sobreviva a un reinicio del servidor.

Antes de desplegar, limita el tamaño de subida y gestiona fallos y tiempos de espera. Subidas, consultas y descargas necesitan controles de acceso; consulta Identidad y autorización.

Errores de exportación y límites de licencia

La exportación puede fallar al enviar la solicitud o durante el seguimiento de la tarea. Un HTTP correcto no garantiza el archivo: compruebe error.code y el estado de la tarea. El cliente Exchange transmite los errores del servidor mediante IExchangeService.requestState$; una UI personalizada puede suscribirse antes de iniciar la operación.

import { IExchangeService } from '@univerjs-pro/exchange-client'import { ErrorCode } from '@univerjs/protocol'const exchange = univer.__getInjector().get(IExchangeService)const subscription = exchange.requestState$.subscribe(({ error }) => {  if (!error || error.code === ErrorCode.OK) return  console.error(error.code, error.message)})

Compare valores ErrorCode de @univerjs/protocol, no mensajes traducidos. Conserve el mensaje del servidor para diagnóstico. Los fallos de red, respuestas no válidas y tiempos de espera pueden producir errores genéricos y no prueban un rechazo de licencia. Llame a subscription.unsubscribe() al retirar el editor.

Un backend o proxy propio debe conservar la respuesta estructurada y marcar las tareas fallidas en lugar de dejarlas pendientes. Aumentar maxTimeoutTime solo prolonga el seguimiento; no aumenta la cuota ni cambia la cobertura de la licencia.

Adjuntos OLE

Sheets, Docs y Slides conservan los archivos OLE importados separados de sus vistas previas. Se pueden descargar los originales disponibles y, con permisos, renombrar una instancia o eliminar el adjunto. Las imágenes y PDF admiten vista previa. La de Office usa conversión JSON de Exchange y un editor temporal de solo lectura, sin crear un documento hijo persistente. No ejecuta aplicaciones nativas de Office ni macros.

Añada ole al registro existente de UniverDrawingPlugin antes de registrar Exchange. La ruta del ejemplo debe abrir la interfaz de documentos de su aplicación; puede usar el segundo argumento de getLink (tipo de documento). Exchange proporciona conversión de Office y detección de colaboración. Los adjuntos referenciados por UUID también requieren ole.attachmentIo con callbacks autorizados upload(file, targetUnitId) y read(attachment, signal). La vista previa de Office necesita el renderizador correspondiente o previewOffice / createOfficePreview personalizados.

import { UniverDrawingPlugin } from '@univerjs/drawing'univer.registerPlugin(UniverDrawingPlugin, {  ole: {    getLink: (unitId) => `/documents/${encodeURIComponent(unitId)}`,  },})

Convertir un adjunto Office en documento en línea requiere un anfitrión colaborativo, permiso de edición, conversión y getLink. Crea un documento independiente y guarda su identidad en el adjunto para reutilizarlo. Editar ese documento no sobrescribe los bytes originales. Los adjuntos ausentes, externos o no compatibles mantienen su estado.

La exportación usa oleAttachmentSource: 'original' por defecto. 'online' incorpora las versiones actuales confirmadas de los documentos convertidos solo en esa exportación, sin modificar los originales almacenados. Espere la sincronización y autorice en el backend el acceso a los documentos referenciados. Pase la opción como segundo argumento de las API de Docs/Slides o cuarto de Sheets; las variantes snapshot usan la misma posición. Consulte la API de exportación.

Exchange envía fileID y la Unit propietaria, sourceUnitID, para adjuntos persistidos. El backend debe validar su relación y el acceso del solicitante antes de convertir por referencia. El sondeo puede devolver progress.stage: reading, converting, creating o done. Para una interfaz propia, consulta las API de importación y progreso.