文件、Asset 和 HTML

本地文件

await controller.loadFile('/Users/me/Documents/page.html');

平台	行为
Android	通过 file URL 加载，`AndroidLoadFileParams` 可附加 headers。
iOS/macOS	WebKit 本地文件加载，`WebKitLoadFileParams` 控制可读范围。
Windows	把文件目录映射为内部 HTTPS virtual host。
Linux	通过 WebKitGTK 加载绝对路径。
OHOS	启用 file access 后加载 file URL。
Web	不支持。浏览器不允许 hosted app 读取任意本地文件。

Android 文件 headers

await (controller.platform as AndroidWebViewController).loadFileWithParams(
  AndroidLoadFileParams(
    absoluteFilePath: '/sdcard/Download/page.html',
    headers: const <String, String>{'X-Source': 'app'},
  ),
);

WebKit read access

await (controller.platform as WebKitWebViewController).loadFileWithParams(
  WebKitLoadFileParams(
    absoluteFilePath: '/Users/me/site/index.html',
    readAccessPath: '/Users/me/site',
  ),
);

readAccessPath 必须覆盖 HTML 引用的图片、脚本和样式。

Flutter Asset

flutter:
  assets:
    - assets/help/index.html

await controller.loadFlutterAsset('assets/help/index.html');

Windows 会为每个 controller 使用随机私有 HTTPS host 映射规范化后的 asset 目录，拒绝跨 origin 访问，并随导航替换或清理映射。Linux 只接受绝对文件路径，并会在加载前将其规范化；两者都会拒绝路径穿越和逃出 Flutter asset 目录的符号链接。Web 会解析为生成后的 assets/ 路径。

内联 HTML

await controller.loadHtmlString(
  '<html><body><a href="details.html">Details</a></body></html>',
  baseUrl: 'https://docs.example.com/help/',
);

有相对链接时应提供 baseUrl。

自定义请求

await controller.loadRequest(
  Uri.parse('https://api.example.com/form'),
  method: LoadRequestMethod.post,
  headers: const <String, String>{'Content-Type': 'application/json'},
  body: Uint8List.fromList(utf8.encode('{"ok":true}')),
);

平台	说明
Android	POST + 自定义 headers 不支持。
OHOS	POST + 自定义 headers 不支持，会抛 `UnsupportedError`。
Web	非简单请求通过 `fetch`，需要服务端 CORS 允许；响应保留原始二进制字节，并使用 redirect 后的最终 URL。
Windows/Linux/iOS/macOS	支持 method、headers 和 body。

不支持的平台可用 app HTTP client 手动请求，再用 loadHtmlString 加载响应 HTML；但这不等价于浏览器原生导航，cookie、redirect、service worker 等语义会不同。