Handsontable 支持的浏览器与兼容性保障:官方支持矩阵、测试策略与编译基线全解析

原创2026-09-20 11:38:231,841 阅读
文章标签:前端UI组件企业应用

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

测试策略:两个最新版本 + 真实设备

官方在测试策略上坚持两条原则:

  1. 版本新鲜度下限:官方在两个最新版本的主流现代浏览器上,同时覆盖移动端和桌面端设备,仔细测试代码。
  2. 双重测试通道:除了运行单元测试(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 用一组单元测试把上述所有声明固化为可执行断言:

  1. ES_TARGET 必须是已知的 ES 年份(es5 ~ esnext 序列之一);
  2. tsconfig 的 lib 必须等于 ES_TARGET——若 ES_TARGET 移动而 tsconfig 未跟随(或反之),测试立即失败;
  3. swc-transpile.mjs 的 target 不得高于 ES_TARGET——npm 产物的语法不能超出声明浏览器可解析的范围;
  4. 每个浏览器地板必须 ≥ 主题发布的全部 CSS 特性起点——防止构建悄悄丢特性而不自知;
  5. CSS 特性表必须覆盖清单中的每个浏览器——新增浏览器却不补充特性表会被拦截;
  6. 每个浏览器地板必须固定为显式版本——正则 /^[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 都是最值得优先阅读的两个文件。

登录后查看全文
handsontable