HarmonyOS ArkWeb 系列之组件四种加载方式：loadUrl、loadData、rawfile 和 resource 协议完全指南
文章目录
- 先把四种方式整体过一遍
- 方式一：加载在线 URL
- 方式二：rawfile — 加载本地 HTML 文件
- 方式三：resource 协议 — 动态加载本地资源
- 方式四：loadData — 直接渲染 HTML 字符串
- 流程图：四种加载方式对比
- 加载富文本数据（loadRichText）
- 加载后动态切换页面
- 选哪种方式？
Web 组件怎么显示内容？说白了就一件事：告诉它"去哪里拿页面"。HarmonyOS ArkWeb 提供了四种截然不同的加载方式，分别适合不同场景。搞清楚这四种方式，开发体验直接上一个台阶。
先把四种方式整体过一遍
| 方式 | 典型用法 | 适合场景 |
|---|---|---|
| 在线 URL | Web({ src: 'https://...' }) | 加载网络页面 |
| rawfile | Web({ src: $rawfile('index.html') }) | 加载本地 HTML 文件 |
| resource 协议 | Web({ src: 'resource://rawfile/index.html' }) | 动态切换本地资源 |
| loadData | controller.loadData(htmlStr, ...) | 直接渲染 HTML 字符串 |
下面逐一拆解。
方式一：加载在线 URL
最基础的用法，直接传网址：
import{webview}from'@kit.ArkWeb';import{BusinessError}from'@kit.BasicServicesKit';@Entry@Componentstruct LoadUrlPage{controller:webview.WebviewController=newwebview.WebviewController();build(){Column(){Button('跳转到 example1.com').onClick(()=>{try{// 页面已经显示后，用 loadUrl 切换到新地址this.controller.loadUrl('https://www.example1.com');}catch(error){console.error(`ErrorCode:${(errorasBusinessError).code}, Message:${(errorasBusinessError).message}`);}})// 组件创建时先加载这个地址Web({src:'https://www.example.com',controller:this.controller}).width('100%').height('100%')}}}几个要注意的点：
Web({ src })里的地址是组件初始加载的页面- 要切换页面，调
controller.loadUrl()，不要直接修改 src - http 地址需要在
module.json5里申请网络权限：ohos.permission.INTERNET
方式二：rawfile — 加载本地 HTML 文件
把 HTML 文件放在src/main/resources/rawfile/目录下，用$rawfile()引用：
import{webview}from'@kit.ArkWeb';@Entry@Componentstruct RawfilePage{controller:webview.WebviewController=newwebview.WebviewController();build(){Column(){// $rawfile('index.html') 指向 src/main/resources/rawfile/index.htmlWeb({src:$rawfile('index.html'),controller:this.controller}).width('100%').height('100%')}}}rawfile 里的 HTML 可以正常引用同目录下的 CSS、JS、图片：
<!-- src/main/resources/rawfile/index.html --><!DOCTYPEhtml><html><head><linkrel="stylesheet"href="style.css"></head><body><h1>本地页面</h1><scriptsrc="app.js"></script></body></html>方式三：resource 协议 — 动态加载本地资源
$rawfile()是编译期静态引用，如果你想运行时动态指定本地文件路径，就用resource://rawfile/协议：
import{webview}from'@kit.ArkWeb';import{BusinessError}from'@kit.BasicServicesKit';@Entry@Componentstruct ResourceLoadPage{controller:webview.WebviewController=newwebview.WebviewController();build(){Column(){Button('加载 index1.html').onClick(()=>{try{// resource://rawfile/ 后面跟文件名，运行时动态指定this.controller.loadUrl('resource://rawfile/index1.html');}catch(error){console.error(`ErrorCode:${error.code}, Message:${error.message}`);}})// 初始加载 index.htmlWeb({src:'resource://rawfile/index.html',controller:this.controller}).width('100%').height('100%')}}}resource://rawfile/和$rawfile()指向同一个目录，区别是前者是字符串，可以拼接、动态构造。
方式四：loadData — 直接渲染 HTML 字符串
不需要任何文件，直接把 HTML 内容当字符串传进去渲染：
import{webview}from'@kit.ArkWeb';import{BusinessError}from'@kit.BasicServicesKit';@Entry@Componentstruct LoadDataPage{controller:webview.WebviewController=newwebview.WebviewController();// 要渲染的 HTML 内容@StatehtmlContent:string='<!DOCTYPE html>'+'<html><head><title>动态内容</title></head>'+'<body>'+'<h1 style="color: #007AFF;">这是动态生成的内容</h1>'+'<p>无需任何文件，直接渲染字符串</p>'+'</body></html>';build(){Column(){Button('刷新内容').onClick(()=>{try{this.controller.loadData(this.htmlContent,'text/html',// mimeType'UTF-8'// encoding);}catch(error){console.error(`ErrorCode:${(errorasBusinessError).code}, Message:${(errorasBusinessError).message}`);}})Web({src:'about:blank',controller:this.controller}).width('100%').height('100%')}}}loadData非常适合：
- 展示用户生成的富文本内容（帖子、文章详情）
- 渲染模板 + 数据拼接出的动态页面
- 在不依赖网络的情况下显示格式化内容
流程图：四种加载方式对比
加载富文本数据（loadRichText）
如果只是展示纯 HTML 片段，还有个更简单的方式loadRichText，不需要完整的 HTML 文档结构：
import{webview}from'@kit.ArkWeb';import{BusinessError}from'@kit.BasicServicesKit';@Entry@Componentstruct RichTextPage{controller:webview.WebviewController=newwebview.WebviewController();build(){Column(){Button('加载富文本').onClick(()=>{try{// 直接传 HTML 片段，不需要 <html><body> 等标签this.controller.loadRichText('<h2>标题</h2><p>正文内容，<b>加粗</b>，<i>斜体</i></p>');}catch(error){console.error(`ErrorCode:${(errorasBusinessError).code}, Message:${(errorasBusinessError).message}`);}})Web({src:$rawfile('index.html'),controller:this.controller}).width('100%').height('100%')}}}加载后动态切换页面
加载完成后，可以在onPageEnd里做后续操作。比如页面 A 加载完了，自动预加载页面 B：
import{webview}from'@kit.ArkWeb';@Entry@Componentstruct AutoNavigatePage{controller:webview.WebviewController=newwebview.WebviewController();build(){Column(){Web({src:'https://www.example.com',controller:this.controller}).onPageEnd((event)=>{if(event){console.info('当前页加载完成:',event.url);// 在这里可以执行跳转、注入脚本等操作}}).width('100%').height('100%')}}}选哪种方式？
- 纯展示网络内容→ 在线 URL
- App 内嵌静态页面（帮助文档、协议页面）→ rawfile
- 根据用户行为动态切换本地页→ resource 协议
- 渲染动态数据（API 返回的富文本、模板页）→ loadData / loadRichText
四种方式没有高下之分，选对场景就好。