文档技术博客教程【免费下载链接】weekly前端精读周刊。帮你理解最前沿、实用的技术。项目地址https://gitcode.com/GitHub_Trending/we/weekly点击查看免费下载Excel 如今可以利用 JavaScript 根据单元格数据生成图表、表格或通过 JS 拓展自定义函数来增强内置 Excel 表达式。本篇精读以微软 Excel JavaScript API 的开放设计为研究对象拆解其「为什么开放 JS API」「能力覆盖范围」以及「以 Range 为核心、以Excel.runcontext.sync()为骨架」的命令式 API 设计哲学帮助读者理解这套开放 API 的抽象思路并从中提炼可复用的开放 API 设计经验。为什么需要开放 JS APIExcel 本身已经具备良好的易用性以及formula公式这个强大的能力。正如仓库往期精读 精读《Microsoft Power Fx》 中提到的formula 就是 Excel 里的 Power Fx属于画布低代码语言不过在 Excel 里叫做公式更合适——它描述的是做什么而不是如何做。既然 Excel 已经具备了这么多能力为何还需要 JS API 呢一句话概括就是在 JS API 内可以使用 formula即 JS API 是公式能力的超集。它包含了对 Excel 工作簿的增删改查、数据的限制、RangeAreas 操作、图表、透视表甚至可以自定义 formula 函数。也就是说JS API 让 Excel 可编程化——以开发者视角对 Excel 进行二次拓展包括对公式进行二次拓展使 Excel 覆盖更多场景。如果说 formula 面向的是普通用户那么 JS API 面向的就是开发者二者是同一份数据模型在不同人群面前的两种呈现方式。JS API 可以用在哪些地方从 Excel 流程中最开始的工作簿、工作表环节到最细节的单元格数据校验都可通过 JS API 支持。从能力边界上看Excel JS API 并没有刻意设置能力边界而是将 Excel 全生命周期中一切可编程的地方持续开放出来。整体可以划分为三个层次第一层工作簿与工作表级操作。包括对工作簿、工作表的操作对工作表用户操作的监听以及对工作表进行只读设置。这一类 API 的目的是对 Excel 这个整体进行编程操作是开放 API 的入口层。第二层单元格级操作。比如对单元格进行区域选中、获取选中区域、设置单元格属性与颜色、对单元格数据进行校验。自定义公式也发生在这个环节——因为单元格的值可以是公式而公式可以利用 JS API 拓展把单元格里放什么这件事交给代码决定。第三层拓展行为。在单元格基础上引入图表、透视表等拓展。虽然这些功能在 UI 按钮上也可以操作出来但 JS API 可以实现 UI 界面配置不出来的逻辑对于非常复杂的逻辑行为即便 UI 可以配置出来可读性也远没有代码高。除了表格、透视表外还可以创建自定义形状——基本的几何图形、图片和 SVG 都支持。这与仓库 精读《前端与 BI》 中描述的 BI 数据链路形成呼应前端 BI 的核心是数据集 数据模型 可视化而 Excel JS API 恰恰把数据集的二维表格直接作为开放的编程对象图表、透视表则是建立在这份结构化数据之上的数据二次分析行为。JS API 设计为什么抽象 Range 而不是 Cell比较有趣的是Excel 并没有抽象单元格对象即便我们所有人都认为单元格就是 Excel 的代表。这么做是出于 API 设计的合理性因为 Excel 使用Range概念表示连续单元格。比如下面这段写入表头并设置样式的代码Excel.run(function (context) { var sheet context.workbook.worksheets.getActiveWorksheet(); var headers [ [Product, Quantity, Unit Price, Totals] ]; var headerRange sheet.getRange(B2:E2); headerRange.values headers; headerRange.format.fill.color #4472C4; headerRange.format.font.color white; return context.sync(); });可以发现Range让 Excel 聚焦在批量单元格 API——即把单元格看做一个范围整体 API 都可以围绕一个范围去设计。这种设计理念的好处是把范围局限在单个单元格就可以覆盖Cell概念聚焦在多个单元格时可以很方便地基于二维数据结构创建表格、折线图等分析图形因为二维结构的数据才是结构化数据。或者可以说结构化数据是 Excel 最核心的概念而单元格无法体现结构化。结构化数据的好处是一张工作表就是一个可以用来分析的数据集在其之上无论是基于单元格的条件格式还是创建分析图表都是一种数据二次分析行为这都得益于结构化数据。所以 Excel JS API 必然围绕结构化数据进行抽象——用 Range 覆盖二维数据块这一基本单位而不是面向孤立的单格。从仓库其它精读文档也能看到类似思路的普遍性无论是 精读《前端与 BI》 中把数据集定义为列头表示字段、每行一份数据的二维表格还是 精读《SQL vs Flux》 中强调查询应基于结构化数据模型展开二维结构化数据都是数据分析类产品 API 设计的地基。Excel JS API 将这一共识落实到了最底层的Range抽象上。Excel.run 与 context.sync命令式 API 的骨架再从 API 语法来看除了工作簿这个级别的 API 采用了Excel.createWorkbook();之外其他大部分 API 都是以下形式Excel.run(function (context) { // var sheet context.workbook.worksheets.getItem(Sample); // 对 sheet 操作 .. return context.sync(); });最外层的函数Excel.run是注入context用的同时可以保证执行的时候 Excel context 已经准备好了。而context.sync()是同步操作——即把当前对 context 的操作真正生效。所以 Excel JS API 是命令式的也不会做类似 MVVM 的双向绑定。在操作过程中数据和 Excel 状态不会发生变化直到执行context.sync()。这套机制带来两个重要推论批量操作天然成立在sync()之前可以连续对多个对象、多个属性赋值它们会被合并成一次同步请求减少与 Excel 宿主之间的往返通信开销读取必须显式触发通过context拿到的对象如Range、Worksheet只是代理proxy对象属性值默认是空的必须调用load(属性名)声明要读取的属性再执行context.sync()才能真正取回数值。理解了这一点就能明白为什么某些代码要写在context.sync().then里了比如下面这个从透视表获取数据的例子Excel.run(function (ctx) { var pivotTable context.workbook.worksheets.getActiveWorksheet().pivotTables.getItem(Farm Sales); // Get the totals for each data hierarchy from the layout. var range pivotTable.layout.getDataBodyRange(); var grandTotalRange range.getLastRow(); grandTotalRange.load(address); return context.sync().then(function () { // Sum the totals from the PivotTable data hierarchies and place them in a new range, outside of the PivotTable. var masterTotalRange context.workbook.worksheets.getActiveWorksheet().getRange(E30); masterTotalRange.formulas [[SUM( grandTotalRange.address )]]; }); }).catch(errorHandlerFunction);这里的关键点在于只有执行context.sync()后才能拿到grandTotalRange.address。因为grandTotalRange是代理对象.address在load(address)之前并不真实存在于 JS 侧load只是登记了我需要这个属性sync()才真正向 Excel 发起请求并填充该属性。因此后续构造SUM(E2:E29)这样的公式字符串必须放在sync()完成之后.then回调内执行。同时整个调用链用.catch(errorHandlerFunction)兜底这与仓库中 精读《捕获所有异步 error》 强调的异步错误处理思路一致Excel.run返回的 Promise 上统一挂载错误处理器避免未捕获的拒绝中断脚本。可复制的最小运行骨架综合以上机制一个可复现的 Excel JS API 脚本骨架通常包含四个固定环节Excel.run(function (context) { // 1. 获取对象工作簿 - 工作表 - Range var sheet context.workbook.worksheets.getActiveWorksheet(); var range sheet.getRange(A1:C3); // 2. 写入/修改对代理对象赋值不会立即生效 range.values [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; range.format.font.bold true; // 3. 读取声明load 需要读回的属性 range.load(address); // 4. 同步真正让修改生效、把 load 的属性填充回来 return context.sync().then(function () { console.log(写入完成 range.address); }); }).catch(function (error) { console.log(Error: error); });从源码结构看Excel.run、context.sync()、load、代理对象这套模式贯穿所有 Excel JS API 示例理解了写入靠赋值、读取靠 load sync这一对约定就能顺藤摸瓜看懂任何一段 Excel JS API 代码。总结ScriptLab 与通用 API微软还在 Office 套件 Excel、Outlook、Word 中推出了ScriptLab功能可以在 Excel 的 ScriptLab 里直接编写 Excel JS API——它充当了官方 REPL的角色让开发者无需搭建完整加载项工程即可试验 API 行为极大降低了上手门槛。在 Excel JS API 之上还有一个通用 APIOffice JavaScript API 中跨应用共用的部分定义为跨应用的通用 API。这样 Excel JS API 就可以把精力聚焦在 Excel 产品本身能力上而不必为每个 Office 应用重复实现基础的宿主交互、上下文管理等通用能力。这种通用层 产品专用层的分层设计同样是开放平台 API 值得借鉴的结构通用层负责跨产品的一致性专用层负责产品差异化能力的深度开放。回顾全文Excel JS API 的开放设计可以提炼出三条经验以数据模型而非 UI 概念为抽象核心用Range覆盖二维结构化数据而非孤立地抽象单元格这让表格、图表、透视表等一切数据二次分析能力都能建立在同一抽象之上命令式 显式同步通过Excel.run(context)注入上下文、以代理对象累积操作、用context.sync()统一提交既保证了批量性能也让数据流的边界清晰可预期能力分层开放从工作簿/工作表到单元格与公式再到图表与透视表拓展层层递进且通过通用 API 与产品专用 API 的切分保持开放面的整洁。对于任何想为复杂产品开放编程能力的团队来说这套设计——先抽象出产品最核心的数据结构再围绕它设计批量化的命令式 API最后提供低门槛的试验环境——都值得在动手写第一行 API 之前认真参考。延伸阅读本仓库 精读《Microsoft Power Fx》 从画布低代码语言角度讲解了 formula 背后的语言设计精读《前端与 BI》 阐述了数据集、渲染引擎、数据模型与可视化四大模块与 Excel JS API 的开放能力互为印证。赞分享文档技术博客教程【免费下载链接】weekly前端精读周刊。帮你理解最前沿、实用的技术。项目地址https://gitcode.com/GitHub_Trending/we/weekly点击查看免费下载相关推荐Blender For Unreal Engine摄像机导出完全攻略从Blender到Unreal SequencerBlender For Unreal Engine摄像机导出完全攻略从Blender到Unreal Sequencer Blender For Unreal开发工具游戏开发Redux Thunk逻辑抽象库设计API与扩展性Redux Thunk逻辑抽象库设计API与扩展性 Redux Thunk作为Redux生态中最基础的异步逻辑处理中间件其设计哲学围绕最小接口、最大扩展前端Area51跨平台输入统一API与设备抽象设计Area51跨平台输入统一API与设备抽象设计 在游戏开发中不同平台PC、PS2、Xbox等的输入设备差异常常导致开发效率低下和兼容性问题。Area51上一篇Fluxer HTTP API 错误响应权威指南错误信封、状态回退映射与错误码注册表下一篇实测手记百度文库文档提取只用 1 个脚本3 步免费保存文库全文创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考