跳转到内容
WebView AllWebView All
这是 1.4.x 版本的文档,最新接口请切换至 latest。

Controller

WebViewController 是核心控制对象。一个 controller 同一时间只能绑定到一个 WebViewWidget,具体操作会委托给当前平台实现。在支持离屏运行的平台上,不创建组件也可以加载内容、接收导航回调、执行 JavaScript 和使用 channel。

通用创建:

final controller = WebViewController();

需要平台创建参数时:

PlatformWebViewControllerCreationParams params =
const PlatformWebViewControllerCreationParams();
if (WebViewPlatform.instance is LinuxWebViewPlatform) {
params = const LinuxWebViewControllerCreationParams(
developerExtrasEnabled: true,
pageCacheEnabled: true,
);
}
final controller = WebViewController.fromPlatformCreationParams(params);

已有平台 controller 时:

final platformController = WindowsWebViewController(
const WindowsWebViewControllerCreationParams(
popupWindowPolicy: WindowsPopupWindowPolicy.sameWindow,
),
);
final controller = WebViewController.fromPlatform(platformController);

不需要显示页面时,使用独立的所有权会话:

import 'dart:async';
final session = await OffscreenWebViewSession.create();
final controller = session.controller;
final loaded = Completer<void>();
try {
await controller.setJavaScriptMode(JavaScriptMode.unrestricted);
await controller.setNavigationDelegate(
NavigationDelegate(onPageFinished: (_) => loaded.complete()),
);
await controller.loadHtmlString('<script>window.price = 42;</script>');
await loaded.future;
final price = await controller.callAsyncJavaScript('return window.price;');
} finally {
await session.close();
}

OHOS 和 Web 调用 OffscreenWebViewSession.create 会抛出 UnsupportedError。Android、iOS、macOS、Windows 和 Linux 可以不创建组件运行,会话关闭前仍可把其 controller 交给组件显示。close() 可重复调用,并会确定性释放会话资源,同时不向公共 controller 增加 dispose()。

离屏运行仍依赖当前应用的 Flutter engine、平台线程、窗口和进程生命周期,并不是后台服务或独立 isolate,也不能绕过系统后台限制。close() 开始后不得继续持有或使用其 controller。

方法用途说明
loadRequest加载 URL 或提交请求URI 必须有 scheme。
loadFile加载设备本地文件Web 平台不支持。
loadFlutterAsset加载 Flutter assetWeb 会解析到 assets/<key>。
loadHtmlString加载内存 HTMLbaseUrl 用于相对路径。
平台GET headersPOST bodyPOST 自定义 headers
Android支持支持不支持,Android postUrl 不接收 headers。
iOS/macOS支持支持支持。
Windows支持支持支持。
Linux支持支持支持。
OHOS支持支持不支持,ArkWeb postUrl 不接收 headers。
Webfetch 支持fetch 支持受 CORS 预检和响应头限制。
final url = await controller.currentUrl();
final title = await controller.getTitle();
if (await controller.canGoBack()) {
await controller.goBack();
}
await controller.reload();

Web 平台会为 controller 发起的加载维护逻辑历史。

await controller.setJavaScriptMode(JavaScriptMode.unrestricted);
await controller.runJavaScript('document.body.dataset.ready = "true";');
final result = await controller.runJavaScriptReturningResult('1 + 2');
await controller.addJavaScriptChannel(
'Host',
onMessageReceived: (JavaScriptMessage message) {
debugPrint(message.message);
},
);

runJavaScriptReturningResult 会拒绝 null 和 undefined。Web 平台可直接 控制同源内容,并通过消息桥控制插件管理的隔离 HTML;直接跨域 iframe URL 仍不可访问。

await controller.scrollTo(0, 0);
final position = await controller.getScrollPosition();
await controller.setOnScrollPositionChange((change) {
debugPrint('${change.x}, ${change.y}');
});

滚动条可见性应先检查:

if (await controller.supportsSetScrollBarsEnabled()) {
await controller.setVerticalScrollBarEnabled(false);
}

其他常用方法:

方法作用
setBackgroundColor设置背景色;macOS 12+ 使用原生 API,更早版本打印说明并安全忽略。
enableZoom控制缩放能力;macOS 使用原生 magnification。
setUserAgent / getUserAgent设置和读取 UA;Web 对非空 override 打印一次说明并忽略。
setOverScrollMode控制 overscroll;macOS 因没有公开 API 而打印说明并安全忽略,部分平台通过 CSS 注入实现。
switch (controller.platform) {
case WindowsWebViewController windows:
await windows.openDevTools();
case LinuxWebViewController linux:
await linux.setDeveloperExtrasEnabled(true);
case OhosWebViewController ohos:
await ohos.setTextZoom(110);
case WebWebViewController web:
await web.setIFrameReferrerPolicy('no-referrer');
}

使用 WebViewSession 在创建页面前选择数据存储,并管理该页面的生命周期:

final capabilities = await WebViewSession.getCapabilities();
final session = await WebViewSession.create(
mode: WebViewSessionMode.incognito,
);
if (session == null) return; // 已打印平台限制或创建失败的原因。
final controller = session.controller;
await session.cookieManager.setCookie(
const WebViewCookie(name: 'account', value: 'temporary', domain: 'example.com'),
);
// 可把 controller 交给 WebViewWidget。移除组件后关闭会话。
await session.close();

shared 使用普通共享存储;incognito(默认)使用平台提供的无痕处理,能力等级由 incognitoSupport 区分; isolatedIncognito 要求独立的原生临时存储。模式在创建时确定,不能动态切换。 create() 不支持所请求的模式或创建失败时会打印具体原因并返回 null,应用可以继续运行。 它不会自动降级为普通会话,也不会通过清空共享 Cookie 模拟无痕。

平台无痕能力
iOS / macOS、Linux支持独立的临时数据存储。
WindowsWebView2 Runtime 支持 InPrivate 创建选项时可用,每个会话使用独立 Profile。
OHOS支持 incognito;原生无痕页面共享一组临时数据,不支持 isolatedIncognito。
Android有限无痕:禁用缓存使用和可用的表单保存,清理当前页面的历史。Cookie、网站存储仍共享且可能持久化。
Web浏览器未向 iframe 开放独立无痕存储。

session.cookieManager 和 session.dataManager 操作该会话所选的存储。 Android 的有限无痕管理器也操作普通共享数据,开启和关闭时不会自动清空共享 Cookie。 默认管理器操作普通数据,但 OHOS 的缓存清理仍是全局操作;OHOS 无痕数据清理会影响其他原生无痕页面, 不会清理普通页面。OHOS 会话管理器的缓存清理因只有全局接口而报告不支持。各数据类别的结果以 WebViewDataClearingResult 为准。Web 不支持会话数据管理时会打印提示并返回空结果或不支持的类别。

关闭会话前先从组件树移除其 WebViewWidget;close() 可重复调用,关闭后不能复用 controller 或会话管理器。 WebViewSession 与 OffscreenWebViewSession 的职责不同:后者管理离屏 controller 的释放,默认使用普通存储。 无痕模式也不保证不产生任何系统临时文件,不会隐藏网络身份或清除应用自行保存的数据。