62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# 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 项目使用以下构建目标：
|
||
|
||
```js
|
||
// 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](./device-capabilities.md) 为准。
|
||
|
||
## 4. 跨内核行为
|
||
|
||
- 日期字符串使用明确的 ISO 格式或拆分为年月日构造，不依赖非标准字符串解析。
|
||
- 不依赖对象遍历顺序表达业务优先级；需要顺序时使用数组。
|
||
- 对 `Intl` 格式化结果、字体度量、滚动和软键盘行为保留布局余量，不把不同内核的细微差异当作固定输出。
|
||
- 触摸、滚动和安全区规则见 [cross-platform-h5.md](./cross-platform-h5.md)。
|
||
|
||
## 5. 交付检查
|
||
|
||
- [ ] 直接交付的 JS 不超出 ES2017；使用更新语法时已有构建链负责转译
|
||
- [ ] 使用 Vite 时构建目标包含 `es2017` 和 `chrome61`，且 zip 中只保留最终静态文件
|
||
- [ ] 新 Web API 有能力检测和局部降级，不使用 UA 猜测能力
|
||
- [ ] 未把语法转译误认为运行时 API polyfill
|
||
- [ ] 未进行实际设备验证时标记“兼容性未实测”，不宣称已在真机通过
|