HarmonyOS 7 新特性（四十七）｜ArkWeb 预取：加载加速与白屏诊断

ArkWeb 页面“偶尔白屏”常被简单归因于网络，但真实原因可能是权限、DNS、证书、重定向、Cookie、DOM Storage、JavaScript、图片策略、User-Agent、渲染进程甚至业务页面自身异常。另一方面，盲目预取全部页面不仅浪费流量，还可能污染登录态和缓存。HarmonyOS 7/API 26 的 ArkWeb 能力应结合 PrefetchOptions、WebviewController、加载回调和 DevTools，建立可观测、可取消、可回退的页面加载管线。

本文给出“导航预测—安全预取—正式加载—错误分类—证据采集—缓存治理”的完整方案。部分预取接口在不同 SDK 的签名和起始版本可能不同，接入前请以目标 API 26 类型声明为准。

一、先定义白屏的业务状态机

页面没有内容不等于只有一种错误。UI 至少区分准备、加载、可交互、失败和离线回退。

type WebPageState =
  | { kind: 'IDLE' }
  | { kind: 'LOADING'; startedAt: number }
  | { kind: 'INTERACTIVE'; url: string }
  | { kind: 'ERROR'; category: WebErrorCategory; retryable: boolean }
  | { kind: 'OFFLINE'; snapshotId?: string }

type WebErrorCategory =
  | 'NETWORK' | 'TLS' | 'HTTP' | 'PERMISSION'
  | 'RENDERER' | 'CONTENT' | 'TIMEOUT' | 'CANCELLED'

只用一个旋转菊花无法表达错误，也会让超时页面永远停在“加载中”。

二、权限和开关先做基线

在线页面需要网络权限；依赖 localStorage、文件、在线图片和 JavaScript 的页面，还要核对 Web 组件相关访问开关。

{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" }
  ]
}

Web({ src: this.url, controller: this.controller })
  .domStorageAccess(true)
  .fileAccess(false)
  .imageAccess(true)
  .onlineImageAccess(true)
  .javaScriptAccess(true)

按最小权限启用。若页面不需要本地文件，保持 fileAccess(false)，不要为了排错把所有开关都打开后忘记收回。

三、预测导航，而不是全量预取

预取候选应来自高概率用户路径，例如用户已在文章列表按下某项、即将进入结算页或标签页邻页。限制数量、网络条件和时间窗口。

interface WebPrefetchCandidate {
  url: string
  probability: number
  sameAccountScope: boolean
  safeMethod: 'GET'
  estimatedBytes: number
  expiresAt: number
}

function eligible(c: WebPrefetchCandidate, now: number): boolean {
  return c.probability >= 0.65 && c.sameAccountScope &&
    c.estimatedBytes < 512_000 && c.expiresAt > now
}

涉及支付、写操作、一次性 Token 和敏感查询参数的 URL 不进入预取。

四、PrefetchOptions 要服务于策略层

ArkWeb API 参考列出了 PrefetchOptions。业务层不要到处直接构造平台对象，而应先定义稳定的预取契约，再由适配器映射。

interface PagePrefetchPolicy {
  url: string
  headers: Record<string, string>
  deadlineMs: number
  cacheScope: string
}

class ArkWebPrefetchAdapter {
  async prefetch(policy: PagePrefetchPolicy): Promise<void> {
    // 按 API 26 SDK 将 policy 映射为 PrefetchOptions，
    // 再调用目标版本提供的预取接口。
  }
}

这样接口变化只影响适配层，业务仍能进行单元测试和降级。

五、预取身份与正式加载必须一致

预取时的 Cookie、语言、账号和实验配置如果与打开页面时不同，命中的缓存可能显示错误用户内容。

interface WebCacheScope {
  accountVersion: number
  locale: string
  cookieEpoch: number
  experimentVersion: string
}

function scopeKey(s: WebCacheScope): string {
  return `${s.accountVersion}:${s.locale}:${s.cookieEpoch}:${s.experimentVersion}`
}

登录、登出、账号切换、Cookie 清理和实验切组时，使旧预取结果失效。

六、所有预取都必须可取消

用户滚动离开候选项、应用退后台、网络切换或真正导航到其他页面时，取消低优先级任务。

class PrefetchRegistry {
  private jobs = new Map<string, AbortController>()

  start(key: string): AbortSignal {
    this.jobs.get(key)?.abort()
    const controller = new AbortController()
    this.jobs.set(key, controller)
    return controller.signal
  }

  cancelAll() {
    this.jobs.forEach(job => job.abort())
    this.jobs.clear()
  }
}

如果目标平台预取 API 没有直接暴露取消句柄，策略层仍应停止后续消费，并限制并发和截止时间。

七、正式加载建立分阶段超时

一个总超时无法判断卡在哪里。至少区分开始、收到响应、DOM 就绪和业务可交互。

interface WebTiming {
  navigationStart: number
  responseStart?: number
  domReady?: number
  businessReady?: number
}

function stalled(t: WebTiming, now: number): string | undefined {
  if (!t.responseStart && now - t.navigationStart > 5000) return 'WAITING_RESPONSE'
  if (!t.domReady && now - (t.responseStart ?? t.navigationStart) > 6000) return 'WAITING_DOM'
  if (!t.businessReady && t.domReady && now - t.domReady > 4000) return 'WAITING_APP'
  return undefined
}

业务页面可通过受控 JS Bridge 上报 businessReady，但要验证消息来源与协议版本。

八、错误回调要分类，不要统一 Toast

网络不可用、证书失败、HTTP 404、重定向循环和渲染器异常的恢复方式不同。

interface WebFailure {
  category: WebErrorCategory
  code: number
  mainFrame: boolean
  urlHash: string
  recover: 'RETRY' | 'GO_BACK' | 'OPEN_NATIVE' | 'REPORT'
}

只对主框架失败切换整页错误态；子资源图片失败可保留正文。证书错误必须失败关闭，不能提供忽略按钮。

九、User-Agent 适配有明确证据链

官方排查文档指出，自定义 User-Agent 丢失 OpenHarmony 标识可能导致第三方站点错误识别。修改前先用 DevTools 查看请求头，对比 ArkWeb 默认值和自定义值。

controllerAttached() {
  const current = this.controller.getUserAgent()
  const next = `${current} DemoApp/3.2.0`
  this.controller.setCustomUserAgent(next)
}

不要伪装成其他平台作为永久方案。若切换 User-Agent 后恢复，应推动 Web 服务正确适配并保留回归测试。

十、重定向与外部协议设白名单

页面可能跳转到登录、支付、地图或自定义 scheme。所有非 HTTP(S) 协议和跨域跳转都要经过校验。

const allowedHosts = new Set(['m.example.com', 'account.example.com'])

function navigationAllowed(raw: string): boolean {
  const url = new URL(raw)
  if (url.protocol !== 'https:') return false
  return allowedHosts.has(url.hostname)
}

外部应用唤起前展示明确用户操作，不允许页面静默启动任意 Ability。

十一、用 DevTools 构建故障证据包

排查时记录构建 SHA、设备/API、原始 URL 的脱敏哈希、主框架错误、网络瀑布、控制台异常、Cookie 范围、UA 和页面截图。

interface WebEvidence {
  gitSha: string
  device: string
  api: number
  urlHash: string
  state: WebPageState
  timing: WebTiming
  uaHash: string
  consoleErrorCount: number
}

远程页面内容可能包含隐私，截图和 HAR 导出前做脱敏与访问控制。

十二、预取收益与浪费共同验收

interface PrefetchMetric {
  attempted: number
  hit: number
  cancelled: number
  expired: number
  bytesDownloaded: number
  navigationSavedMs: number
}

按页面类型和网络分桶比较 P50/P90 可交互时间。命中率低、流量高或登录态错误率上升时立即关闭预取。

十三、上线检查清单

• 网络权限和 Web 访问开关按最小需求配置；
• 预取只覆盖高概率、幂等、安全候选；
• PrefetchOptions 封装在平台适配层；
• 登录、Cookie、语言和实验变化会使缓存失效；
• 预取有并发、截止时间和取消策略；
• 加载分阶段计时并识别业务可交互；
• 主框架与子资源错误分开处理；
• TLS 错误失败关闭；
• User-Agent 修改有 DevTools 证据和服务端修复计划；
• 指标同时记录加载收益与流量浪费。

结语

ArkWeb 优化不是“提前打开网页”，排障也不是“网络不好请重试”。把安全导航预测、身份一致的预取、分阶段加载、错误分类和 DevTools 证据连接起来，才能既减少可交互等待，又避免 Cookie 污染、流量浪费和安全降级。任何预取失败都应回到正常加载，任何异常都应落到可解释的状态。

官方参考

• ArkWeb 页面加载问题定位：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-page-loading
• ArkWeb API 总览（含 PrefetchOptions）：https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/api/system-basicfun-api
• 网络连接安全配置：https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/network-connection-security-configuration

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/m0_46382645/article/details/164214518