Flutter 鸿蒙实战：用 webview_flutter 三方库在 鸿蒙 中内嵌真实网页
发布时间：2026/9/28 12:01:33 作者：尧图编辑部 阅读量：1,286
Flutter 鸿蒙实战用 webview_flutter 三方库在 鸿蒙 中内嵌真实网页Flutter 社区地址https://atomgit.com/CPF-Flutter/flutter_fluttergithub三方库地址https://github.com/flutter/packages/tree/main/packages/webview_flutterpub地址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.1br_webview_flutter-v4.13.1_ohosFlutter 鸿蒙 SDK 3.44.9DevEco Studio 26.0.0.821DevEco 模拟器HarmonyOS 7.0.0.105API 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 / loadFileJS 互调runJavaScript / addJavaScriptChannelJS 模式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.gitref 为 br_webview_flutter-v4.13.1_ohospath 分别为 packages/webview_flutter/ 下对应子目录写法与官方 video_player 鸿蒙版完全一致。不锁五包时 pub 会解析到 pub.dev 新版导致类型不匹配。4.2 控制器初始化finalcontrollerWebViewController()..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 调用awaitcontroller.loadHtmlString(h1hello ohos webview/h1);awaitcontroller.runJavaScript(11);finaltitleawaitcontroller.getTitle();finalurlawaitcontroller.currentUrl();awaitcontroller.goBack();awaitcontroller.reload();运行效果鸿蒙模拟器实测Example Domain 真实渲染getTitle/currentUrl/canGoBack/runJavaScript 返回值进事件流loadHtmlString 渲染 hello ohos webview getTitle 返回五、FAQQ1编译报 type not found / 五包类型不匹配未锁 dependency_overrides 五包同 commitpub 解析到 pub.dev 新版。Q2网页加载白屏检查 entry module.json5 有 ohos.permission.INTERNET模拟器网络可用本 demo 走 eth0。Q3runJavaScript 返回 nullrunJavaScript 返回 void需要返回值用 runJavaScriptReturningResult。Q4install -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 OHoh-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-Flutterhttps://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_packagespubhttps://pub.dev/packages/webview_flutter华为云码道https://developer.huaweicloud.com/codeartsco.html
尧图网站开发 