跳转到内容
WebView AllWebView All

Linux

Linux 由 webview_all_linux 提供,底层使用 WebKitGTK。

项值
ControllerLinuxWebViewController
WidgetLinuxWebViewWidget
DelegateLinuxNavigationDelegate
Cookie managerLinuxWebViewCookieManager
引擎WebKitGTK
系统依赖webkit2gtk-4.1

Linux WebView 是 native GTK widget。插件会在标准 Flutter runner realize FlView 前自动安装所需的 GtkOverlay,应用无需修改 runner。

从 1.4.7 起,可在首次创建 WebView、操作 Cookie 或清理网站数据前配置共享环境。 应先完成 WidgetsFlutterBinding.ensureInitialized():

import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';
import 'package:webview_all_linux/webview_all_linux.dart';
final dataDirectory = await getApplicationSupportDirectory();
final cacheDirectory = await getApplicationCacheDirectory();
await LinuxWebViewController.ensureEnvironment(
userDataPath: p.join(dataDirectory.path, 'WebKit'),
cachePath: p.join(cacheDirectory.path, 'WebKit'),
);

普通 WebView、Cookie 和网站数据清理共用该环境。userDataPath 指定持久化网站 数据目录,cachePath 指定缓存目录。两项都为 null 时,复用已选环境;尚未选择 时沿用 WebKitGTK 默认目录。相对路径按当前工作目录解析。

相同配置可重复调用。显式传参代表完整配置,其中省略或空字符串路径表示平台默认 目录;配置不一致时返回 environment_configuration_conflict,已选环境不能更换 目录。所选环境会保持到应用进程结束,关闭全部 WebView 也不会重置目录。也可使用 initializeEnvironment 进行严格的一次性初始化。

配置后,默认 WebViewCookieManager 和 WebViewDataManager 自动使用所选环境, 无需重复传路径。如果首次操作就是清理,也可通过 LinuxWebViewDataManagerCreationParams(userDataPath: ..., cachePath: ...) 指定目录。

切换目录不会自动迁移旧网站数据。应用后续启动应继续使用相同路径,才能访问该 数据。Cookie 的有效期和持久化行为保持原样。

创建 controller 时设置 LinuxWebViewControllerCreationParams(incognito: true), 即可使用独立的临时 WebKitGTK context。独立创建的无痕 controller 的 Cookie 和网站 存储彼此隔离,也不与普通 WebView 共用;通过同一 WebViewProfile 创建的关联会话 共享该 Profile 的临时存储。数据不会写入共享配置的持久化目录。

共享 Cookie 和网站数据管理器不访问这些会话。创建无痕 controller 不会选择或锁定 共享环境的数据目录。会话结束时调用 controller 的 dispose()。

final params = const LinuxWebViewControllerCreationParams(
incognito: false,
developerExtrasEnabled: true,
downloadsEnabled: false,
mediaPlaybackRequiresUserGesture: false,
pageCacheEnabled: true,
allowFileAccessFromFileUrls: false,
allowUniversalAccessFromFileUrls: false,
zoomFactor: 1.0,
);

incognito 默认为 false;其他字段可为 null,表示保留 WebKitGTK 默认值。

下载默认允许。可在创建时设置 downloadsEnabled: false,或在加载内容前等待 setDownloadsEnabled(false) 完成,取消新下载并阻止保存文件。已开始的下载和 其他 WebView 不受影响。允许下载时使用默认下载目录,并以不覆盖方式安全保存。 从 1.4.8 起,可通过下载代理选择目标文件、 获取进度及结果;插件不会创建保存窗口。

API作用
setDeveloperExtrasEnabled启用开发者功能。
openDevTools打开 Web Inspector。
setDownloadsEnabled控制此 WebView 是否允许新下载,默认允许。
setJavaScriptCanOpenWindowsAutomatically控制 JS popup。
setMediaPlaybackRequiresUserGesture控制媒体自动播放。
setMediaPlaybackAllowsInline控制内联媒体播放。
setPageCacheEnabled控制 page cache。
setAllowFileAccessFromFileUrls允许 file 页面读其他 file URL。
setAllowUniversalAccessFromFileUrls允许 file 页面访问所有 origin。
setDefaultFontSize / setMinimumFontSize字号设置。
setZoomFactor页面缩放。
dispose可选的 Linux 平台专用提前释放入口。

常规清理也是自动的:Linux controller 不再可达时,finalizer 会释放 native WebView。公共 WebViewController 没有增加 dispose(),组件移出树也不会让仍 可能复用的 controller 失效。

通用 enableZoom(false) 会禁用插件可控制的 WebKitGTK 缩放手势,包括 Ctrl+鼠标滚轮和 Ctrl++/-/0;普通滚动与键盘输入不受影响。

Linux 通过 event channel 上报 URL、页面生命周期、进度、history、title、资源错误、HTTP 错误、JS channel、console、scroll、导航请求、HTTP auth、SSL auth、权限请求和 JS dialog。

所有等待 Dart 决策的 native request 都有 30 秒期限。如果应用没有完成请求或 event channel 关闭,导航会拒绝,认证/dialog/TLS 会取消,权限会拒绝。应用回调 抛异常时会打印单行信息并使用相同的安全默认值,不会让 WebKitGTK 一直阻塞。

WebKitGTK 的 GTK port 目前还没有 WebAuthn 支持,上游工作仍记录在 WebKit bug 205350。因此 webview_all_linux 不声明支持 Passkey,也不暴露底层无法执行的虚假开关。 必须使用 Passkey 的 Linux 应用应将认证流程交给支持该能力的外部浏览器, 或保留其他认证方式。插件不使用 JS 凭据模拟,因为它无法保证 WebAuthn 的 origin 与 authenticator 安全语义。

  • WebView 是 GTK 原生 widget,而非 Flutter texture。它会跟随 Flutter 的逻辑位置和尺寸,支持视口边界及矩形祖先裁剪。圆角和椭圆可使用 ClipRRect、ClipOval、PhysicalModel,或 ShapeBorderClipper 配合 RoundedRectangleBorder(包括 NavigationView 的默认内容裁剪)。显示和 点击区域按 GTK 逻辑像素网格同步裁剪;GtkOverlay 仍无法复现任意 Flutter 图层穿插。
  • 自定义 ClipPath 等其他路径须完整包含当前可见矩形。路径切入该区域时(例如包含孔洞), 插件会隐藏原生 WebView 并打印限制说明,避免裁剪区域外仍可显示或点击。
  • 支持系统 HiDPI 和通过 ViewConfiguration 配置的应用界面缩放。
  • 组件变换支持平移;缩放、旋转、倾斜、透视和镜像无法由 GTK 原生子组件准确表示。 遇到这些变换时,插件会隐藏 WebView 并打印限制说明,避免留下视觉错位但仍可交互 的原生区域。
  • 本地文件必须使用绝对路径,并会在加载前规范化;Flutter asset 中的路径穿越、绝对路径和逃出 asset bundle 的符号链接会被拒绝。
  • loadHtmlString 未指定 baseUrl 时,reload() 可能重载 about:blank 而显示空白页。 刷新这类内容应重新调用 loadHtmlString;需要常规 URL 刷新行为时可使用应用资源 URL。
  • 不可信本地文件不要启用 universal file URL access。
  • 不同发行版 WebKitGTK 版本差异明显,媒体、权限和 dialog 需要在目标发行版验证。
  • 音视频依赖系统 GStreamer 组件;Ubuntu/Debian 播放 H.264 可安装 gstreamer1.0-plugins-bad 和 gstreamer1.0-libav,补齐解析器与解码器。
  • WebAuthn/Passkey 需要等待 WebKitGTK GTK port 实现平台 authenticator 集成。
  • frame 更新是异步且错误隔离的,组件销毁阶段不会泄漏未处理异常。