Enlace bidireccional

Conecta aplicaciones HTML con datos, resultados de fórmulas y actualizaciones colaborativas mediante Server SDK.

Función experimental

El enlace bidireccional está en fase experimental. Las próximas versiones incluirán cambios incompatibles; las API y los métodos de integración pueden cambiar.

Univer Server SDK conecta las páginas HTML, CSS y JavaScript a la hoja. La hoja de cálculo conserva los datos y las fórmulas, mientras que la página proporciona formas, métricas, gráficos y interacciones de negocios. Un cambio a una entrada en cada lado actualiza el otro lado. El SDK permite que una aplicación convierta un modelo de hoja de cálculo en una calculadora de presupuesto, una aplicación interactiva.

Ejemplo: aplicación y hoja conectadas

El ejemplo de la Cumbre del Proyecto expone el crecimiento, el precio de la oferta y la mezcla de pago de efectivo como controles a la izquierda, con el libro de trabajo financiero completo a la derecha. Un cambio a una suposición actualiza las fórmulas relacionadas, tarjetas métricas y gráficos. Los usuarios también pueden abrir la hoja de cálculo para inspeccionar los insumos y los cálculos detrás de ellos.

La captura de pantalla muestra un modelo que se ejecuta en un navegador local. La edición y persistencia compartidas utilizan la integración de la colaboración descrita a continuación. Haga clic en la imagen para verla a tamaño completo.

Una Sheet, varias interfaces

La vista HTML se comunica con su anfitrión a través del tiempo de ejecución de la página. El motor de enlace lee y escribe el contenido real de hoja a través de su propia instancia headless Univer. Univer SDK maneja fórmulas y colaboración, y la capa de unión ofrece valores cambiados a la página.

100%

Las páginas de Bound también se actualizan cuando un usuario edita la hoja de cálculo directamente u otro usuario hace un cambio de colaboración. Una vista HTML única puede acceder a varias Unidades para las que está autorizado. El host carga un motor por unidad, y cada motor mantiene su propia instancia headless Univer.

Declarar enlaces en HTML

Una referencia de datos sobre un elemento mantiene su texto o control sincronizado automáticamente. Las referencias celulares utilizan el formulario unitId:sheetId:A1. Cada ID se codifica por separado con encodeURIComponent, y el ID de hoja de trabajo debe permanecer estable.

AtributoFinalidad
data-univer-cell-textMuestra un valor celular como el texto del elemento.
data-univer-cell-modelSincroniza una célula y un control de forma en ambas direcciones.
data-univer-cell-subscribeDeclara una suscripción celular para la renderización personalizada JavaScript.
data-univer-range-subscribeDeclara una suscripción de rango rectangular para gráficos, listas y otros consumidores de una matriz.

Por ejemplo, el precio unitario es en B2, la cantidad es en B3 y B4 mantiene =B2*B3. El siguiente fragmento de plantilla conecta las dos entradas y el total a esas células:

HTML
<label>  Precio unitario  <input type="number" min="0" step="0.01"    data-univer-cell-model="book:sheet:B2" /></label><label>  Cantidad  <input type="number" min="0" step="1"    data-univer-cell-model="book:sheet:B3" /></label><p>Total: <span data-univer-cell-text="book:sheet:B4"></span></p>

Reemplazar book y sheet con IDs reales y autorizados, y luego cargar la plantilla a través de Renderer. Las fórmulas se definen en Hoja, y la página sólo lee los resultados. Entradas de texto, entradas de números, entradas de rango, casillas de verificación, textareas y controles de una sola selección se unen según sus tipos de valor.

Ampliar gráficos e interacción con JavaScript

La página runtime inicializa window.univerBinding antes de cualquier script de plantilla. Describa el rango de gráficos con data-univer-range-subscribe, y luego llame a subscribeRangeById(elementId, callback) para recibir la matriz y actualizar el gráfico. Componentes que muestran un solo uso de valor subscribeCellById().

Utilice getCellState() / getRangeState() para lecturas de una sola vez, setCellValue() escribir un escalar, y insertRowsWithValues() insertar filas y llenarlas en una sola operación. Una suscripción entrega el estado actual primero y luego cada cambio de valor real. ediciones locales, ediciones de colaboración y resultados de fórmula aplicados pueden todos refrescar la suscripción.

Las referencias leen coordenadas fijas y por lo tanto no siguen el registro original cuando se insertan o eliminan filas o columnas. Un escalar escribe reemplaza cualquier fórmula o texto rico ya presente en la célula, así que une sólo las células que tienen entrada de negocio.

Conectar el host y el Agent

La aplicación proporciona un contenedor, una plantilla HTML y loadEngine. El cargador autoriza el acceso a la Unidad, configura la colaboración y devuelve un motor cargado. Renderer posee la página aislada, el mensaje entre esa página y el host, y el ciclo de vida de los motores que ofrece. Este punto de entrada acepta las tres entradas:

TypeScript
import {  renderHtmlView,  type RenderHtmlViewOptions,} from '@univerjs-labs/html-view-renderer/render';export function createPreview(  container: HTMLElement,  html: string,  loadEngine: RenderHtmlViewOptions['loadEngine'],) {  return renderHtmlView({ container, html, loadEngine });}

Generación de plantillas, edición de fuentes, almacenamiento de archivos y navegación de negocios siguen siendo responsabilidad de la aplicación. Un agente puede generar HTML con declaraciones vinculantes que reutilizan los datos de hoja y reglas de cálculo. Llame a view.inspect.open() para inspeccionar la correspondencia entre una unidad, una hoja, una referencia, y un elemento de página.

El host tiene las credenciales de colaboración, y el servidor impone el acceso. Mantenga la UI de hoja de cálculo y el Motor sin cabeza en entornos JavaScript separados, como páginas separadas o iframes.

Distinguir actualización local y confirmación de guardado

OperaciónSignificado
Escritura de página completadaLa operación local ha ejecutado, pero el servidor puede que no lo haya reconocido todavía.
await view.flush()Presenta proyectos de valores de controles, espera escritos anteriores y el reconocimiento de la colaboración, y luego permite que la edición continúe.
await view.prepareToLeave()Pausas editando y guarda. Deja una vez que el ahorro tenga éxito, o llama a view.resume() si la navegación es cancelada.
view.dispose()Libera conexiones, motores y suscripciones. No guarda datos.

Las suscripciones refrescan los valores en la pantalla una vez que se aplican los resultados de la fórmula. Si un ahorro falla, mantén la página abierta y vuelva a introducir el ahorro. Un escrito de página completado no significa por sí mismo que los datos se han guardado.

Continuar la integración

Funciones relacionadas: ejecución sin interfaz y cálculo en servidor · colaboración en tiempo real · Agents y automatización.

Volver a todas las funciones

¿Cómo es esta guía?

© 2026 DreamNum Co., Ltd.