ooxml-excel-editor 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -2,6 +2,136 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.2] - 2026-06-08
+
+**修 webpack 4 / vue-cli 4 / CJS 环境兼容** — 用户反馈 Vue 2.6.12 + @vue/cli 4 (webpack 4) 项目消费 1.3.1 时报多个错. 此版本系统修复 4 个老打包器兼容问题, **任何环境(Vite / webpack 5 / webpack 4 / Snowpack / Parcel)都能消费**.
+
+### 修复 (1.3.2 二次迭代, 同版本号未发布前补丁)
+
+#### Vue 2.6 上 renderArea / fb / templateInput 三个 DOM 全拿不到 → canvas 不挂
+
+**根因**: `src/vue2/ExcelViewer.ts` 之前用**函数 ref (callback ref)** 拿 DOM:
+```ts
+function domSlot<T>() {
+  const slot = { value: null, bind: (el) => { slot.value = el } }
+  return slot
+}
+h('div', { ref: renderAreaSlot.bind, class: 'ov-render-area' }, [...])
+```
+
+**但函数 ref 是 Vue 3 引入、Vue 2.7 才 backport 的特性**. **Vue 2.6 的 vnode ref 只认字符串 ref** — 传函数根本不会被 Vue 调用, `slot.value` 永远是 null, onMounted 里 `renderAreaSlot.value`、`fbSlot.value`、`templateInputSlot.value` 全是 null, 画布初始化整段挂不上.
+
+(为什么内部 demo (`vue2-demo`) 一直 OK? 因为 demo 的 `vue2` 别名解析到 `vue@2.7.16` —— 2.7 起函数 ref 已 backport, 跑起来正常. 直到消费方在真 Vue 2.6.12 项目里装包才暴露.)
+
+**修复**: 把 `domSlot` 从函数 ref 改成**字符串 ref + `vm.$refs` getter**, 三个版本 (Vue 2.6 / 2.7 / Vue 3) 统一支持字符串 ref:
+```ts
+function makeDomSlotFactory(vm) {
+  return function domSlot<T>(refName: string) {
+    return { refName, get value() { return vm.$refs[refName] ?? null } }
+  }
+}
+// render: `ref: slot.refName` (string)
+// access: `slot.value` getter → 实时读 vm.$refs[name]
+```
+
+并保留 onMounted 体内的 `nextTick` 兜底, 让 Vue 3 (refs 在 mounted 后 flush) 也能拿到. 修复影响 3 处 DOM 槽: `renderAreaSlot` (画布根 div) / `fbSlot` (公式栏 textarea) / `templateInputSlot` (隐藏的模板 file input).
+
+**验证**: 本地把 `vue2` devDep 临时改成 `npm:vue@2.6.12` + `Vue.use(VueCompositionAPI)`, 跑 `npm run dev:vue2`, headless 检查: renderArea (1280×509) / canvas (1280×509) / 8 个 controller 子节点全到位, 控制台 0 错误.
+
+### 修复
+
+#### 1. dist 不再含 `import.meta.url` + module worker (webpack 4 SyntaxError 致命)
+
+之前 lib-vue2 build 没用 worker stub, `dist/vue2.js` 含:
+```js
+new Worker(new URL("/assets/parse.worker-xxx.js", import.meta.url), { type: "module" })
+```
+- `import.meta.url` 是 ESM 专属语法, webpack 4 解析失败 (Module parse failed: Unexpected token)
+- `/assets/parse.worker-xxx.js` 是 Vite 构建产物, 在别的打包器/项目里根本不存在
+
+**修复**: vite.config.ts 把 `isLibBuild` 判定从 `command === 'build' && !isDemoSite && !isVue2Build` 改成 `command === 'build' && !isDemoSite` (Vue 2 lib build 也用 worker-client.stub.ts 走主线程解析). 现在所有 lib 产物 (`dist/index.js` / `react.js` / `vue2.js`) 都不含 `new Worker` 也不含 `import.meta`.
+
+#### 2. dist 降级 `??` / `?.` 等 ES2020 语法 (webpack 4 SyntaxError 致命)
+
+之前用户报:
+```js
+r.onerror = () => o(r.error ?? new Error("文件读取失败"))  // ?? 是 ES2020, webpack 4 不识别
+```
+- 多数项目默认不转译 node_modules (webpack 4 / vue-cli 4 尤甚), 用户被迫加 transpileDependencies
+
+**修复**: vite.config.ts 给所有 lib build 加 `target: 'es2018'`. ES2018 没有 `??` (ES2020) / `?.` (ES2020), 但保留 async/await + spread/rest (ES2017+, webpack 4 都支持), 不引入大量 polyfill.
+
+#### 3. 包根加 vue2.js / react.js / core.js stub (webpack 4 不读 package.json#exports)
+
+之前用户报:
+```js
+import ExcelViewer from 'ooxml-excel-editor/vue2'  // webpack 4 解析失败
+// 被迫: import ExcelViewer from 'ooxml-excel-editor/dist/vue2.js'
+```
+
+**修复**: 包根新增 3 个 stub 文件:
+- `vue2.js` — re-export `./dist/vue2.js`
+- `react.js` — re-export `./dist/react.js`
+- `core.js` — re-export `./dist/core.js`
+
+webpack 4 解析 `ooxml-excel-editor/vue2` → 找包根 `vue2.js` → re-export 到 dist. webpack 5 / Vite / Rollup 仍走 `package.json#exports` → `./dist/vue2.js` (stub 不会被用到, 0 性能影响).
+
+文件加进 `package.json` `files` 数组, npm publish 时一并发布.
+
+#### 4. echarts / exceljs / jspdf / hyperformula **inline 进 dist chunks/** (彻底)
+
+试过 3 个方案都不彻底:
+- 1.3.1 `peerOptional`: npm 7+ 触发 ERESOLVE 冲突
+- 1.3.2 第一版 文档说明 + 用户按需装: webpack 4 静态扫描 `await import()` 找不到模块发 warning
+- 1.3.2 第二版 改 `dependencies` 自动装: webpack 4 解析这些 lib **源码** 时仍报 named-export / class-fields 错误 (因为 lib 用 ES2020+ 语法)
+
+**终极修复**: rollupOptions.external 区分两类:
+
+**inline 编进 chunks/** (老打包器零解析):
+- `exceljs` — 私有依赖, 用户项目一般没用
+- `hyperformula` — class fields 语法 webpack 4 解析必炸, 必 inline
+- `jspdf` — 同样现代语法
+
+**external + dependencies (npm 自动装)**:
+- `echarts` — 用户项目大概率已有自己的 echarts (常见 viz lib), inline 会:
+  - 浪费 ~1 MB bundle 体积
+  - 跟用户 `echarts.registerTheme()` 注册的主题 dual instance, 用户主题在我们 inline 的实例上失效
+  现代 echarts 5.x CJS / UMD 入口 webpack 4 兼容良好, external 安全.
+
+target: `es2017` 把 class-fields / `??` / `?.` 全降级.
+
+消费方:
+- **完全不用手动装任何 lib** — `npm i ooxml-excel-editor` 自动装 echarts
+- webpack 不解析 exceljs / jspdf / hyperformula 源码 (已 inline 嚼碎)
+- echarts 跟消费方自己的 echarts 同实例 (theme 共享, 不 dual)
+- 不再有 named-export / class-fields / `import.meta` / module worker / `??` 等老打包器报错
+
+变化:
+- **dependencies** 仅保留 `echarts` (+ 小 lib `fast-xml-parser` / `fflate`)
+- **dependencies** 移除: `exceljs` / `jspdf` / `hyperformula` (已 inline)
+- **peerDependencies** 剩余: `vue` / `react` / `react-dom` / `@vue/composition-api`
+- **dist 体积**: 5.4 MB (含 3 个 inline lib)
+- **tgz 压缩后**: 1.33 MB
+- vite/rollup target: `es2017`
+
+消费方 build 后 bundle (不用 PDF/编辑公式) **影响很小** — dynamic import 保留 code-split, 不调到 chunk 就不下载.
+
+### 总效果
+
+任何打包器都能消费 1.3.2:
+- ✅ Vite / webpack 5: 走 `package.json#exports`, 用 dist/ 真实产物
+- ✅ webpack 4 / vue-cli 4: 走包根 stub 文件, dist 已降级语法 + 无 worker
+- ✅ Parcel / Snowpack / esbuild: 同上
+- ✅ Node CJS (SSR): 同 webpack 4 路径
+
+### 升级提示 (从 1.3.0 / 1.3.1 升 1.3.2)
+
+无 breaking, `npm i ooxml-excel-editor@1.3.2`. 4 个运行时 lib (`echarts` / `exceljs` / `jspdf` / `hyperformula`) 已改成 `dependencies` 随包自动装, **不用手动 `npm i`**. 之前手动装的不用卸载, npm 会复用现有版本 (前提是 `^range` 满足).
+
+Vue 3 / React 用户**无变化**.
+
+---
+
 ## [1.3.1] - 2026-06-08
 
 **Vue 2 子入口扩展兼容到 Vue 2.6.x** — 通过 `@vue/composition-api` package 让一份代码同时支持 Vue 2.6 + 2.7+. 1.3.0 只支持 2.7+ (内置 Composition API), 此版本不破坏 2.7 用户用法.

package/README.md

@@ -9,11 +9,13 @@
 **装**(按框架二选一):
 
 ```bash
-npm i ooxml-excel-editor vue exceljs                  # Vue 3 (默认入口)
-npm i ooxml-excel-editor react react-dom exceljs      # React 壳 (/react 子入口)
-npm i ooxml-excel-editor vue@2.7 @vue/composition-api exceljs  # Vue 2.6/2.7+ (/vue2 子入口, 1.3.0+)
+npm i ooxml-excel-editor vue                          # Vue 3 (默认入口)
+npm i ooxml-excel-editor react react-dom              # React 壳 (/react 子入口)
+npm i ooxml-excel-editor vue@2.7 @vue/composition-api # Vue 2.6/2.7+ (/vue2 子入口, 1.3.0+)
 ```
 
+> 1.3.2+ `exceljs` / `jspdf` / `hyperformula` 已 **inline 编进 dist chunks/** (ES2017 降级 + 老打包器零解析), `echarts` 仍 external 走 `dependencies` (npm 自动装, 避免主题 dual instance). 消费方仅装 framework (`vue` / `react` / `@vue/composition-api`), 其他 lib 完全不用手动装. `dist` ~5.4 MB, tgz ~1.33 MB.
+
 **用**(Vue,容器要给高度;`src` 可传 `File` / `Blob` / `ArrayBuffer` / `Uint8Array` / URL 字符串):
 
 ```vue

package/core.js

@@ -0,0 +1,2 @@
+// 包根兼容入口 — 老打包器(webpack 4)不读 package.json#exports
+export * from './dist/core.js'

package/dist/chunks/_commonjsHelpers-bAxELxBV.js

@@ -0,0 +1,8 @@
+var o = typeof globalThis != "undefined" ? globalThis : typeof window != "undefined" ? window : typeof global != "undefined" ? global : typeof self != "undefined" ? self : {};
+function l(e) {
+  return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
+}
+export {
+  o as c,
+  l as g
+};