前言

很多 ArkUI 页面做到一半，总会遇到一个问题：有些内容根本不适合重写一套原生界面。比如活动页、帮助中心、协议页、运营专题，直接嵌一个网页，往往更现实。

问题是，不少人第一次接触 HarmonyOS7 的 Web 组件时，脑子里只有一句话：它能加载网页。然后就没有然后了。配置项一多，回调一多，什么该先学、什么是后面再补的，顺序全乱了。

这篇文章我就按一个更适合入门的顺序来讲，把 Web 组件的骨架先搭起来。别急着追高级能力，先把“能放进去、知道怎么配、知道什么时候用”这三件事搞明白。

这个案例展示了什么

案例本身没有真的打开网页，而是用一个占位区域把 Web 组件的基本结构和常见属性列了出来。这样的写法反而适合拿来做入门理解，因为注意力不会被页面内容带跑偏。

它主要覆盖三块内容：

• Web({ src, controller }) 的基本使用形式
• 常见配置项，比如 JS、缩放、DOM 存储、混合模式
• 页面加载生命周期里最常见的几个回调

完整代码先放在这里

import { DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'

@Entry
@Component
struct WebComponentStarter {
  @State isShow: boolean = true

  build() {
    Column() {
      if (this.isShow) {
        Scroll() {
          Column({ space: 16 }) {
            Text('Web 组件基础').fontSize(16).fontColor(DEMO_THEME_COLOR).fontWeight(FontWeight.Bold)

            Column() {
              Text('Web 组件区域').fontSize(13).fontColor('#4D96FF').margin({ bottom: 8 })
              Column({ space: 8 }) {
                Text('Web({ src: "https://...", controller: ... })').fontSize(11).fontColor('#FFFFFF80')
                Text('网页内容展示区域').fontSize(16).fontColor('#FFFFFF')
                Text('支持加载和渲染 HTML 页面').fontSize(12).fontColor('#FFFFFF80')
              }
              .width('100%')
              .height(200)
              .backgroundColor('#333333')
              .borderRadius(10)
              .justifyContent(FlexAlign.Center)

              Text('Web 组件用于嵌入 Web 页面内容').fontSize(11).fontColor(DEMO_SUBTEXT_COLOR).margin({ top: 4 })
            }
            .backgroundColor(DEMO_CARD_COLOR)
            .padding(12)
            .borderRadius(12)

            Column({ space: 6 }) {
              Text('Web 组件基本属性').fontSize(14).fontColor(DEMO_THEME_COLOR).fontWeight(FontWeight.Bold)
              Text('.src("url") - 加载的网页地址').fontSize(12).fontColor('#333333')
              Text('.controller(webController) - 控制器').fontSize(12).fontColor('#333333')
              Text('.javaScriptAccess(true) - JS 访问').fontSize(12).fontColor('#333333')
              Text('.zoomAccess(true) - 缩放').fontSize(12).fontColor('#333333')
              Text('.overviewModeAccess(true) - 概览').fontSize(12).fontColor('#333333')
              Text('.mixedMode(MixedMode.All) - 混合模式').fontSize(12).fontColor('#333333')
              Text('.domStorageAccess(true) - DOM 存储').fontSize(12).fontColor('#333333')
            }
            .width('100%')
            .backgroundColor('#E8F4FD')
            .padding(14)
            .borderRadius(12)

            Column({ space: 6 }) {
              Text('Web 回调事件').fontSize(14).fontColor(DEMO_THEME_COLOR).fontWeight(FontWeight.Bold)
              Text('.onPageBegin() - 页面开始加载').fontSize(12).fontColor('#333333')
              Text('.onPageEnd() - 页面加载结束').fontSize(12).fontColor('#333333')
              Text('.onProgressChange() - 加载进度').fontSize(12).fontColor('#333333')
              Text('.onTitleReceive() - 获取标题').fontSize(12).fontColor('#333333')
              Text('.onErrorReceive() - 加载错误').fontSize(12).fontColor('#333333')
            }
            .width('100%')
            .backgroundColor('#F0F0FF')
            .padding(14)
            .borderRadius(12)
          }
          .width('100%')
        }
      }

      Text('WebComponentStarter - Web 组件基本用法')
        .fontSize(12)
        .fontColor(DEMO_SUBTEXT_COLOR)
        .margin({ top: 12 })
    }
    .width('100%')
    .height('100%')
    .backgroundColor(DEMO_BG_COLOR)
    .padding(16)
  }
}

Web 组件最小可理解模型

先别被一堆属性吓到。你可以把 Web 组件理解成三件东西：

• 一个页面容器
• 一个 URL 入口
• 一个控制器和一组回调

真正落到代码里，最核心的形式就是：

Web({ src: 'https://example.com', controller: this.webController })

src 决定你要加载什么内容，controller 负责后续控制，比如前进、后退、刷新，或者后面更复杂的 JS 调用。

这个结构先记住，剩下的属性基本都是围绕它扩展出来的。

关键属性到底是干什么的

案例里把常见配置列得很直白，这正好适合做一个快速理解。

javaScriptAccess(true)

表示允许页面里的 JavaScript 正常工作。很多现代网页如果关掉这项，页面功能会直接残废。

但这也意味着，你要对加载来源更谨慎。不是所有外部地址都适合直接放进应用里。

zoomAccess(true)

允许用户缩放网页内容。这个配置很适合资讯、文档、图文详情类页面，用户有时确实需要放大阅读。

overviewModeAccess(true)

让网页以更适合当前容器的方式展示，避免内容一进来就只露出一角。你可以把它理解成帮助页面先“看全”的能力。

mixedMode(MixedMode.All)

这个配置跟混合内容加载有关。简单说，就是 HTTPS 页面里是否允许加载 HTTP 资源。实际项目里要慎用，因为安全和兼容问题都可能从这里冒出来。

domStorageAccess(true)

允许网页使用 DOM 存储，比如 localStorage 一类能力。很多登录态、页面偏好、本地缓存都会依赖它。

页面生命周期为什么一定要了解

写原生页面时，你大多只关心 UI 本身。但嵌网页以后，页面内容是在另一个加载过程里完成的，所以你必须知道它什么时候开始、什么时候结束、有没有出错。

案例列出的几个回调，基本就够你覆盖第一阶段开发了：

.onPageBegin()
.onPageEnd()
.onProgressChange()
.onTitleReceive()
.onErrorReceive()

它们分别对应：开始加载、加载结束、进度变化、拿到网页标题、收到错误。

真实项目里，这些回调最常见的用途有三个。

一个是做加载态，比如展示进度条或者 loading 文案；一个是同步页面标题到原生导航栏；另一个是统一兜底错误页，避免白屏看着像死掉了一样。

为什么这个案例用“占位块”反而合理

你可能会觉得，这个案例没有直接写真实 Web()，是不是有点虚。

但换个角度，它其实在帮你先理解“脑图”。对于入门来说，先把能力边界看明白，再去加载真实页面，会比一上来写一堆回调更清楚。

尤其是 Web 组件这种东西，它天生不只是一个 UI 组件，而是一个小型运行环境。你如果只会把它放进去，不理解控制器、回调、权限和存储，后面迟早会卡住。

真实业务里最常见的几个场景

我自己最常见的用法有这几类。

一种是协议和帮助文档。这类内容更新频繁，用网页更灵活。

一种是运营活动页。设计稿变化快、联动后端频繁，重做原生通常不划算。

还有一种是混合式页面，比如原生头部加网页正文。这个场景下，Web 组件会放在页面主体区域，外层再套自己的导航和操作区。

初学者最容易踩的坑

第一个坑，是只会配 src，不会处理错误回调。结果一断网或者 URL 错误，页面就空着。

第二个坑，是把外部网页当成可信内容。尤其开了 JS 能力和桥接能力以后，安全边界必须想清楚。

第三个坑，是布局上不给 Web 组件稳定高度。它本质上是页面内容容器，不给尺寸，显示效果往往很难看。

第四个坑，是把所有内容都想做成 Web。这其实也不对。凡是高频交互、强系统能力依赖、复杂动画和手势页面，优先还是原生更靠谱。

后续该怎么继续学

如果你刚接触 Web 组件，顺序建议是这样的：先会嵌入，再会切换 URL，再会监听加载状态，最后再碰 JS 桥接。

这个顺序不是保守，是因为桥接能力一旦上来，你要同时考虑调用链、数据格式和安全问题。基础没打稳，后面会很乱。

写在最后

Web 组件的价值，不是“在应用里开个网页”这么简单，而是让原生页面和 Web 内容之间有了一个低成本连接点。很多中后台、内容型、活动型页面，都是靠它把效率拉起来的。

先把基础理解扎实，后面再看 URL 切换、JS 交互和页面控制，就不会觉得它是一堆零散配置了。