HarmonyOS NEXT 上 Web 应用开发者必须知道的 10 件事

1. UA 字符串检测

在 JS 或后端识别 HarmonyOS NEXT 设备：

// JS 端
const ua = navigator.userAgent;
const isHarmonyOSNext = ua.includes('HarmonyOS NEXT') || ua.includes('ArkWeb');
const isHarmonyOS = ua.includes('HarmonyOS');

// 后端（示例）
// User-Agent 里找 "HarmonyOS" 和 "ArkWeb"

2. 用标准 Web API 优先

只写 W3C 标准 API，避免 Chromium 私有特性：

用	避免
`document.createElement('div')`	`document.implementation.createHTMLDocument()`
CSS `display: flex` / `grid`	CSS nesting、`:has()`
`document.querySelector()`	XPath（`document.evaluate`）
`fetch()` API	`XMLHttpRequest`（兼容性更好）
Canvas 2D	WebGL / WebGPU（ArkWeb 暂不支持）

3. 所有浏览器特有 API 做 feature detect

// ❌ 不要：假设 API 存在
const features = window.CSS.features();

// ✅ 要：检查后再用
if (window.CSS && CSS.supports && CSS.supports(':has(div)')) {
    // Chromium 路径
} else {
    // ArkWeb 兼容路径
}

4. 不要用 Chromium 安全沙箱假设

Chromium 的跨源隔离（COOP / COEP）、iframe sandbox、Content Security Policy 等在 ArkWeb 上实现不同：

COOP 在 ArkWeb 上可能不生效 → 跨源 iframe 的 localStorage 共享策略可能和 Chromium 不同
CSP frame-src 可能放宽 → ArkWeb 安全策略不同
建议在 HarmonyOS NEXT 上单独测 iframe 嵌套场景

5. 文件下载显式处理

HarmonyOS NEXT 默认拦截非 HTTPS 的文件下载，并且 blob: 协议可能不可用：

始终用 HTTPS URL 触发下载
App 端实现 WebChromeClient.onShowFileChooser 或鸿蒙对应的 ArkWeb API

6. 权限请求

HarmonyOS 的权限体系和 Android 完全不同：

android.permission.CAMERA → 鸿蒙是 ohos.permission.CAMERA
onPermissionRequest → 鸿蒙 ArkWeb 的权限请求流程不同
建议：HarmonyOS NEXT 上把相机 / 麦克风 / 定位的处理移到原生层，不要靠 JS 自动权限请求

7. 字体与样式

HarmonyOS NEXT 默认中文字体是华为自研 HarmonyOS Sans，和 Chromium 默认的 Noto Sans CJK 不同——同样的 CSS 样式在 HarmonyOS NEXT 上显示可能有差异：

字重：HarmonyOS Sans 字重区间和 Noto Sans 不完全对齐
字号：不同字号的实际渲染大小可能微差
图标字体：@font-face 加载的图标字体如果路径有问题，HarmonyOS 拦截比 Chromium 更严格

8. 测试清单

上线前按这个清单过一遍 HarmonyOS NEXT 真机：

[ ] 首页加载时间（ArkWeb 首屏渲染可能比 Chromium 慢）
[ ] 登录 / 支付 / 第三方 SDK 回调
[ ] iframe 嵌套场景
[ ] 视频播放（HTML5 Video）
[ ] WebSocket 连接
[ ] Service Worker / PWA 能力
[ ] 文件上传 <input type=file>
[ ] 文件下载
[ ] 深色模式（Force Dark）
[ ] 权限请求（相机 / 麦克风 / 定位）

9. 联系华为开发者支持

HarmonyOS NEXT 的 ArkWeb 问题可以在华为开发者平台反馈——华为对内嵌 Web 场景的重视度在提升，迭代节奏较快。

10. 接受现实

如果你的 App 核心能力强依赖 Chromium 专有 API（比如 WebGPU、复杂 CSS nesting、完整 WebRTC），那 HarmonyOS NEXT 上可能真的做不到完美兼容——建议在 HarmonyOS NEXT 上提供一个功能降级版。

→ 返回常见问题总览