在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

403次阅读
没有评论

共计 5730 个字符,预计需要花费 15 分钟才能阅读完成。

Univer 是一套开源的网页办公组件,仓库在 dream-num/univer。它解决的问题很具体:你想在自己的网站或内部小工具里放一张能编辑、能写公式、改一个数其他格子自动重算的表格,又不想自己从画格子、写公式引擎开始。装两个 npm 包,写十几行代码,页面上就有一张像样的电子表格。

11 月 16 日早上 7 点 51 分(北京时间)我看 GitHub 日榜,它排第 1,当天加了 1,041 星,总星数 25,592,许可证 Apache-2.0。两天前(11 月 14 日)它刚发了 1.5.0。

我没打算做大东西,就用它做一张回国预算表:机票、给爸妈带的东西、国内手机卡,按美元填,按汇率折成人民币。下面是我在自己的 Linux 测试机上从空文件夹做到能保存的全过程,坑按踩到的顺序写。

PART 01

先弄清楚:免费的部分到哪为止

Univer 官方把整套东西叫 Office SDK,分三块。中文 README 里写得很直白:

  • Web SDK:表格和文档的编辑、渲染、公式计算,还有给程序调用的 Facade API。这块在 GitHub 上以 Apache-2.0 开源。
  • Server SDK:多人实时协同、编辑历史、Office 文件导入导出。单独授权。
  • AI SDK:把这些能力接给现有 Agent 的工具集。商业扩展单独授权。

所以我这篇只用开源的 Sheets Core。能做的事:单元格样式、合并单元格、公式、筛选排序、数据验证、条件格式、撤销重做。导入导出 .xlsx 不在这条开源链路里,中文 README 的原话是「快照持久化与 XLSX 导入导出是不同的能力,后者需要单独分发的文件转换能力」。

🍎 想要的是「上传一个 Excel、网页里改完再下载回 Excel」,开源版本身做不到,得另接商业的 Server SDK 或自己找别的库转换。只想在网页里填表、算数、存 JSON,开源版够用。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 示意图:本文只用左边开源的那块

PART 02

准备一个空项目

我的环境:Node v24.22.1,npm 11.21.1。README 推荐用 Vite、esbuild 或 Webpack 5 打包,我用 Vite 建一个最小的 TypeScript 项目,全程在一个单独的文件夹里,不装任何全局包。

建 Vite 空项目 → 装两个包 → 写容器 → 写十几行初始化 → 浏览器打开

npm create vite@latest sheet-demo -- --template vanilla-ts --no-interactive
cd sheet-demo
npm install
npm install @univerjs/presets @univerjs/preset-sheets-core

README 里写的是 pnpm add,用 npm 一样。我这边第二条装了 123 个包,用了 5.9 秒,两个包版本都是 1.5.0。输出末尾多了几行黄字:

npm warn install-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn install-scripts   protobufjs@7.6.6 (postinstall: node scripts/postinstall)

这是新版 npm 默认不跑依赖的安装脚本,提醒你看一眼。我没批准它,后面表格照样跑得起来,可以先不管。

PART 03

先原样跑 README 的例子

把 index.html 里的容器改成有高度的:

<div id="app" style="height: 100vh"></div>

src/main.ts 整个换成 README 的快速开始代码:

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
  },
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
})
univerAPI.createWorkbook({})

npx vite 启动,打开终端里给的 http://localhost:5173/(端口被占会顺延)。看到下面这样就对了:英文菜单,一张空表,点格子能输入。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:README 原样代码,页面上就是一张能用的空表

坑 1:容器没给高度,表格只剩一条工具栏

我故意把 style="height: 100vh" 删掉试了一次。工具栏和底部的 Sheet1 标签都在,中间的格子区一格都没有。量了一下,格子那块画布高度是 0。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:页面不报错,只是格子没地方画

解法就一条:给容器一个明确的高度,100vh、600px 都行。官方 Vue 文档的例子用的是 height: 600px。

PART 04

换成中文,填一张回国预算表

中文语言包在同一个包里,把 en-US 换成 zh-CN,LocaleType.EN_US 换成 LocaleType.ZH_CN。菜单会变成「开始、公式、视图」,右键菜单也是中文。

填数据用 README 报价单例子里的写法:等表格初始化完,再用 setValues 一次写一片。下面是我实际跑的版本,去掉了保存的部分(第六节再加):

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: { [LocaleType.ZH_CN]: mergeLocales(UniverPresetSheetsCoreZhCN) },
  presets: [UniverSheetsCorePreset({ container: 'app' })],
})
univerAPI.createWorkbook({ name: '回国预算' })
// 等公式引擎就绪再写数据(README 报价单例子里的写法)
await new Promise<void>((resolve) => {
  if (univerAPI.getCurrentLifecycleStage() >= univerAPI.Enum.LifecycleStages.Steady) return resolve()
  const l = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
    if (stage === univerAPI.Enum.LifecycleStages.Steady) { l.dispose(); resolve() }
  })
})
const sheet = univerAPI.getActiveWorkbook()!.getActiveSheet()
sheet.getRange('A1:E5').setValues([
  ['项目', '数量', '单价(美元)', '小计(美元)', '小计(人民币)'],
  ['往返机票', 1, 980, '=B2*C2', '=D2*$G$1'],
  ['给爸妈的保健品', 4, 45, '=B3*C3', '=D3*$G$1'],
  ['国内手机卡月租', 2, 12, '=B4*C4', '=D4*$G$1'],
  ['合计', '', '', '=SUM(D2:D4)', '=SUM(E2:E4)'],
])
sheet.getRange('F1:G1').setValues([['汇率', 7.1]])
sheet.setColumnWidth(0, 130)
sheet.setColumnWidth(4, 110)
sheet.setName('回国预算')

汇率单独放在 G1,人民币那列都写 $G$1,以后只改一个格子。表里的汇率 7.1 是我随手填的,用的时候换成你自己查到的。

刷新页面,美元合计 1184,人民币合计 8406.4。980 + 4×45 + 2×12 = 1184,1184 × 7.1 = 8406.4,手算对得上。

坑 2:中文项目名被截断

第一次跑我没写 setColumnWidth,A 列默认宽度放不下「给爸妈的保健品」,只露出「给爸妈的保健」。加一行 sheet.setColumnWidth(0, 130)(第一个参数是列序号,从 0 开始)就好了。手动拖列宽也行,只是每次刷新都要重拖。

坑 3:表名写了,底部标签还是 Sheet1

createWorkbook({ name: '回国预算' }) 改的是整个工作簿的名字,底部那个工作表标签还是 Sheet1。要改标签得对工作表本身调 sheet.setName('回国预算')。

PART 05

改汇率,看它自己重算

点 G1,把 7.1 改成 7.25,回车。人民币那一列和合计立刻跟着变,合计成了 8584。点 E5,上面公式栏显示 =SUM(E2:E4)。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:只改了 G1 一个格子

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 示意图:本节的操作顺序

坑 4:新加的一项,合计里没有

后来想起还要拍签证照片,15 美元。我顺手在「合计」下面那行敲:签证照片,Tab,1,Tab,15,Tab,=B6*C6,回车。这一行的小计算出来是 15,可合计还是 1184。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:合计公式还是 =SUM(D2:D4)

这跟 Excel 一样,SUM(D2:D4) 只认 2 到 4 行,写在外面的行它不管。我又用脚本调接口试了一种:紧贴着合计那一行的上方插一行。新行落在第 5 行,还是在 2 到 4 行外面,公式没跟着扩。

管用的办法是把新行插在区间中间:右键第 4 行的行号,选「在上方插入 1 行」。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:中文右键菜单

插完以后合计公式自己变成了 =SUM(D2:D5),填进签证照片,美元合计变成 1199。人民币那列别忘了在 E4 补上 =D4*$G$1,截图里我还没填,所以人民币合计还停在 8406.4。

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 实测截图:插在区间里面,公式范围跟着扩

在自己网页里放一张会算公式的表格:Univer 1.5 实测,从空项目做到回国预算表

▲ 示意图:两种加行方式的区别

PART 06

存起来,刷新不丢

Univer 只管表格,存到哪由你自己决定。workbook.save() 返回一份 JSON 快照,README 的例子是存进浏览器的 localStorage,我照着加了两段:

const KEY = 'trip-budget'
// 页面打开时:有存档就恢复,没有才新建空表
const saved = localStorage.getItem(KEY)
if (saved) {
  univerAPI.createWorkbook(JSON.parse(saved))
} else {
  univerAPI.createWorkbook({ name: '回国预算' })
  // ……上一节填数据的代码放这里
}
// 想保存的时候调一次,比如绑到一个按钮上
function saveSheet() {
  localStorage.setItem(KEY, JSON.stringify(univerAPI.getActiveWorkbook()!.save()))
}

我把汇率改成 7.25 后调了一次保存,这份五行小表的快照有 1,753 个字符。刷新页面,G1 还是 7.25,合计还是 8584。

🍎 恢复的时候要用快照去 createWorkbook,别先建一张空表再建一张,README 特地加粗写了「而不是创建空白工作簿」。localStorage 只存在这台电脑这个浏览器里,换设备就没了,正式用要存到自己的后端。

PART 07

打包有多大,适合谁

npm run build 用了 2.37 秒,过程中刷了 19 条 "use client" 的提示,都来自依赖里的界面组件,不影响结果。体积是真不小:

产物原始大小gzip 后
主 JS6,544.74 kB1,634.02 kB
CSS122.56 kB17.93 kB

dist 文件夹一共 11 MB、79 个文件,node_modules 306 MB。Vite 还提示了分块超过 500 kB。

所以我的判断是:内部工具、后台、自己用的小网页,放一张 Univer 表格很省事;对加载速度敏感的公开页面,要先想想 1.6 MB 的 gzip 体积能不能接受,或者只在用户点开表格时再加载它。

运行环境的几条要求也记一下,来自 README:依赖浏览器的 Intl.Segmenter,老浏览器要加 polyfill;React 18、19 都支持;不带界面、在 Node.js 里跑公式要 Node 18.17.0 以上。

1.5.0 这次的更新说明里,开源 Sheets 多了三个开关:selectionAnimation(点格子时选框动画)、enableFillHandle(右下角填充柄)、warnBeforeDragOverwrite(拖动覆盖已有数据前先确认),默认都开着,写在 UniverSheetsCorePreset 的 sheets 配置里就能关。图表工作表、误差线这些新功能要另外装图表相关的插件,这篇没碰。

· · ·

相关阅读

官方资料:GitHub 仓库、中文 README、1.5.0 更新说明、官方中文文档(Vue 集成)。

正文完
 0

版权声明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。

科技喵仔
版权声明:本站原创文章,由 科技喵仔 于2026-11-16发表,共计5730字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码
    中文English