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

错误与限制

API失败情况
loadRequestURI 没有 scheme 时抛 ArgumentError。
loadFlutterAssetkey 为空或 asset 不存在时失败。
loadFile文件不存在时失败;Web 不支持。
runJavaScriptReturningResult返回 null、undefined 或不可序列化值时失败。
addJavaScriptChannel重名 channel 会失败;部分平台还要求合法 JS identifier。
setCookiecookie name/domain/path 非法时失败。
平台API行为
AndroidPOST + 自定义 headersAndroid postUrl 不支持。
OHOSPOST + 自定义 headersArkWeb postUrl 不支持,抛 UnsupportedError。
WebloadFile抛 UnsupportedError。
WebsetUserAgent(nonNull)抛 UnsupportedError。
WebSSL auth 决策浏览器不暴露。
Web跨域 JS/scroll浏览器同源策略阻止。
macOS部分 UIKit WebKit 属性可能抛 UnimplementedError。

最大兼容建议:

  • Android/OHOS 上需要自定义 headers 时优先使用 GET。
  • 同时要求 Android/OHOS 时避免 POST 自定义 headers。
  • Web 非简单请求必须由服务器正确配置 CORS。
  • 手动 HTTP 请求再 loadHtmlString 只适合可控 HTML,不等同于浏览器导航。

生产环境应取消证书错误:

onSslAuthError: (SslAuthError error) async {
await error.cancel();
}

proceed() 只能用于内部测试、实验环境或完全受控网络。

Web iframe 无法检查或脚本控制跨域内容,影响 JS 执行、channel、console hook、dialog hook、scroll API、title 读取和资源错误细节。

平台限制
Windows必须安装 WebView2 Runtime。
Linux必须安装 WebKitGTK 4.1,runner 需要 GtkOverlay。
OHOS需要 OHOS Flutter SDK,ArkWeb 行为会随 API 版本变化。
Android能力取决于系统 WebView/Chrome 版本。
iOS/macOS能力取决于 OS 版本和应用 entitlement。