双向绑定

通过 Server SDK,让 HTML 应用与电子表格共享数据、公式结果和协同更新。

实验性功能

双向绑定目前仍处于实验阶段,后续版本会有破坏性更新,API 和接入方式可能调整。

Univer Server SDK 可以将普通的 HTML、CSS、JavaScript 页面接入 Sheet。数据和公式保留在表格中,页面负责表单、指标、图表和业务交互。任意一侧的输入发生变化,另一侧都会收到更新。借助它,应用可以将表格模型转化为报价工具、经营看板或可交互的业务应用。

示例:应用与表格联动

Project Summit 示例把增长率、报价和现金支付比例放在左侧控件中,右侧是完整的财务表格。修改某个假设后,相关的公式、指标卡片和图表会随之更新。用户也可以打开表格,检查输入以及背后的计算过程。

截图展示的是在本地浏览器中运行的模型。共享编辑和持久化使用下文介绍的协同接入方式。点击图片可以放大查看。

同一份 Sheet,多个交互界面

HTML 视图通过页面运行时与宿主通信。实际的 Sheet 内容由 Binding Engine 通过其自身独立的 headless Univer 实例读写。公式和协同由 Univer SDK 处理,绑定层负责将变化后的值传递到页面。

100%

用户在表格中直接修改,或其他用户产生协同变更时,绑定页面同样会刷新。一个 HTML 视图可以访问多个已获授权的 Unit。宿主为每个 Unit 加载一个 Engine,每个 Engine 各自持有一个独立的 headless Univer 实例。

用 HTML 声明绑定

在元素上声明数据引用后,其文本或表单控件会自动保持同步。单元格引用的格式为 unitId:sheetId:A1。两个 ID 分别使用 encodeURIComponent 编码,工作表 ID 必须保持不变。

属性用途
data-univer-cell-text将单元格的值显示为元素的文本。
data-univer-cell-model使单元格与表单控件双向同步。
data-univer-cell-subscribe声明单元格订阅,供自定义 JavaScript 渲染使用。
data-univer-range-subscribe声明矩形区域订阅,供图表、列表等读取二维数据的组件使用。

例如,单价位于 B2,数量位于 B3,B4 中为公式 =B2*B3。下面的模板片段将两个输入和总价连接到这几个单元格:

HTML
<label>  单价  <input type="number" min="0" step="0.01"    data-univer-cell-model="book:sheet:B2" /></label><label>  数量  <input type="number" min="0" step="1"    data-univer-cell-model="book:sheet:B3" /></label><p>总价: <span data-univer-cell-text="book:sheet:B4"></span></p>

将 book 和 sheet 替换为真实且已授权的 ID,再通过 Renderer 加载模板。公式定义在 Sheet 中,页面只读取计算结果。文本输入框、数字输入框、滑块、复选框、文本域和单选下拉框都会按各自的值类型绑定。

用 JavaScript 扩展图表与交互

页面运行时会在任何模板脚本执行之前准备好 window.univerBinding。图表使用 data-univer-range-subscribe 声明数据区域,然后调用 subscribeRangeById(elementId, callback) 获取二维矩阵并更新图表。只显示单个值的组件使用 subscribeCellById()。

仅需读取一次时,使用 getCellState() / getRangeState();写入单个值时使用 setCellValue();插入行并同时填充值时使用 insertRowsWithValues()。订阅会先返回当前状态,之后仅在值实际发生变化时通知。本地编辑、协同修改和公式结果应用都会触发刷新。

引用读取的是固定坐标,因此在插入或删除行列后不会跟随原记录移动。标量写入会覆盖单元格中原有的公式或富文本,因此只应绑定存放业务输入的单元格。

接入宿主与 Agent

应用需要提供容器、HTML 模板和 loadEngine。加载器负责校验 Unit 访问权限、配置协同连接,然后返回一个已加载的 Engine。Renderer 负责隔离页面本身、页面与宿主之间的消息通信,以及所交付 Engine 的生命周期。下面这个入口接收的就是这三个参数:

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 });}

模板生成、源码编辑、文件存储和业务导航均由应用负责。Agent 可以生成带绑定声明的 HTML,复用 Sheet 中的数据和计算规则;调用 view.inspect.open() 可以查看 Unit、Sheet、引用和页面元素之间的对应关系。

协同凭据保存在宿主侧,实际的访问校验由服务端执行。Sheet UI 和 Headless Engine 必须分别放在不同的 JavaScript 环境中,例如两个页面或 iframe。目前的绑定包只覆盖 Sheet。

区分本地更新与保存确认

操作含义
页面写入完成本地操作已执行,但服务端可能尚未确认。
await view.flush()提交控件中的草稿值,等待此前的写入和协同确认完成,然后继续编辑。
await view.prepareToLeave()暂停编辑并保存。保存成功后可以离开;如果导航被取消,调用 view.resume()。
view.dispose()释放连接、Engine 和订阅。它不会保存任何数据。

公式结果应用后,订阅会刷新页面上的值。保存失败时,应保持页面打开并重试保存。页面写入完成本身并不表示数据已经保存。

继续接入

相关能力:无头与服务端计算 · 实时协同 · Agent 与自动化。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.