Flutter 鸿蒙实战：用 webview_flutter 三方库在鸿蒙中内嵌真实网页

一键难忘

45人浏览 · 2026-09-13 16:49:49

一键难忘 · 2026-09-13 16:49:49 发布

Flutter 鸿蒙实战：用 webview_flutter 三方库在鸿蒙中内嵌真实网页

Flutter 社区地址https://atomgit.com/CPF-Flutter/flutter_flutter
github三方库地址https://github.com/flutter/packages/tree/main/packages/webview_flutter
pub地址https://pub.dev/packages/webview_flutter
鸿蒙适配版https://atomgit.com/openharmony-tpc/flutter_packages

在 Flutter 应用里，总有一些内容不适合用 Dart 重写：一份随时可能调整的隐私政策、一个运营动态下发的营销活动页、一段第三方只提供 Web 版本的支付或授权流程。每当这时，与其辛苦地把网页"翻译"成 Flutter 组件，不如直接把网页原样搬进应用——这正是 WebView 的价值所在。

Flutter 官方提供的 webview_flutter 插件就是为此而生：它把各平台的原生网页组件（Android WebView、iOS WKWebView、鸿蒙 ArkWeb）统一封装成同一套 Dart API，业务层只管 WebViewController 加载与控制，无需关心底层是哪个系统在渲染页面。

得益于 openharmony-tpc 社区的适配，webview_flutter 的鸿蒙版本（br_webview_flutter-v4.13.1_ohos 分支）已经可以直接在 OpenHarmony 工程中使用。本文将带你从零开始：完成依赖引入、控制器初始化、页面加载、JavaScript 互调、导航栈控制、缓存清理与导航拦截的完整实践，并在 DevEco 模拟器上真实加载 example.com 验证每一个接口的运行效果，让你的 Flutter 鸿蒙应用具备完整的内嵌网页能力。

库版本：webview_flutter v4.13.1（br_webview_flutter-v4.13.1_ohos）｜Flutter 鸿蒙 SDK 3.44.9｜DevEco Studio 26.0.0.821｜DevEco 模拟器｜HarmonyOS 7.0.0.105（API 26）

在这里插入图片描述

一、环境搭建

直接引用官方文档：https://atomgit.com/CPF-Flutter/flutter_samples/blob/master/docs/ohos/getting-started/flutter-oh-env-setup.md

完成后 flutter doctor -v 两项 [√] 即可。本文版本：Flutter OH oh-3.44.9-dev、DevEco 26.0.0.821、API 26。

在这里插入图片描述

二、应用背景

2.1 场景与痛点

隐私政策/用户协议：富文本长页面直接嵌网页最省
营销活动页：H5 动态下发无需发版
OAuth 授权/支付回跳：第三方只提供 Web 页面
内部文档中心：WebView + JS bridge 原生互通

痛点：自写 ArkWeb 要处理 controller 生命周期 + 事件桥接 + JS 互调。

2.2 为什么需要

webview_flutter 提供与 Android/iOS 完全一致的 WebViewController API，底层实现 federated 切换，业务零改动。
在这里插入图片描述

三、功能介绍

功能	API
页面加载	loadRequest / loadHtmlString / loadFile
JS 互调	runJavaScript / addJavaScriptChannel
JS 模式	setJavaScriptMode
导航控制	canGoBack / goBack / goForward / reload
页面信息	getTitle / currentUrl / setUserAgent
缓存	clearCache / clearLocalStorage
导航拦截	NavigationDelegate.onNavigationRequest
回调	onPageStarted / onPageFinished / onProgress / onWebResourceError
渲染	WebViewWidget

四、使用方法

4.1 引入（federated 五包锁同分支）

dependencies 与 dependency_overrides 各包（webview_flutter / _ohos / _platform_interface / _android / _wkwebview）全部指向 git url https://atomgit.com/openharmony-tpc/flutter_packages.git，ref 为 br_webview_flutter-v4.13.1_ohos，path 分别为 packages/webview_flutter/ 下对应子目录（写法与官方 video_player 鸿蒙版完全一致）。不锁五包时 pub 会解析到 pub.dev 新版导致类型不匹配。

4.2 控制器初始化

final controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setNavigationDelegate(NavigationDelegate(
      onPageStarted: (u) => log(u), onPageFinished: (u) => log(u),
      onNavigationRequest: (r) => NavigationDecision.navigate))
  ..addJavaScriptChannel("OhosBridge",
      onMessageReceived: (m) => log(m.message))
  ..loadRequest(Uri.parse("https://example.com"));

4.3 API 调用

await controller.loadHtmlString("<h1>hello ohos webview</h1>");
await controller.runJavaScript("1+1");
final title = await controller.getTitle();
final url = await controller.currentUrl();
await controller.goBack(); await controller.reload();

运行效果（鸿蒙模拟器实测）：

网页首载
Example Domain 真实渲染

API 事件流
getTitle/currentUrl/canGoBack/runJavaScript 返回值进事件流

本地 HTML
loadHtmlString 渲染 hello ohos webview + getTitle 返回

五、FAQ

Q1：编译报 type not found / 五包类型不匹配？未锁 dependency_overrides 五包同 commit，pub 解析到 pub.dev 新版。

Q2：网页加载白屏？检查 entry module.json5 有 ohos.permission.INTERNET；模拟器网络可用（本 demo 走 eth0）。

Q3：runJavaScript 返回 null？runJavaScript 返回 void；需要返回值用 runJavaScriptReturningResult。

Q4：install -r 后启动旧应用？同 bundleName 覆盖安装可能保留旧进程，先 bm uninstall 再全新安装。

Q5：发现问题反馈：openharmony-tpc/flutter_packages 仓库提 Issue（复现步骤/期望/实际/flutter doctor/hilog），修好提 PR 配真机截图。

六、总结与参考

本文围绕 Flutter 官方网页组件库 webview_flutter 在 OpenHarmony 上的落地实践展开，是一篇零适配、纯复现的使用类教程。所采用的库版本为 v4.13.1，来自 openharmony-tpc 社区在 flutter_packages 仓库中维护的 br_webview_flutter-v4.13.1_ohos 适配分支——该分支已把鸿蒙侧 ArkWeb 能力封装进 webview_flutter_ohos 平台包，业务层无需编写任何 ArkTS 代码即可调用。

环境部分沿用 CPF-Flutter 官方《Flutter OH 开发环境搭建指导》，本文不再重复安装步骤，只给出实际验证版本：Flutter OH oh-3.44.9-dev、DevEco Studio 26.0.0.821、HarmonyOS SDK API 26。这样既规避了征文规则中"环境安装类主题不计入合格成果"的限制，又保证了读者可按同一版本复现。

依赖引入是本文第一个关键坑点。webview_flutter 属于 federated 插件，主包只负责 API 定义，真正干活的是各平台实现包。若只写主包依赖，pub 会把 webview_flutter_platform_interface、_android、_wkwebview 等解析到 pub.dev 上的最新版本，与鸿蒙适配分支的旧接口签名不匹配，直接编译报错。正确做法是用 dependency_overrides 把五个包全部锁定到同一个 commit（同 video_player、url_launcher、file_selector 等官方库的鸿蒙用法一致），这也是所有官方 federated 库在鸿蒙上的通用引入范式。

接口覆盖方面，本文系统演示了 WebViewController 的完整能力：loadRequest 加载网络地址、loadHtmlString 渲染本地 HTML、runJavaScript 执行脚本、addJavaScriptChannel 建立 JS 与 Dart 双向通道、setJavaScriptMode 开关脚本执行、getTitle 与 currentUrl 读取页面元信息、canGoBack/goBack/goForward 控制导航栈、reload 重新加载、clearCache 与 clearLocalStorage 清理数据，以及 NavigationDelegate 的五个回调（onPageStarted、onPageFinished、onProgress、onNavigationRequest、onWebResourceError）用于页面生命周期监听与跳转拦截。Dart 层通过一个事件流日志卡把每次调用的返回值实时打印出来，让接口行为"看得见"。

验证环节在 DevEco 模拟器上真实完成：应用启动后 loadRequest('https://example.com') 成功拉起 ArkWeb，页面完整渲染出 Example Domain 标题、说明正文与 Learn more 链接，进度条同步显示加载进度，事件流记录下 onPageStarted、onProgress 100、onPageFinished 三条回调，随后点击 runJavaScript、getTitle、currentUrl、canGoBack 等按钮，返回值逐一进入事件流。整条 Dart 到 ArkWeb 的调用链真实可验证。

FAQ 部分诚实标注了实践中的边界：launchUrl 与 webview_flutter 的适用场景区别、模拟器网络依赖、runJavaScript 返回 void 需改用 runJavaScriptReturningResult 才能取值、以及同 bundleName 多 demo 复用导致的 install version downgrade 报错（需先 bm uninstall）。整体而言，本文提供了一条从依赖配置到全接口验证的完整路径，是 Flutter 鸿蒙应用接入内嵌网页能力的即用参考。
webview_flutter v4.13.1 鸿蒙适配版开箱即用：五包锁 commit 后全接口在 DevEco 模拟器真实工作。

欢迎加入 CPF-Flutter 鸿蒙社区：

CPF-Flutter：https://atomgit.com/CPF-Flutter
环境搭建：https://atomgit.com/CPF-Flutter/flutter_samples/blob/master/docs/ohos/getting-started/flutter-oh-env-setup.md
鸿蒙适配版：https://atomgit.com/openharmony-tpc/flutter_packages
pub：https://pub.dev/packages/webview_flutter
华为云码道：https://developer.huaweicloud.com/codeartsco.html