Handsontable 支持的浏览器与兼容性保障:官方支持矩阵、测试策略与编译基线全解析
Handsontable 支持的浏览器与兼容性保障:官方支持矩阵、测试策略与编译基线全解析
本篇技术指南以 Handsontable 官方文档《Supported browsers》为骨架,结合当前仓库中的编译目标配置(browser-targets.js)、构建工具配置(handsontable/rspack.config.js、babel.config.js)与兼容性测试用例(handsontable/test/tests/esTarget.unit.js),系统讲解 Handsontable 官方支持的桌面端与移动端浏览器清单、"两个最新版本"测试策略,以及仓库是如何在构建期、类型检查期和测试期三层保障这些兼容性承诺的。读完本文,你将能准确判断 Handsontable 在你目标浏览器环境中的可用性,并理解其"支持声明"与"编译地板"之间的精确区别。
支持的浏览器:官方支持矩阵
Handsontable 官方文档明确声明,其支持所有最流行的桌面端和移动端浏览器。官方支持矩阵如下:
| 桌面浏览器 | 移动浏览器 |
|---|---|
| Chrome | Chrome |
| Firefox | Safari iOS |
| Safari | |
| Edge |
测试策略:两个最新版本 + 真实设备
官方在测试策略上坚持两条原则:
- 版本新鲜度下限:官方在两个最新版本的主流现代浏览器上,同时覆盖移动端和桌面端设备,仔细测试代码。
- 双重测试通道:除了运行单元测试(unit tests)和端到端测试(end-to-end tests)之外,官方还重点关注对所有用户都至关重要的两个因素——性能(performance)与用户界面准确性(accuracy of the user interface)。
BrowserStack 云测 + 物理设备实测
兼容性测试在 BrowserStack 上运行,同时也在有限数量的物理桌面设备和移动设备上运行。官方特别指出,物理设备的访问为性能测量提供了更好的条件——虚拟机上难以准确测量真实性能,而物理设备能更真实地反映用户环境。
仓库内的端到端测试支撑
当前仓库的端到端测试基础设施印证了这一承诺。根目录下的 tests/playwright.config.ts 使用 Playwright 运行功能性 E2E 套件:测试矩阵按 主题(theme)× 包(bundle) 组合展开,每个组合对应一个 project(e2e-<theme><a href="https://link.gitcode.com/i/3ada4458f8111e89697eeff83bdd68f1" target="_blank">-min]),默认基于 devices['Desktop Chrome'](桌面 Chrome 设备描述)运行,并启动 [tests/support/static-server.mjs 提供测试页面。CI 环境下每个组合各跑一个 job,本地则通过 npx playwright test 一次跑完所有组合,--project=e2e-horizon 可只跑单个主题。同时 handsontable/jest.config.js 支撑着单元测试,两者共同构成了"单元 + 端到端"的测试体系。
编译基线:仓库如何定义"最低支持版本"
官方文档中的支持矩阵是测试范围的声明;而仓库中 browser-targets.js 定义了另一层含义——编译地板(compile floor),即产物必须能在其上运行的最低浏览器版本。这层配置被以下所有环节消费:
handsontable/.config/下所有 rspack/swc 配置的env.targets- babel.config.js 的
targets - CSS 构建的 lightningcss targets
eslint-plugin-compat的settings.browsers
// browser-targets.js(节选)
exports.BROWSERS_LIST = [
'Chrome >= 130',
'Edge >= 130',
'Firefox >= 132',
'Safari >= 18.2',
'iOS >= 18.2',
];
这份清单是 Baseline 2024 目标集,用 browserslist('baseline 2024') 解析一次后**固定(pinned)**下来的结果。注意几个关键设计决策:
- 刻意使用固定整数而非动态查询:注释明确指出,
last 2 versions、baseline widely available这类移动查询会让构建不可复现,且会在任何一次重建时悄悄丢弃支持。提高这些版本号属于支持降级,必须走大版本发布边界 + 团队签字确认。 - iOS 与 Safari 分开列出:browserslist 将
ios_saf视为独立目标,只写Safari会让 lightningcss 和eslint-plugin-compat完全没有 iOS 边界。两者版本同步移动(iOS 18.2 与 Safari 18.2 是同一套 WebKit),因此被固定为相同版本号。 - 刻意不包含
and_chr与and_ff:browserslist 对它们各自只携带一个(最新)版本,无法固定,因此由桌面端对应版本代为约束(Android Chrome 跟随桌面 Chrome 的策略)。
从源码结构可以推断,这份基线主要面向现代主流浏览器,且与官方"测试两个最新版本"的声明互为补充——测试是新鲜度下限(当下最新必须可用),而编译地板则可以远低于它(仓库注释明确说明"floor is deliberately many majors below it")。
从编译目标到 Babel 配置
根目录 babel.config.js 直接消费这份清单:
const { BROWSERS_LIST } = require('./browser-targets.js');
const babelPresetConfig = () => ({
targets: `${BROWSERS_LIST.join(', ')}, Node >= 11`, // (Node 11) support for Webpack 4 and similar oldish bundlers
modules: false,
debug: false,
useBuiltIns: false,
});
可以看到,编译目标在浏览器清单之外追加了 Node >= 11,以兼容 Webpack 4 等老式打包器的运行环境;useBuiltIns: false 意味着 Babel 不自动注入 polyfill,而是由 swc 只做语法降级(见下文)。
API 边界:ES_TARGET 与 tsconfig 的 lib
除了浏览器版本地板,仓库还固定了一个 API 地板(API floor)——即 BROWSERS_LIST 中所有浏览器都完整支持的 ES 年份桶:
exports.ES_TARGET = 'es2024';
这个值被固定为 handsontable/tsconfig.json 中的 lib,使得调用高于地板的内置 API 在 .ts 文件中直接构成类型错误。仓库注释记录了一个真实事故:eslint-plugin-compat 无法解析非字面量接收者上的原型方法,toSorted 和 Array#at 正是借此在 18.0.0 中溜了进去。推导规则是:每当 BROWSERS_LIST 移动,ES_TARGET 都要按 core-js-compat 的 data.json 重新推导——取"所有特性都在每个地板之下"的最新 ES 年份。Baseline 2024 地板对应的最高特性是 ArrayBuffer#transfer(Firefox 122)和 Array.fromAsync(Chrome 121、Safari 18.0);ES2025 则超出范围,因为 RegExp.escape 需要 Chrome 136。
npm 产物的特例:swc-transpile 固定 es2021
handsontable/scripts/swc-transpile.mjs 刻意不跟随 ES_TARGET,而是硬编码 es2021,目的是让 npm 的 ESM/CJS 产物保留对 class fields 的降级,以兼容 Angular 的 Zone.js。其约束是"绝不比 ES_TARGET 更新",这一不变量由 esTarget.unit.js 断言兜底。
CSS 特性地板:主题样式不能跑赢编译目标
仓库对 CSS 同样设置了特性地板。主题实际发布的最"高"的 CSS 特性及其支持起点为:
| CSS 特性 | Chrome | Edge | Firefox | Safari | iOS |
|---|---|---|---|---|---|
light-dark() |
123 | 123 | 120 | 17.5 | 17.5 |
| CSS nesting | 120 | 120 | 117 | 17.2 | 17.2 |
| CSS logical properties | 89 | 89 | 66 | 15 | 15 |
light-dark() 是仓库使用的最高特性,因此编译地板(Chrome 130、Firefox 132、Safari 18.2)必须覆盖它。若地板低于这些特性,lightningcss 就会把特性降级掉——这正是 18.0.0 中运行时主题字符串丢失嵌套图标规则(nested icon rules)的原因。仓库注释还记录了逻辑属性降级导致的真实 bug:低于 Safari 15 时 border-*-radius 四个属性被降级,RTL 网格会圆角化错误的单元格。
三层保障:测试用例如何固化这些承诺
handsontable/test/tests/esTarget.unit.js 用一组单元测试把上述所有声明固化为可执行断言:
ES_TARGET必须是已知的 ES 年份(es5~esnext序列之一);tsconfig的lib必须等于ES_TARGET——若ES_TARGET移动而 tsconfig 未跟随(或反之),测试立即失败;swc-transpile.mjs的 target 不得高于ES_TARGET——npm 产物的语法不能超出声明浏览器可解析的范围;- 每个浏览器地板必须 ≥ 主题发布的全部 CSS 特性起点——防止构建悄悄丢特性而不自知;
- CSS 特性表必须覆盖清单中的每个浏览器——新增浏览器却不补充特性表会被拦截;
- 每个浏览器地板必须固定为显式版本——正则
/^[A-Za-z ]+ >= \d+(\.\d+)*$/直接禁止last 2 versions这类移动查询进入清单。
此外,handsontable/AGENTS.md 记录了配套的类型检查门禁:tsconfig.json 将 lib 固定为 ES_TARGET(es2024),使高于地板的内置 API 调用成为类型错误;no-restricted-syntax 规则则覆盖同样一批方法,外加 src/ 下剩余 12 个 .js 文件(这些文件 allowJs 关闭、不受类型检查保护)。仓库还记录了"地板之上"的具体案例:Array#with 在 Firefox 140(相对地板的 132)才支持,TypedArray#with 在 Safari/iOS 更晚,因此这类方法被明确禁止调用——因为 swc 只做语法降级、不注入 core-js polyfill,在受支持浏览器上调用会直接抛 X is not a function。
实践要点与常见疑问
- "两个最新版本"与编译地板不是一回事:browser-targets.js 的注释特别强调,指南中"two latest versions"声明描述的是测试范围,是新鲜度的下限(当下最新必须可用),而编译地板可以并且刻意远低于它。
- Android Chrome 如何覆盖:由于 browserslist 无法固定
and_chr版本,Android Chrome 通过桌面 Chrome 的地板(Chrome >= 130)间接约束,两者由官方跟踪策略保持一致。 - 老式打包器场景:根目录 babel.config.js 在浏览器目标外追加
Node >= 11,覆盖 Webpack 4 等旧打包链路的宿主环境。 - 移动端测试重点:移动端支持矩阵为 Chrome 与 Safari iOS;iOS 与 Safari 的 WebKit 版本同步推进(如 iOS 18.2 与 Safari 18.2),仓库因此在清单中为两者设置相同版本号。
- 判断你的目标环境是否受支持:对照 browser-targets.js 的
BROWSERS_LIST(Chrome/Edge ≥ 130、Firefox ≥ 132、Safari/iOS ≥ 18.2)即可确认产物层面的最低保障;若你还在这些版本之上运行,则属于官方"两个最新版本"的测试范围。
综上,Handsontable 的浏览器兼容性不是一句营销口号,而是由支持矩阵声明、云测 + 物理设备测试、固定的编译地板、类型检查门禁和可执行的单元断言五层机制共同保障的工程承诺。无论是集成方评估环境,还是贡献者修改源码,browser-targets.js 与 handsontable/test/tests/esTarget.unit.js 都是最值得优先阅读的两个文件。