平台设置

大多数平台添加 xue_hua_webview 后即可使用，但部分引擎需要运行时组件或权限。

Android

最低 SDK 需要 API 24。根据页面能力添加系统权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

CAMERA 用于 <input type="file" capture> 和 getUserMedia 相机。插件已按可选硬件声明该权限。Photo Picker 与 ACTION_GET_CONTENT 不需要 READ_MEDIA_* 或 READ_EXTERNAL_STORAGE。只有自定义 setOnShowFileSelector 直接读 MediaStore 时才需要这些存储权限。

如果 WebView 表单控件需要 Material Components 风格，请让应用主题兼容 Material Components。文件输入默认走内置选择器；setOnShowFileSelector 是可选覆盖。网页申请相机或麦克风前，宿主仍需先获得 Android 运行时权限，再调用 request.grant()。

iOS

最低 iOS 13.0。页面需要访问摄像头、麦克风或定位时，在 Info.plist 添加说明：

<key>NSCameraUsageDescription</key>
<string>Allow pages to use the camera after approval.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Allow pages to use the microphone after approval.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Allow pages to pick photos or videos after approval.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Allow pages to request location.</string>

<input type="file"> 使用 WKWebView 系统选择器。缺少 NSCameraUsageDescription 时，capture 流程可能崩溃。

HTTPS 页面不需要额外的 App Transport Security（ATS）例外。明文 HTTP 会被 ATS 拦截，除非宿主应用在 Info.plist 中为对应域名添加例外（例如 NSExceptionDomains）。不要默认开启 NSAllowsArbitraryLoads，除非你明确接受其安全代价。

App-Bound Domains 需要宿主应用配置域名，并用 WebKitWebViewControllerCreationParams(limitsNavigationsToAppBoundDomains: true) 创建控制器。

macOS

最低 macOS 10.15。沙盒应用如需联网，需要启用 outgoing network entitlement：

<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.files.user-selected.read-only</key>
<true/>

文件输入通过 WKUIDelegate.runOpenPanel 弹出 NSOpenPanel。沙盒应用需要 user-selected files 权限。

macOS 与 iOS 共用 xue_hua_webview_wkwebview，但部分 UIKit 风格的属性在 macOS 上没有实现。详见iOS 和 macOS。

Windows

Windows 使用 WebView2，目标机器必须安装 Microsoft Edge WebView2 Runtime。

final version = await WindowsWebViewController.getWebViewVersion();
if (version == null) {
  // 提示用户安装 WebView2 Runtime。
}

需要自定义用户数据目录或浏览器路径时，在创建 controller 前初始化环境：

await WindowsWebViewController.initializeEnvironment(
  userDataPath: 'C:\\Users\\Public\\MyApp\\WebView2',
);

Linux

需要 WebKitGTK 4.1。Ubuntu 系发行版可安装：

sudo apt install libwebkit2gtk-4.1-dev

Linux 实现会在标准 Flutter runner realize FlView 之前自动安装所需的 GtkOverlay，应用无需修改 linux/runner/my_application.cc。

Web

Web 实现是 HTML iframe，必须遵守浏览器安全边界：

不能读取用户机器上的任意本地文件。
不能向跨域 iframe 执行 JavaScript。
不能拦截 TLS 证书错误决策。
Cookie 受 document.cookie 和浏览器隐私策略限制。