ooxml-excel-editor 1.14.1 → 1.15.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.15.1] - 2026-06-25
+
+> 修非 HTTPS / 内网 IP 部署下复制静默失败。纯增量,HTTPS / localhost 行为字节级不变、零回归。
+
+### 修复 — 复制兼容非安全上下文(内网 HTTP / 局域网 IP)
+
+- **现象**:在 `http://192.168.x.x:port` 或内网 HTTP 域名访问时,右键菜单「复制」/ Ctrl+C 点了无反应。
+- **根因**:复制(`ViewerController.copySelection` / `copyMultiSelection`)只用 `navigator.clipboard.write` / `writeText`,这俩受浏览器 Secure Context 约束 —— 非 HTTPS 且非 loopback 时 `navigator.clipboard` 为 `undefined`,`else` 分支调用直接抛 `TypeError`,被 `catch` 静默吞掉。内网部署的企业级应用(OKR/ERP/工单,普遍不挂 HTTPS)因此完全用不了复制。
+- **修法**:新增框架无关 helper [`src/core/edit/clipboard-write.ts`](./src/core/edit/clipboard-write.ts) `writeClipboard(tsv, html?)` 双路径 —— ① 安全上下文仍走异步 Clipboard API(`ClipboardItem` 同时写 `text/plain` + `text/html`,**1:1 保真 / 图片 / 格式 / `data-ooxml-clip` 快照全不变**);② 不可用 / 抛异常时退到 `document.execCommand('copy')`,临时 `copy` 监听器照样 `setData` 双 MIME(富表格 + 内嵌快照仍能粘进 Excel/Word/本组件)。`copySelection` / `copyMultiSelection` 两处重复内联块收敛到此 helper。
+- **影响**:HTTPS / localhost 用户走原路径,行为完全一致;内网 HTTP 用户从"复制无效"恢复为可用。纯 core 修复,Vue 3 / React / Vue 2 三壳零改动自动获得。
+- 新增 [`src/core/edit/__tests__/clipboard-write.test.ts`](./src/core/edit/__tests__/clipboard-write.test.ts) 锁回归(安全上下文 / 内网兜底 / 无权限降级 / headless,4 测)。
+
+## [1.15.0] - 2026-06-15
+
+> 纯 Node(headless)用法闭环 —— 让"解析取数"与"高保真往返编辑"在无浏览器/无 canvas 的 Node 里好用。纯增量,默认行为不变、零回归。
+
+### 新增 — Node 友好的入口 / 出口(框架无关 core)
+
+- **`openWorkbook(src)`**:一行门面 = `loadArrayBuffer` 归一化 + `parseWorkbook`,Node 可直接吃 `fs.readFileSync()` 的 **Buffer**(Buffer 是 Uint8Array 子类),浏览器侧仍接受 File/Blob/ArrayBuffer/URL。
+- **`parseWorkbook` 放宽入参** 为 `ArrayBuffer | Uint8Array` 并在内部归一化 —— 老 ArrayBuffer 调用 100% 兼容,Node 传 Buffer/Uint8Array 不再 TS 报错或踩坑。
+- **`workbookToXlsxBytes(wb, opts)`**:返回 `Uint8Array`(不是浏览器 `Blob`),纯 Node `fs.writeFileSync` 直接落盘;`fidelity: 'overlay' + sourceBuffer` 保真往返。`workbookToXlsxBlob` 改为它 + Blob 包装,签名/行为不变。
+- **导出建表 API**:`jsonToWorkbook` / `isWorkbookModel` / `makeDefaultStyle`(及 `JsonInput`/`JsonLoadOptions` 类型)补进 core 出口 —— 可在 Node 从数据(2D 数组 / 对象数组)直建模型再 `workbookToXlsxBytes` 生成 .xlsx。四入口同源,各壳自动可见。
+
+### 文档 / 示例 / 测试
+
+- README 新增 **「Node / 服务端 (headless) 用法」** 节(取数 / 高保真往返 / 数据建表三段可跑代码 + headless 不可用清单);英文区加对应段。EXTENDING.md 加 **「Headless / Node 安全 API 面」**(纯 Node 可用 vs 需浏览器的导出清单)。
+- **修正过时安装文档**:`exceljs` / `fflate` / `jspdf` / `hyperformula` 1.3.2+ 已**内联进 dist**,README 各处 `npm i ... exceljs` → 去掉(只需装 framework;纯 Node 仅 `npm i ooxml-excel-editor`)。入口表 peer 列 + "exceljs 为 peer" 旧述一并更正。
+- 新增 [`examples/node-extract.mjs`](./examples/node-extract.mjs) / [`examples/node-roundtrip.mjs`](./examples/node-roundtrip.mjs) 可跑示例;新增 `src/core/__tests__/node-headless.test.ts` 回归网(openWorkbook 吃 Buffer / 取数 / 往返 bytes / 数据建表,5 测)。
+
 ## [1.14.1] - 2026-06-15
 
 > 文档审计 + 入口出口修正(无运行时行为变更)。一次"保证接入/二开都没问题"的体检。

package/README.md

@@ -64,43 +64,96 @@ const src = ref<File>() // 绑个 <input type="file" @change> 给它即可
 
 ## 安装
 
-一个包,**四个子入口** —— 框架无关的 core 引擎被 Vue 3 / React 两个壳共享(`dist/core.js` 只打一份),Vue 2 因 SFC 编译器跟 Vue 3 冲突独立打包(内嵌 core)。按你的框架装对应 peer:
+一个包,**四个子入口** —— 框架无关的 core 引擎被 Vue 3 / React 两个壳共享(`dist/core.js` 只打一份),Vue 2 因 SFC 编译器跟 Vue 3 冲突独立打包(内嵌 core)。**只需按框架装对应 framework**,`exceljs` / `fflate` / `jspdf` / `hyperformula` 等重依赖 **1.3.2+ 已内联进 dist,无需手动装**:
 
 ```bash
 # Vue 3 项目
-npm i ooxml-excel-editor vue exceljs
+npm i ooxml-excel-editor vue
 
 # React 项目
-npm i ooxml-excel-editor react react-dom exceljs
+npm i ooxml-excel-editor react react-dom
 
 # Vue 2.6.x 或 2.7+ 项目 (1.3.0+) — 必装 @vue/composition-api (兼容 2.6 + 2.7)
-npm i ooxml-excel-editor vue@2.7 @vue/composition-api exceljs
+npm i ooxml-excel-editor vue@2.7 @vue/composition-api
 # Vue 2.6.x 还需 main.js: Vue.use(require('@vue/composition-api').default)
 
-# 只解析 / 读数据 / 导出(不渲染 UI)
-npm i ooxml-excel-editor exceljs
-
-# echarts 可选:仅渲染图表时需要;jspdf 可选:仅导出 PDF 时需要
-npm i echarts jspdf
-# hyperformula 可选:仅开启编辑 + 公式重算(recalc)时需要
-npm i hyperformula
+# 纯 Node / 只解析读数据 / 导出(不渲染 UI,无框架)
+npm i ooxml-excel-editor
 ```
 
 四个入口:
 
-| import | 内容 | 需要的 peer | 体积 (gzip) |
+| import | 内容 | 需要装的 framework | 体积 (gzip) |
 |---|---|---|---|
-| `ooxml-excel-editor` | **Vue 3** 组件 `<ExcelViewer>` (参考实现 Standard) | `vue@3` + `exceljs` | ~19 KB + 共享 chunks |
-| `ooxml-excel-editor/react` | **React** 组件 `<ExcelViewer>` (1:1 复刻 Vue 3) | `react` + `react-dom` + `exceljs` | ~11 KB + 共享 chunks |
-| `ooxml-excel-editor/vue2` | **Vue 2.6 / 2.7+** 组件 `<ExcelViewer>` (1:1 复刻 Vue 3) | `vue@2.6+` + `@vue/composition-api` + `exceljs` | ~124 KB (内嵌 core) |
-| `ooxml-excel-editor/core` | 框架无关引擎(解析/渲染/控制器/导出/读数据) | `exceljs` | ~1 KB + 共享 chunks |
+| `ooxml-excel-editor` | **Vue 3** 组件 `<ExcelViewer>` (参考实现 Standard) | `vue@3` | ~19 KB + 共享 chunks |
+| `ooxml-excel-editor/react` | **React** 组件 `<ExcelViewer>` (1:1 复刻 Vue 3) | `react` + `react-dom` | ~11 KB + 共享 chunks |
+| `ooxml-excel-editor/vue2` | **Vue 2.6 / 2.7+** 组件 `<ExcelViewer>` (1:1 复刻 Vue 3) | `vue@2.6+` + `@vue/composition-api` | ~124 KB (内嵌 core) |
+| `ooxml-excel-editor/core` | 框架无关引擎(解析/渲染/控制器/导出/读数据) | 无(纯 Node 也可用,见 [Node 用法](#node--服务端-headless-用法)) | ~1 KB + 共享 chunks |
 
-`exceljs` 必需;`vue` / `react` / `vue@2` 按框架三选一(均为可选 peer);`echarts` / `jspdf` / `hyperformula` 为**可选** peer —— 未装分别只影响"图表渲染""PDF 导出""公式重算",其余正常,且**绝不打包进你的产物**(运行时才动态加载)。
+`vue` / `react` / `vue@2` 按框架三选一(均为可选 peer);`exceljs` / `fflate` / `jspdf` / `hyperformula` **已内联进 dist**(无需装、也**绝不重复进你的产物**,运行时才动态从 chunk 加载);`echarts` 是 external 依赖(npm 自动装,仅图表渲染才真正加载,避免主题 dual instance)。
 
 > **三壳 UI 1:1**: Vue 3 SFC 是参考实现 (Standard), Vue 2 / React 1:1 复刻视觉与交互 (工具栏 SVG 图标 / 下拉子菜单 / 公式栏 / 状态栏 / dialog / 浮层 / 演示 demo 全部对齐). 详见 [docs/Vue2.md](./docs/Vue2.md) 跟 Vue 3 的差异速查 + [CLAUDE.md](./CLAUDE.md) 第 7 中心原则。
 
 > 公式重算的引擎(1.14.0 起):默认是**内置 MIT 引擎**(零依赖,覆盖 ~60 常用函数,无许可证负担)。需要更全函数集时,`formulaEngine` prop 注入 **HyperFormula**(`hyperFormulaEngineFactory`,GPL-3.0/商业双授权,~395 函数)或自研引擎(实现 `FormulaEngine` 接口)。
 
+## Node / 服务端 (headless) 用法
+
+不渲染 UI、纯在 **Node**(无浏览器、无 canvas)里处理 .xlsx —— 走 `ooxml-excel-editor/core`(框架无关、ESM)。装包只需 `npm i ooxml-excel-editor`(`exceljs` 等已内联)。可跑示例见 [`examples/`](./examples)。
+
+**适合 Node 的两件事**(比裸 `exceljs` 多了"显示文本渲染 / 合并 / 日期 / 富文本"的保真):
+
+**① 解析取数** —— 拿"人看到的"数据(显示文本 / JSON / CSV):
+
+```ts
+import { readFileSync } from 'node:fs'
+import { openWorkbook, getSheetData, sheetToJSON, getCellText, toCsv } from 'ooxml-excel-editor/core'
+
+// openWorkbook 直接吃 Node Buffer —— 不必手动转 ArrayBuffer
+const wb = await openWorkbook(readFileSync('input.xlsx'))
+const sheet = wb.sheets[0]
+
+getCellText(sheet, 0, 0)               // 单格显示文本(数字格式/日期已渲染,如 "2021年1月")
+getSheetData(sheet, { format: true })  // 2D 数组(format:false 给原始值)
+sheetToJSON(sheet)                      // 对象数组(首行当表头)
+toCsv(sheet)                            // CSV 文本
+```
+
+**② 高保真往返编辑** —— 打开真实 .xlsx → 程序化改值/样式 → 保样式回写(`overlay` 保留原件的样式/条件格式/图片/透视表,裸 exceljs 会丢):
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs'
+import { openWorkbook, setCellValue, applyStyleOverride, workbookToXlsxBytes } from 'ooxml-excel-editor/core'
+
+const src = readFileSync('input.xlsx')
+const wb = await openWorkbook(src)
+const sheet = wb.sheets[0]
+
+setCellValue(sheet, 1, 2, 123.45)
+applyStyleOverride(sheet, 1, 2, { font: { bold: true, color: '#FF0000' } })
+
+// workbookToXlsxBytes 返回 Uint8Array(不是浏览器 Blob),直接 fs 落盘
+const bytes = await workbookToXlsxBytes(wb, {
+  fidelity: 'overlay',
+  sourceBuffer: src.buffer.slice(src.byteOffset, src.byteOffset + src.byteLength),
+})
+writeFileSync('output.xlsx', bytes)
+```
+
+**③ 从数据建表**(可选;纯建表裸 `exceljs` 也行)—— `jsonToWorkbook` → `workbookToXlsxBytes`:
+
+```ts
+import { writeFileSync } from 'node:fs'
+import { jsonToWorkbook, workbookToXlsxBytes } from 'ooxml-excel-editor/core'
+
+const wb = jsonToWorkbook(
+  [{ name: '张三', age: 25 }, { name: '李四', age: 30 }],
+  { sheetName: 'People' },
+)
+writeFileSync('new.xlsx', await workbookToXlsxBytes(wb))
+```
+
+**Node headless 下不可用**(硬依赖浏览器 canvas / DOM,需在浏览器或 Electron 渲染进程跑):图片/PNG/JPEG 与 **PDF 导出**、`print()`、`downloadBlob`、内置 `DefaultEditor` 编辑器、`<ExcelViewer>` 组件渲染。另:`finalizeImages` 在 Node 会安全跳过(图片保留 `bytes`/`mime`,不生成 blob URL);URL 字符串入参走 `fetch`,**Node 用 `fs` 读 Buffer,别传本地路径字符串**。纯 Node 可用的导出面见 [EXTENDING.md](./EXTENDING.md#headless--node-安全-api-面)。
+
 ## 使用
 
 ### Vue
@@ -339,12 +392,12 @@ viewer.value.getRangeData(viewer.value.getSelection())  // 取"我选中的"区
 |---|---|
 | `ExcelViewer` | 预览/编辑组件(各框架入口各自的) |
 | `default` | Vue 3 / Vue 2 入口默认导出 = Vue 插件(`app.use`) |
-| **解析/加载** | `parseWorkbook(buffer)`(`ArrayBuffer → Promise<WorkbookModel>`,优先 Worker)· `loadArrayBuffer(src)`(多种输入归一) |
+| **解析/加载** | `openWorkbook(src)`(一行门面 = 归一化 + 解析,Node/浏览器通用)· `parseWorkbook(buffer)`(`ArrayBuffer\|Uint8Array → Promise<WorkbookModel>`,优先 Worker)· `loadArrayBuffer(src)`(多种输入归一)· `jsonToWorkbook(data)`(数据直建模型) |
 | **读数据 API** | `getCellValue` / `getCellText` / `getCellStyle` / `getSheetData` / `getRangeData` / `sheetToJSON` / `getWorkbookJSON` / `cellDisplayText` |
 | **格式/工具** | `formatValue`(数字格式)· `cellKey` · `colIndexToLetters` |
 | **插件 / 主题** | `definePlugin` · `DEFAULT_THEME` / `mergeTheme` |
 | **公式引擎**(1.14.0) | `builtinFormulaEngineFactory`(默认,MIT)· `hyperFormulaEngineFactory`(HyperFormula,GPL/商业)· `FUNCTION_NAMES`(已支持函数名)· `BuiltinFormulaEngine` |
-| **导出工具** | `workbookToXlsxBlob` · `toCsv` / `toWorkbookJson` · `canvasToBlob` / `canvasToDataURL` / `downloadBlob` |
+| **导出工具** | `workbookToXlsxBytes`(→ `Uint8Array`,**纯 Node 落盘用**)· `workbookToXlsxBlob`(→ `Blob`,浏览器下载用)· `toCsv` / `toWorkbookJson` · `canvasToBlob` / `canvasToDataURL` / `downloadBlob`(后三者需浏览器) |
 | **类型** | `WorkbookModel` / `SheetModel` / `CellModel` / `CellStyle` / `CellStyleOverride` / `MergeRange` / `ConditionalRule` / `DataValidationRule` / `ChartSpec` / `ImageAnchor` / `PivotTableModel` / `CssColor` / `ExcelSource` / `ViewerApi` / `ExcelPlugin` / `FormulaEngine` / `FormulaEngineFactory` / `EditConfig` / 导出选项类型(`PdfExportOptions`/`ImageExportOptions`/…)等 |
 
 > 想看完整出口清单见 [`src/core/index.ts`](src/core/index.ts);深度二开(直接用 `ViewerController` / `CanvasRenderer` / `EditController` / 模型 mutations 等内部件)也都从这些入口导出,见 [ARCHITECTURE.md](ARCHITECTURE.md)。
@@ -480,7 +533,7 @@ const myEditor: EditorResolver = (cell, pos) => {
 
 现代浏览器(Chrome/Edge 80+、Safari 15+、Firefox 114+,需支持 Canvas / ResizeObserver)。
 
-> **解析线程**:发布的组件库在**主线程**解析(`exceljs` 为 peer 依赖,不重复打包)。本仓库的 demo/dev 额外启用了 **Web Worker** 解析(大文件不卡 UI)。如果你的应用要处理很大的文件,可直接用导出的 `parseWorkbook` 包进你自己的 Worker。
+> **解析线程**:发布的组件库在**主线程**解析(`exceljs` 1.3.2+ 已内联进 dist chunks,运行时动态加载,不重复进你的产物)。本仓库的 demo/dev 额外启用了 **Web Worker** 解析(大文件不卡 UI)。如果你的应用要处理很大的文件,可直接用导出的 `parseWorkbook` 包进你自己的 Worker。
 
 ## 范围边界
 
@@ -530,10 +583,10 @@ MIT
 
 **🔗 Live demo: https://ojadeveloper.github.io/ooxml-excel-editor/**
 
-A **Vue 3 + Vue 2 + React high-fidelity `.xlsx` preview & edit component** with a from-scratch parser and canvas renderer. Renders cells, number formats, merges, conditional formatting, images, charts (via ECharts), sparklines, comments, data validation, frozen panes, and supports selection / copy / hyperlinks. **Read-only by default**; set `editable` to enable editing — cell values / styles / column-row sizes / floating images / insert-delete rows-cols, with undo-redo, before/after full-snapshot events, dirty tracking + reset-to-original, swappable formula recalc engine, custom cell editors, and **export back to .xlsx / JSON / CSV**. Parsing runs in a Web Worker (with main-thread fallback). `vue` / `react` / `exceljs` are peer dependencies; `echarts` / `jspdf` / `hyperformula` are optional peers (charts / PDF / formula recalc).
+A **Vue 3 + Vue 2 + React high-fidelity `.xlsx` preview & edit component** with a from-scratch parser and canvas renderer. Renders cells, number formats, merges, conditional formatting, images, charts (via ECharts), sparklines, comments, data validation, frozen panes, and supports selection / copy / hyperlinks. **Read-only by default**; set `editable` to enable editing — cell values / styles / column-row sizes / floating images / insert-delete rows-cols, with undo-redo, before/after full-snapshot events, dirty tracking + reset-to-original, swappable formula recalc engine, custom cell editors, and **export back to .xlsx / JSON / CSV**. Parsing runs in a Web Worker (with main-thread fallback). Only the framework (`vue` / `react`) is a peer dependency; `exceljs` / `fflate` / `jspdf` / `hyperformula` are bundled into `dist` (no manual install).
 
 ```bash
-npm i ooxml-excel-editor vue exceljs
+npm i ooxml-excel-editor vue
 ```
 
 ```ts
@@ -541,4 +594,22 @@ import { ExcelViewer } from 'ooxml-excel-editor'
 import 'ooxml-excel-editor/style.css'
 ```
 
+**Headless / Node (no browser):** use `ooxml-excel-editor/core` to parse `.xlsx`, extract data, edit and write back — no canvas needed. `npm i ooxml-excel-editor` only.
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs'
+import { openWorkbook, sheetToJSON, setCellValue, workbookToXlsxBytes } from 'ooxml-excel-editor/core'
+
+const src = readFileSync('input.xlsx')
+const wb = await openWorkbook(src)              // accepts a Node Buffer directly
+const rows = sheetToJSON(wb.sheets[0])          // array of row objects (display text)
+setCellValue(wb.sheets[0], 1, 2, 123.45)
+writeFileSync('out.xlsx', await workbookToXlsxBytes(wb, {
+  fidelity: 'overlay',
+  sourceBuffer: src.buffer.slice(src.byteOffset, src.byteOffset + src.byteLength),
+}))            // workbookToXlsxBytes → Uint8Array (not a Blob)
+```
+
+Not available headless (need a browser canvas/DOM): image/PDF export, `print()`, the built-in cell editor, and component rendering. See the 中文 [Node 用法](#node--服务端-headless-用法) section for details.
+
 See the API table above. MIT licensed.