JavaScript 兼容性规范

小工具 JavaScript 的最低兼容基线是 Android 8.1 出场 Chrome / WebView 61。最终代码必须能在 Chrome 61 解析和运行；iOS 18.4+ 支持的额外能力只能用于能力检测后的增强路径。Chrome 61 完整支持 ES2017，最终代码以 ES2017 为构建目标。

1. 语法基线

最终 zip 中的 JS 须兼容 Chrome 61：

直接编写并交付 .js 时可使用 ES2017，包括 async / await、Object.entries / Object.values、Array.prototype.includes、String.prototype.padStart / padEnd。
ES2018+ 语法须由构建链转译，例如对象 spread、异步迭代、可选链、空值合并、逻辑赋值、class 私有字段、static block、BigInt 字面量和 top-level await；更新的运行时 API 仍须做能力检测或提供必要的局部实现。
正则表达式避免依赖 lookbehind、Unicode property escapes 等较新的语法特性。

语法不兼容会在脚本解析阶段直接失败，无法通过运行时 if 兜底。

2. 有构建链与无构建链

直接交付静态三件套

没有现成构建链时，不为兼容性临时引入 Babel、core-js 或新的 npm 依赖；直接按 ES2017 编写。

项目已有构建链

可以在源码中使用构建链已支持的新语法。Vite 项目使用以下构建目标：

// vite.config.js
export default {
  build: { target: ['es2017', 'chrome61'] },
}

最终产物须：

转译到 ES2017 / Chrome 61；
只把构建后的静态文件放进 zip，不带 node_modules、source map 或构建配置。

转译只解决语法，不会自动补齐所有运行时 API。不要因为构建成功就假定新 API 可用。

3. 运行时 API

ES2017 内置 API 和基础 DOM API 可直接使用。
String.prototype.replaceAll、Array.prototype.at、Object.hasOwn、structuredClone 等更新 API 不应直接作为唯一实现路径。
使用非基础 Web API 前先做能力检测；不可用时隐藏增强功能、使用简单替代实现或给出清晰提示。
只补功能实际需要的小型本地 fallback，不引入整套通用 polyfill；所有代码仍须随包离线交付。
能力检测基于对象 / 方法是否存在，不按 UA、机型或系统版本字符串分支。
不为被容器明确禁止的能力添加 polyfill；能力边界仍以 device-capabilities.md 为准。

4. 跨内核行为

日期字符串使用明确的 ISO 格式或拆分为年月日构造，不依赖非标准字符串解析。
不依赖对象遍历顺序表达业务优先级；需要顺序时使用数组。
对 Intl 格式化结果、字体度量、滚动和软键盘行为保留布局余量，不把不同内核的细微差异当作固定输出。
触摸、滚动和安全区规则见 cross-platform-h5.md。

5. 交付检查

直接交付的 JS 不超出 ES2017；使用更新语法时已有构建链负责转译
使用 Vite 时构建目标包含 es2017 和 chrome61，且 zip 中只保留最终静态文件
新 Web API 有能力检测和局部降级，不使用 UA 猜测能力
未把语法转译误认为运行时 API polyfill
未进行实际设备验证时标记“兼容性未实测”，不宣称已在真机通过

3.3 KiB Raw Permalink Blame History Unescape Escape