给企业做数据系统这几年我最大的感受就是业务方嘴上说的是做个网页表格心里装的其实是把 Excel 给我搬到网页上还不能少功能。去年接的物料台账、数据填报系统就是典型项目编号 271702999从需求分析到上线排期几乎每个环节都绕不开表格能力。最后整个系统的在线表格部分我是用 SpreadJS 17.0.7 落地的从数据绑定、公式联动、Excel 导入导出到校验、权限、性能优化一整套下来踩了不少坑也攒了不少经验。今天这篇就把完整的选型思路、集成细节和避坑记录整理出来给准备在项目里上 SpreadJS 的朋友一份能直接参考的实操笔记。1. 项目背景与需求拆解1.1 客户要的不是表格是 Excel这个项目的业务场景分两块。第一块是物料主数据台账几千条物料的编码、名称、规格、单位、采购价、安全库存这些字段做成在线表格不同角色要能筛选、编辑、评论改完的数据按权限批量提交入库。第二块是月度生产数据填报各分厂业务员在系统里填产量、能耗、废品率等指标表格自带校验规则和跨表计算公式提交后要汇总成集团级报表。这两块需求听起来都叫表格实际做起来差异很大。台账侧重点是展示、编辑、批量提交就是对数据本身的操作填报侧重点是公式联动、校验拦截、汇总统计对计算能力的要求更高。但它们有一个共同点用户已经习惯了 Excel 的操作方式你在网页上做一个跟 Excel 长得差不多的表格他们能快速上手你做一个跟 Excel 不一样的东西哪怕是逻辑更好也会被嫌弃。所以核心诉求其实很清晰——在网页里把 Excel 的交互体验还原出来同时能把数据安全地送回后端。1.2 为什么选 SpreadJS 而不是自己写接这个项目的时候我先把市面上的路线过了一遍。第一条路是纯手写 HTML 表格加编辑功能做简单展示和单格编辑没问题但一旦遇到公式联动、行列拖拽、样式还原、合并单元格、筛选这些 Excel 常规操作开发量会迅速失控而且浏览器原生表格在渲染大数据量时性能瓶颈非常明显。第二条路是用服务端组件生成 Excel 文件这种只能解决导出一个文件的需求前端交互、即时计算、行内校验统统做不到跟在线编辑的要求相差太远。所以方向基本锁定在成熟的纯前端表格控件上。SpreadJS 是几个候选里综合评分最高的原因有三点。第一它本质上是把 Excel 的公式引擎、单元格类型、数据验证、条件格式这些能力复刻到了浏览器端JS 跑在本地交互即时响应不依赖网络请求。第二它对 .xlsx 文件的兼容性确实好客户那边积累了十几年的 Excel 模板字段、公式、样式都是按业务习惯排好的如果换套系统让他们重新做模板项目基本做不下去SpreadJS 可以直接导入这些模板数据回填、公式保留做到原来怎么在 Excel 里干活现在就怎么在网页里干活。第三是生态和文档比较完整遇到问题能查的资料足够多不会卡在某个 API 上出不来。1.3 版本 17.0.7 意味着什么选型时候我特意用了 17.0.7 而不是更早的稳定版。SpreadJS 每年会有一个大版本迭代17 系列在计算引擎和 Excel 兼容性上都有提升而 17.0.7 属于维护版本会把前面几个小版本里反馈的问题修掉一批。用维护版的好处是既能吃到新功能又不用承担大版本初期那些稳定性风险。项目上线到现在这个版本的表现确实对得起预期。2. 工程集成与基础初始化2.1 安装、引入、样式一个都不能少这个项目的技术栈是 Vue 3 Vite直接在工程里装 SpreadJS 的 npm 包就行。基础表格能力在grapecity/spread-sheets包里但 Excel 的导入导出是单独一个包grapecity/spread-excelio这两者要同时装。如果你还需要图表、打印、PDF 导出这些能力还要按需引入对应模块包这次的业务没涉及图表所以只装了下面三个。npm install grapecity/spread-sheets17.0.7 npm install grapecity/spread-excelio17.0.7 npm install grapecity/spread-sheets-resources-zh17.0.7除了 JS 逻辑样式也要引进来。这一步特别容易被忽略漏掉之后表格不是不能用而是外观会非常奇怪行列头、网格线、选中态的样式全都不对整体就一个素颜状态用户第一眼就会觉得系统没做完。import grapecity/spread-sheets/styles/gc.spread.sheets.css;还有一点要注意如果你在项目里用到了 SpreadJS 的在线表格编辑器Designer那需要安装的是grapecity/spread-designer以及对应样式API 体系和基础表格不完全一样别混用。2.2 页面容器与 Workbook 初始化SpreadJS 必须渲染在一个指定宽高的 DOM 容器里。我把它封装成了一个 Vue 组件模板里只有一个 div。div refhost stylewidth: 100%; height: calc(100vh - 160px)/div这里有个经验容器必须有确定的高度。只给宽度不给高度SpreadJS 渲染出来往往是一个高度为 0 的空区域怎么调都不出表格。上面我用的calc(100vh - 160px)是预留了顶部导航栏和筛选区的空间这个值在后面的章节里还会提到。初始化代码在onMounted里执行import * as GC from grapecity/spread-sheets; let spread; let sheet; onMounted(() { spread new GC.Spread.Sheets.Workbook(host.value, { sheetCount: 1 }); sheet spread.getActiveSheet(); sheet.setRowCount(500); sheet.setColumnCount(50); });初始化时如果把sheetCount设为 1工作簿会默认带一个 sheet名字是 Sheet1后面可以通过 API 动态增删。如果你需要多个 sheet也可以在初始化时直接给多一点比如sheetCount: 3再按业务需求改名、删减。我这边台账和填报分成了两个独立页面单页用 1 个 sheet 就够但如果你做一个多 Tab 的工作簿页面这个参数就能派上用场。2.3 授权码与中文资源SpreadJS 是商业控件授权码必须配置不然界面会带试用角标并且不定期弹授权提示。配置方式是在初始化之前设置。GC.Spread.Sheets.LicenseKey 你的授权码;授权码来自你购买的 License通常是企业授权一次配置全局生效。我建议把授权码放到环境变量里不同环境用不同 key不然授权信息写死在代码仓库里后面不好管理。中文资源这块默认的右键菜单、筛选下拉、导入导出提示都是英文的。要让界面变成中文需要单独引入本地化资源包。import grapecity/spread-sheets-resources-zh; import * as GC from grapecity/spread-sheets; GC.Spread.Common.CultureManager.culture(zh-cn);注意spread-sheets-resources-zh要确保在设置 culture 之前加载完。这一步做完SpreadJS 内置的 UI 文案基本就中文化了。但业务自定义的文案比如你自己做的工具栏按钮文字还是得自己处理控件只负责内置部分。3. 核心功能落地实现3.1 数据绑定表格绑定、单元格绑定怎么选SpreadJS 的数据绑定有三套体系表格绑定TableBinding、单元格绑定CellBinding、模板绑定TemplateBinding。做项目之前分不清楚后面非常容易给自己挖坑。表格绑定适合列表型数据一列对应一个字段绑定后数据源和表格联动改数据源表格会刷新。物料台账就是这么做的。const data [ { code: M001, name: 轴承, spec: 6204, unit: 个, price: 12.5 }, { code: M002, name: 螺栓, spec: M8*30, unit: 个, price: 0.8 }, ]; const table sheet.tables.add(tbMaterial, 0, 0, 1, 5); table.bindingPath(dsMaterial); table.setColumnDataField(0, code); table.setColumnDataField(1, name); table.setColumnDataField(2, spec); table.setColumnDataField(3, unit); table.setColumnDataField(4, price); sheet.setDataSource({ dsMaterial: data });这里有一个容易踩的细节setDataSource的参数是一个对象对象的 key 必须和table.bindingPath()设置的路径一致数据才会映射进去。很多新手在这里直接传数组结果表格一片空白而且不报任何错排查起来非常难受。单元格绑定适合表单型布局。比如一张采购单里物料编码在 B2、供应商在 B3、采购数量在 B4这种一个个格子传值的方式就用单元格绑定。sheet.setBindingPath(1, 1, materialCode); sheet.setBindingPath(2, 1, supplier); sheet.setBindingPath(3, 1, quantity); sheet.setDataSource({ materialCode: M001, supplier: 某供应商, quantity: 100 });这种方式的优点是表单结构灵活缺点是修改数据源后需要手动管理同步。实际项目里我一般用表格绑定处理列表用单元格绑定处理表单各管各的别混。3.2 公式自动计算与性能挂起填报页面里有一列是合格品数量 日产量 × 合格率这种计算直接交给公式引擎。// 产量在第8列合格率在第9列合格品数量在第10列 for (let r 1; r 100; r) { sheet.setFormula(r, 9, IF(AND(H${r}, I${r}), H${r}*I${r}, )); }公式引擎的好处是上游单元格一变下游结果自动重算不需要前端手动更新。跨 sheet 引用同样支持写法是老朋友Sheet2!A1。但公式批量设置的时候要特别当心性能。如果循环几百行都setFormula而且不做任何挂起处理每一个公式都会触发一次绘制和一次计算页面会肉眼可见地卡顿。我的做法是先把绘制和计算全部挂起设置完成后再一次性恢复。sheet.suspendPaint(); sheet.suspendCalcService(); // 批量设置公式、赋值 sheet.resumeCalcService(); sheet.resumePaint();这个挂起-恢复的写法在 SpreadJS 项目里几乎天天用。凡是批量操作不管是赋值、设公式、改样式都建议先挂起。实测下来同样一批操作挂不挂起渲染时间能差出好几倍数据量上千行以后差距更夸张。3.3 Excel 导入导出与数据清洗导入导出是客户最看重的功能毕竟他们有大量历史 Excel 模板。导出核心代码是这样的import grapecity/spread-excelio; const excelIO new GC.Spread.Excel.IO(); spread.export( (blob) { const link document.createElement(a); link.download 台账导出.xlsx; link.href URL.createObjectURL(blob); link.click(); }, (e) { console.error(e.errorMessage); }, { fileType: GC.Spread.Sheets.ExportFileType.xlsx, includeStyles: true, includeFormulas: true, columnWidthsAsPixel: true, } );导出参数里有几个值得提。includeFormulas我建议必须开不开的话导出的是纯数值公式丢了客户拿到 Excel 文件发现没有公式会很崩溃。includeStyles控制样式是否保留不同版本的默认行为有差异项目上建议显式指定别依赖默认值。columnWidthsAsPixel这个参数影响列宽的单位换算有时候导出的文件在客户电脑上列宽异常就跟这个参数有关。导入 Excel 的关键在于文件解析。我用了 FileReader 读取 ArrayBuffer再交给 excelIO.open 解析成 SpreadJS 内部 JSON最后通过fromJSON加载到工作簿。fileInput.addEventListener(change, (e) { const file e.target.files[0]; const reader new FileReader(); reader.onload (ev) { excelIO.open(ev.target.result, (json) { spread.fromJSON(json); // 这里做数据清理 }); }; reader.readAsArrayBuffer(file); });导入之后我强烈建议做一遍脏数据清理。客户发的 Excel 里经常有合并单元格、空行、隐藏列、非法字符这些数据直接提交入库非常容易出问题。我的做法是导入后遍历一遍业务数据区域把空行标记出来、把隐藏列恢复、把明显的格式异常提示给用户等用户确认后再允许提交。3.4 单元格类型与数据验证物料分类、供应商名称这种字段不能让人随便填要做成下拉选择。SpreadJS 提供了多种单元格类型ComboBox 是其中之一。const combo new GC.Spread.Sheets.CellTypes.ComboBox(); combo.items([ { text: 原材料, value: raw }, { text: 半成品, value: semi }, { text: 产成品, value: finished }, ]); sheet.setCellType(3, 2, combo, GC.Spread.Sheets.SheetArea.viewport);setCellType最后一个参数指定区域一般用 viewport 就行。ComboBox 的 items 是{ text, value }结构text 是显示内容value 是实际值这两个字段名别写错写错的话下拉列表会空白。数据验证用来拦截错误输入。比如采购价格必须大于 0不满足就不给通过。const dv GC.Spread.Sheets.DataValidation.createNumberValidator( GC.Spread.Sheets.ComparisonOperator.greaterThan, 0, true ); dv.showError true; dv.errorMessage 采购价格必须大于0; dv.showInputMessage true; dv.inputMessage 请输入大于0的价格; sheet.setDataValidator(6, 5, dv);数据验证的价值在于把错误数据的拦截从后端提前到了前端用户在填表阶段就被提示了而不是等提交到后端才收到报错。企业用户对这种填错了当场告诉我的体验非常买账。4. 交互、框架配合与性能优化4.1 单元格事件与自定义操作除了展示和编辑表格还承载了不少业务交互。比如双击物料编码单元格就弹出历史价格查看这个通过事件绑定实现。spread.bind(GC.Spread.Sheets.Events.CellClick, (e, args) { const { row, col, sheet } args; if (col 0 row 0) { // 打开物料详情 } }); spread.bind(GC.Spread.Sheets.Events.ValueChanged, (e, args) { const { sheet, row, col, newValue, oldValue } args; if (col 5 !isValid(newValue)) { sheet.setValue(row, col, oldValue); // 提示用户输入不合法 } });事件参数里sheet是当前 sheet 实例row和col是触发单元格的行列索引。要注意args.newValue的类型并不总是字符串有时候是数字、有时候是对象处理前先判断类型。还有一个场景是右键菜单。默认右键菜单是 Excel 的一套包含剪切、复制、粘贴、插入行这些。如果需要业务菜单项可以在右键菜单 open 事件里动态添加。spread.bind(GC.Spread.Sheets.Events.OpenMenu, (e, args) { const menuData args.menuData; menuData.push({ text: 标记为已审核, command: () { // 业务处理 }, }); });这种自定义菜单能帮用户省掉很多切换页面的操作让表格真正融入业务流程。4.2 在 Vue/React 里使用的注意事项框架里用 SpreadJS最大的坑是生命周期和组件卸载。Vue 的onBeforeUnmount里一定要销毁实例。onBeforeUnmount(() { spread.destroy(); spread null; });不销毁的话组件反复切换时旧实例的事件监听、DOM 节点会一直留在内存里时间一长页面越来越卡甚至出现幽灵事件。我见过一个真实案例页面跳转再回来点击事件触发了两次排查到最后就是实例没销毁导致的事件叠加。另一个注意点是不要把 SpreadJS 的容器交给框架的响应式系统去反复渲染。div refhost这个容器尽量保持结构稳定不要用v-if控制显示隐藏否则框架的渲染时机和 SpreadJS 内部的布局机制冲突表格区域会变空白或者样式错乱。如果真要切换显示优先用v-show或者把初始化拆出来等容器可见时再实例化。4.3 大数据量渲染优化三板斧物料台账几千行数据不可能毫秒级全部渲染但用户体验必须顺畅。这里有三条实践我每次都照着做。第一挂起绘制再批量填充。所有 setValue、setFormula 操作包在suspendPaint和resumePaint之间这是最基础也最有效的优化。第二关闭不必要的计算。台账这种纯展示场景数据加载过程中不涉及公式联动可以先把计算服务挂起数据全部填充完再恢复。第三动态调整行列数不要在一个默认 200 行 × 100 列的 sheet 上硬塞数据。先确认业务最多要多少行再setRowCount动态设置。sheet.suspendPaint(); sheet.suspendCalcService(); sheet.setRowCount(data.length 2); for (let i 0; i data.length; i) { sheet.setValue(i 1, 0, data[i].code); sheet.setValue(i 1, 1, data[i].name); // 其他列 } sheet.resumeCalcService(); sheet.resumePaint();如果数据量到了几万行还可以考虑开启虚拟滚动让控件只渲染可视区域的行。开启后滚动性能会好很多代价是单元格渲染时机有细微差别某些需要预计算的场景要额外处理。4.4 容器尺寸自适应业务页面左侧有菜单栏、上方有筛选条件表格区域的高度不是固定的。如果只在 mounted 时给一个固定高度窗口一变化表格区域要么溢出、要么空白。我的做法是监听容器尺寸变化动态刷新。const observer new ResizeObserver(() { spread.refresh(); }); observer.observe(host.value);spread.refresh()会根据容器新尺寸重新布局。如果你希望表格跟着容器变宽变高CSS 上容器要用百分比或 viewport 单位并且在初始化时设置对应的列宽策略。还有一个小细节如果用户手动调整过列宽刷新时要注意列宽设置的单位避免观感出现细微偏差。5. 踩坑记录与常见问题速查5.1 我印象最深的两个问题第一个问题是导入 Excel 后公式全部变成 #NAME?。排查后发现客户 Excel 里用了中文函数名和特殊函数SpreadJS 的公式解析器不支持这些写法。解决办法是导入后统一做公式检查建一个函数名映射表把常见的中文函数名转换成英文写法实在转换不了的降级为静态值并给出提示。这个兜底逻辑上线后客户那边反馈明显变好。第二个问题是导出文件在 Windows 上打开时列宽异常。这种问题在开发环境Mac 或 Linux上根本重现不了只有到客户 Windows 电脑上才暴露。原因是不同系统字体渲染差异导致列宽的像素换算有偏差。解决办法是导出前先做一次autoFitColumn让列宽按内容自适应整体观感稳定很多。5.2 常见问题速查表现象可能原因解决方法表格高度为 0 或不可见容器无高度或初始化时机不对为容器设置确定高度容器挂载后再初始化中文菜单没生效未注册中文资源或 culture 设置错误引入 resources-zh 并执行CultureManager.culture(zh-cn)导出后公式丢失导出参数includeFormulas未开启显式设置includeFormulas: true公式结果不对计算服务被挂起后未恢复检查是否漏掉了resumeCalcService()组件反复切换越来越卡实例未销毁onBeforeUnmount里执行spread.destroy()单元格下拉列表空白ComboBox 的 items 格式错误确认 items 是{ text, value }结构导入的 Excel 公式报错公式函数名不兼容建函数映射表做兜底转换导出的列宽在 Windows 异常字体渲染差异导致像素换算偏差导出前执行autoFitColumn()大数据量滚动卡顿未开启虚拟滚动或样式过重挂起绘制、关闭不必要条件格式、开虚拟滚动5.3 几条值得记住的经验用 SpreadJS 这类商用控件做项目文档和示例其实是够用的但真实项目里最花时间的往往不是 API 不会用而是业务模型的梳理。比如数据是应该走前端绑定还是直接操作单元格这决定了后面维护的复杂度。我的建议是凡是结构化的业务数据优先用数据绑定体系去管理而不是一股脑往单元格里 setValue。单元格只是表现层数据层要跟业务模型保持一致后面做校验、提交、权限控制都会轻松很多。另外版本升级这件事别太抗拒。我在项目中期从 16 升到 17.0.7本来担心有破坏性变更结果整体迁移很顺利还顺手解决了一个旧版本里注释导出异常的问题。商用控件维护版追新稳定性收益往往大于升级成本。6. 后续还能怎么扩展这个项目目前交付了数据填报、校验、导入导出这几块其实 SpreadJS 如果想继续往深了做链路还能拉得很长。比如把表格和流程引擎结合做成数据填报 审批流一体化的平台业务员填完数据直接走审批领导在审批里看到的也是同一份在线表格再比如利用透视表功能做经营数据的在线分析让数据填报和数据分析在一个系统里闭环还有权限控制同一份数据按角色打散到不同的列和行做到不同人看到不同数据范围。这些方向都是以后可以继续打磨的。到那时候回头再看当初选型的决策会觉得这条路走对了。
给企业做数据系统这几年我最大的感受就是业务方嘴上说的是做个网页表格心里装的其实是把 Excel 给我搬到网页上还不能少功能。去年接的物料台账、数据填报系统就是典型项目编号 271702999从需求分析到上线排期几乎每个环节都绕不开表格能力。最后整个系统的在线表格部分我是用 SpreadJS 17.0.7 落地的从数据绑定、公式联动、Excel 导入导出到校验、权限、性能优化一整套下来踩了不少坑也攒了不少经验。今天这篇就把完整的选型思路、集成细节和避坑记录整理出来给准备在项目里上 SpreadJS 的朋友一份能直接参考的实操笔记。1. 项目背景与需求拆解1.1 客户要的不是表格是 Excel这个项目的业务场景分两块。第一块是物料主数据台账几千条物料的编码、名称、规格、单位、采购价、安全库存这些字段做成在线表格不同角色要能筛选、编辑、评论改完的数据按权限批量提交入库。第二块是月度生产数据填报各分厂业务员在系统里填产量、能耗、废品率等指标表格自带校验规则和跨表计算公式提交后要汇总成集团级报表。这两块需求听起来都叫表格实际做起来差异很大。台账侧重点是展示、编辑、批量提交就是对数据本身的操作填报侧重点是公式联动、校验拦截、汇总统计对计算能力的要求更高。但它们有一个共同点用户已经习惯了 Excel 的操作方式你在网页上做一个跟 Excel 长得差不多的表格他们能快速上手你做一个跟 Excel 不一样的东西哪怕是逻辑更好也会被嫌弃。所以核心诉求其实很清晰——在网页里把 Excel 的交互体验还原出来同时能把数据安全地送回后端。1.2 为什么选 SpreadJS 而不是自己写接这个项目的时候我先把市面上的路线过了一遍。第一条路是纯手写 HTML 表格加编辑功能做简单展示和单格编辑没问题但一旦遇到公式联动、行列拖拽、样式还原、合并单元格、筛选这些 Excel 常规操作开发量会迅速失控而且浏览器原生表格在渲染大数据量时性能瓶颈非常明显。第二条路是用服务端组件生成 Excel 文件这种只能解决导出一个文件的需求前端交互、即时计算、行内校验统统做不到跟在线编辑的要求相差太远。所以方向基本锁定在成熟的纯前端表格控件上。SpreadJS 是几个候选里综合评分最高的原因有三点。第一它本质上是把 Excel 的公式引擎、单元格类型、数据验证、条件格式这些能力复刻到了浏览器端JS 跑在本地交互即时响应不依赖网络请求。第二它对 .xlsx 文件的兼容性确实好客户那边积累了十几年的 Excel 模板字段、公式、样式都是按业务习惯排好的如果换套系统让他们重新做模板项目基本做不下去SpreadJS 可以直接导入这些模板数据回填、公式保留做到原来怎么在 Excel 里干活现在就怎么在网页里干活。第三是生态和文档比较完整遇到问题能查的资料足够多不会卡在某个 API 上出不来。1.3 版本 17.0.7 意味着什么选型时候我特意用了 17.0.7 而不是更早的稳定版。SpreadJS 每年会有一个大版本迭代17 系列在计算引擎和 Excel 兼容性上都有提升而 17.0.7 属于维护版本会把前面几个小版本里反馈的问题修掉一批。用维护版的好处是既能吃到新功能又不用承担大版本初期那些稳定性风险。项目上线到现在这个版本的表现确实对得起预期。2. 工程集成与基础初始化2.1 安装、引入、样式一个都不能少这个项目的技术栈是 Vue 3 Vite直接在工程里装 SpreadJS 的 npm 包就行。基础表格能力在grapecity/spread-sheets包里但 Excel 的导入导出是单独一个包grapecity/spread-excelio这两者要同时装。如果你还需要图表、打印、PDF 导出这些能力还要按需引入对应模块包这次的业务没涉及图表所以只装了下面三个。npm install grapecity/spread-sheets17.0.7 npm install grapecity/spread-excelio17.0.7 npm install grapecity/spread-sheets-resources-zh17.0.7除了 JS 逻辑样式也要引进来。这一步特别容易被忽略漏掉之后表格不是不能用而是外观会非常奇怪行列头、网格线、选中态的样式全都不对整体就一个素颜状态用户第一眼就会觉得系统没做完。import grapecity/spread-sheets/styles/gc.spread.sheets.css;还有一点要注意如果你在项目里用到了 SpreadJS 的在线表格编辑器Designer那需要安装的是grapecity/spread-designer以及对应样式API 体系和基础表格不完全一样别混用。2.2 页面容器与 Workbook 初始化SpreadJS 必须渲染在一个指定宽高的 DOM 容器里。我把它封装成了一个 Vue 组件模板里只有一个 div。div refhost stylewidth: 100%; height: calc(100vh - 160px)/div这里有个经验容器必须有确定的高度。只给宽度不给高度SpreadJS 渲染出来往往是一个高度为 0 的空区域怎么调都不出表格。上面我用的calc(100vh - 160px)是预留了顶部导航栏和筛选区的空间这个值在后面的章节里还会提到。初始化代码在onMounted里执行import * as GC from grapecity/spread-sheets; let spread; let sheet; onMounted(() { spread new GC.Spread.Sheets.Workbook(host.value, { sheetCount: 1 }); sheet spread.getActiveSheet(); sheet.setRowCount(500); sheet.setColumnCount(50); });初始化时如果把sheetCount设为 1工作簿会默认带一个 sheet名字是 Sheet1后面可以通过 API 动态增删。如果你需要多个 sheet也可以在初始化时直接给多一点比如sheetCount: 3再按业务需求改名、删减。我这边台账和填报分成了两个独立页面单页用 1 个 sheet 就够但如果你做一个多 Tab 的工作簿页面这个参数就能派上用场。2.3 授权码与中文资源SpreadJS 是商业控件授权码必须配置不然界面会带试用角标并且不定期弹授权提示。配置方式是在初始化之前设置。GC.Spread.Sheets.LicenseKey 你的授权码;授权码来自你购买的 License通常是企业授权一次配置全局生效。我建议把授权码放到环境变量里不同环境用不同 key不然授权信息写死在代码仓库里后面不好管理。中文资源这块默认的右键菜单、筛选下拉、导入导出提示都是英文的。要让界面变成中文需要单独引入本地化资源包。import grapecity/spread-sheets-resources-zh; import * as GC from grapecity/spread-sheets; GC.Spread.Common.CultureManager.culture(zh-cn);注意spread-sheets-resources-zh要确保在设置 culture 之前加载完。这一步做完SpreadJS 内置的 UI 文案基本就中文化了。但业务自定义的文案比如你自己做的工具栏按钮文字还是得自己处理控件只负责内置部分。3. 核心功能落地实现3.1 数据绑定表格绑定、单元格绑定怎么选SpreadJS 的数据绑定有三套体系表格绑定TableBinding、单元格绑定CellBinding、模板绑定TemplateBinding。做项目之前分不清楚后面非常容易给自己挖坑。表格绑定适合列表型数据一列对应一个字段绑定后数据源和表格联动改数据源表格会刷新。物料台账就是这么做的。const data [ { code: M001, name: 轴承, spec: 6204, unit: 个, price: 12.5 }, { code: M002, name: 螺栓, spec: M8*30, unit: 个, price: 0.8 }, ]; const table sheet.tables.add(tbMaterial, 0, 0, 1, 5); table.bindingPath(dsMaterial); table.setColumnDataField(0, code); table.setColumnDataField(1, name); table.setColumnDataField(2, spec); table.setColumnDataField(3, unit); table.setColumnDataField(4, price); sheet.setDataSource({ dsMaterial: data });这里有一个容易踩的细节setDataSource的参数是一个对象对象的 key 必须和table.bindingPath()设置的路径一致数据才会映射进去。很多新手在这里直接传数组结果表格一片空白而且不报任何错排查起来非常难受。单元格绑定适合表单型布局。比如一张采购单里物料编码在 B2、供应商在 B3、采购数量在 B4这种一个个格子传值的方式就用单元格绑定。sheet.setBindingPath(1, 1, materialCode); sheet.setBindingPath(2, 1, supplier); sheet.setBindingPath(3, 1, quantity); sheet.setDataSource({ materialCode: M001, supplier: 某供应商, quantity: 100 });这种方式的优点是表单结构灵活缺点是修改数据源后需要手动管理同步。实际项目里我一般用表格绑定处理列表用单元格绑定处理表单各管各的别混。3.2 公式自动计算与性能挂起填报页面里有一列是合格品数量 日产量 × 合格率这种计算直接交给公式引擎。// 产量在第8列合格率在第9列合格品数量在第10列 for (let r 1; r 100; r) { sheet.setFormula(r, 9, IF(AND(H${r}, I${r}), H${r}*I${r}, )); }公式引擎的好处是上游单元格一变下游结果自动重算不需要前端手动更新。跨 sheet 引用同样支持写法是老朋友Sheet2!A1。但公式批量设置的时候要特别当心性能。如果循环几百行都setFormula而且不做任何挂起处理每一个公式都会触发一次绘制和一次计算页面会肉眼可见地卡顿。我的做法是先把绘制和计算全部挂起设置完成后再一次性恢复。sheet.suspendPaint(); sheet.suspendCalcService(); // 批量设置公式、赋值 sheet.resumeCalcService(); sheet.resumePaint();这个挂起-恢复的写法在 SpreadJS 项目里几乎天天用。凡是批量操作不管是赋值、设公式、改样式都建议先挂起。实测下来同样一批操作挂不挂起渲染时间能差出好几倍数据量上千行以后差距更夸张。3.3 Excel 导入导出与数据清洗导入导出是客户最看重的功能毕竟他们有大量历史 Excel 模板。导出核心代码是这样的import grapecity/spread-excelio; const excelIO new GC.Spread.Excel.IO(); spread.export( (blob) { const link document.createElement(a); link.download 台账导出.xlsx; link.href URL.createObjectURL(blob); link.click(); }, (e) { console.error(e.errorMessage); }, { fileType: GC.Spread.Sheets.ExportFileType.xlsx, includeStyles: true, includeFormulas: true, columnWidthsAsPixel: true, } );导出参数里有几个值得提。includeFormulas我建议必须开不开的话导出的是纯数值公式丢了客户拿到 Excel 文件发现没有公式会很崩溃。includeStyles控制样式是否保留不同版本的默认行为有差异项目上建议显式指定别依赖默认值。columnWidthsAsPixel这个参数影响列宽的单位换算有时候导出的文件在客户电脑上列宽异常就跟这个参数有关。导入 Excel 的关键在于文件解析。我用了 FileReader 读取 ArrayBuffer再交给 excelIO.open 解析成 SpreadJS 内部 JSON最后通过fromJSON加载到工作簿。fileInput.addEventListener(change, (e) { const file e.target.files[0]; const reader new FileReader(); reader.onload (ev) { excelIO.open(ev.target.result, (json) { spread.fromJSON(json); // 这里做数据清理 }); }; reader.readAsArrayBuffer(file); });导入之后我强烈建议做一遍脏数据清理。客户发的 Excel 里经常有合并单元格、空行、隐藏列、非法字符这些数据直接提交入库非常容易出问题。我的做法是导入后遍历一遍业务数据区域把空行标记出来、把隐藏列恢复、把明显的格式异常提示给用户等用户确认后再允许提交。3.4 单元格类型与数据验证物料分类、供应商名称这种字段不能让人随便填要做成下拉选择。SpreadJS 提供了多种单元格类型ComboBox 是其中之一。const combo new GC.Spread.Sheets.CellTypes.ComboBox(); combo.items([ { text: 原材料, value: raw }, { text: 半成品, value: semi }, { text: 产成品, value: finished }, ]); sheet.setCellType(3, 2, combo, GC.Spread.Sheets.SheetArea.viewport);setCellType最后一个参数指定区域一般用 viewport 就行。ComboBox 的 items 是{ text, value }结构text 是显示内容value 是实际值这两个字段名别写错写错的话下拉列表会空白。数据验证用来拦截错误输入。比如采购价格必须大于 0不满足就不给通过。const dv GC.Spread.Sheets.DataValidation.createNumberValidator( GC.Spread.Sheets.ComparisonOperator.greaterThan, 0, true ); dv.showError true; dv.errorMessage 采购价格必须大于0; dv.showInputMessage true; dv.inputMessage 请输入大于0的价格; sheet.setDataValidator(6, 5, dv);数据验证的价值在于把错误数据的拦截从后端提前到了前端用户在填表阶段就被提示了而不是等提交到后端才收到报错。企业用户对这种填错了当场告诉我的体验非常买账。4. 交互、框架配合与性能优化4.1 单元格事件与自定义操作除了展示和编辑表格还承载了不少业务交互。比如双击物料编码单元格就弹出历史价格查看这个通过事件绑定实现。spread.bind(GC.Spread.Sheets.Events.CellClick, (e, args) { const { row, col, sheet } args; if (col 0 row 0) { // 打开物料详情 } }); spread.bind(GC.Spread.Sheets.Events.ValueChanged, (e, args) { const { sheet, row, col, newValue, oldValue } args; if (col 5 !isValid(newValue)) { sheet.setValue(row, col, oldValue); // 提示用户输入不合法 } });事件参数里sheet是当前 sheet 实例row和col是触发单元格的行列索引。要注意args.newValue的类型并不总是字符串有时候是数字、有时候是对象处理前先判断类型。还有一个场景是右键菜单。默认右键菜单是 Excel 的一套包含剪切、复制、粘贴、插入行这些。如果需要业务菜单项可以在右键菜单 open 事件里动态添加。spread.bind(GC.Spread.Sheets.Events.OpenMenu, (e, args) { const menuData args.menuData; menuData.push({ text: 标记为已审核, command: () { // 业务处理 }, }); });这种自定义菜单能帮用户省掉很多切换页面的操作让表格真正融入业务流程。4.2 在 Vue/React 里使用的注意事项框架里用 SpreadJS最大的坑是生命周期和组件卸载。Vue 的onBeforeUnmount里一定要销毁实例。onBeforeUnmount(() { spread.destroy(); spread null; });不销毁的话组件反复切换时旧实例的事件监听、DOM 节点会一直留在内存里时间一长页面越来越卡甚至出现幽灵事件。我见过一个真实案例页面跳转再回来点击事件触发了两次排查到最后就是实例没销毁导致的事件叠加。另一个注意点是不要把 SpreadJS 的容器交给框架的响应式系统去反复渲染。div refhost这个容器尽量保持结构稳定不要用v-if控制显示隐藏否则框架的渲染时机和 SpreadJS 内部的布局机制冲突表格区域会变空白或者样式错乱。如果真要切换显示优先用v-show或者把初始化拆出来等容器可见时再实例化。4.3 大数据量渲染优化三板斧物料台账几千行数据不可能毫秒级全部渲染但用户体验必须顺畅。这里有三条实践我每次都照着做。第一挂起绘制再批量填充。所有 setValue、setFormula 操作包在suspendPaint和resumePaint之间这是最基础也最有效的优化。第二关闭不必要的计算。台账这种纯展示场景数据加载过程中不涉及公式联动可以先把计算服务挂起数据全部填充完再恢复。第三动态调整行列数不要在一个默认 200 行 × 100 列的 sheet 上硬塞数据。先确认业务最多要多少行再setRowCount动态设置。sheet.suspendPaint(); sheet.suspendCalcService(); sheet.setRowCount(data.length 2); for (let i 0; i data.length; i) { sheet.setValue(i 1, 0, data[i].code); sheet.setValue(i 1, 1, data[i].name); // 其他列 } sheet.resumeCalcService(); sheet.resumePaint();如果数据量到了几万行还可以考虑开启虚拟滚动让控件只渲染可视区域的行。开启后滚动性能会好很多代价是单元格渲染时机有细微差别某些需要预计算的场景要额外处理。4.4 容器尺寸自适应业务页面左侧有菜单栏、上方有筛选条件表格区域的高度不是固定的。如果只在 mounted 时给一个固定高度窗口一变化表格区域要么溢出、要么空白。我的做法是监听容器尺寸变化动态刷新。const observer new ResizeObserver(() { spread.refresh(); }); observer.observe(host.value);spread.refresh()会根据容器新尺寸重新布局。如果你希望表格跟着容器变宽变高CSS 上容器要用百分比或 viewport 单位并且在初始化时设置对应的列宽策略。还有一个小细节如果用户手动调整过列宽刷新时要注意列宽设置的单位避免观感出现细微偏差。5. 踩坑记录与常见问题速查5.1 我印象最深的两个问题第一个问题是导入 Excel 后公式全部变成 #NAME?。排查后发现客户 Excel 里用了中文函数名和特殊函数SpreadJS 的公式解析器不支持这些写法。解决办法是导入后统一做公式检查建一个函数名映射表把常见的中文函数名转换成英文写法实在转换不了的降级为静态值并给出提示。这个兜底逻辑上线后客户那边反馈明显变好。第二个问题是导出文件在 Windows 上打开时列宽异常。这种问题在开发环境Mac 或 Linux上根本重现不了只有到客户 Windows 电脑上才暴露。原因是不同系统字体渲染差异导致列宽的像素换算有偏差。解决办法是导出前先做一次autoFitColumn让列宽按内容自适应整体观感稳定很多。5.2 常见问题速查表现象可能原因解决方法表格高度为 0 或不可见容器无高度或初始化时机不对为容器设置确定高度容器挂载后再初始化中文菜单没生效未注册中文资源或 culture 设置错误引入 resources-zh 并执行CultureManager.culture(zh-cn)导出后公式丢失导出参数includeFormulas未开启显式设置includeFormulas: true公式结果不对计算服务被挂起后未恢复检查是否漏掉了resumeCalcService()组件反复切换越来越卡实例未销毁onBeforeUnmount里执行spread.destroy()单元格下拉列表空白ComboBox 的 items 格式错误确认 items 是{ text, value }结构导入的 Excel 公式报错公式函数名不兼容建函数映射表做兜底转换导出的列宽在 Windows 异常字体渲染差异导致像素换算偏差导出前执行autoFitColumn()大数据量滚动卡顿未开启虚拟滚动或样式过重挂起绘制、关闭不必要条件格式、开虚拟滚动5.3 几条值得记住的经验用 SpreadJS 这类商用控件做项目文档和示例其实是够用的但真实项目里最花时间的往往不是 API 不会用而是业务模型的梳理。比如数据是应该走前端绑定还是直接操作单元格这决定了后面维护的复杂度。我的建议是凡是结构化的业务数据优先用数据绑定体系去管理而不是一股脑往单元格里 setValue。单元格只是表现层数据层要跟业务模型保持一致后面做校验、提交、权限控制都会轻松很多。另外版本升级这件事别太抗拒。我在项目中期从 16 升到 17.0.7本来担心有破坏性变更结果整体迁移很顺利还顺手解决了一个旧版本里注释导出异常的问题。商用控件维护版追新稳定性收益往往大于升级成本。6. 后续还能怎么扩展这个项目目前交付了数据填报、校验、导入导出这几块其实 SpreadJS 如果想继续往深了做链路还能拉得很长。比如把表格和流程引擎结合做成数据填报 审批流一体化的平台业务员填完数据直接走审批领导在审批里看到的也是同一份在线表格再比如利用透视表功能做经营数据的在线分析让数据填报和数据分析在一个系统里闭环还有权限控制同一份数据按角色打散到不同的列和行做到不同人看到不同数据范围。这些方向都是以后可以继续打磨的。到那时候回头再看当初选型的决策会觉得这条路走对了。
