Extended Web View API on iOS

flutter/flutter#136479

• Deprecates `WebViewController.loadFile(String)` in favor of `WebViewController.loadFileWithParams(LoadFileParams)`.
• Introduces `AndroidLoadFileParams` and `WebKitLoadFileParams` to support platform-specific parameters when loading local HTML files on Android and iOS/macOS.

Author: agavrilko

packages/webview_flutter/webview_flutter/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 4.14.0
+
+* Deprecates `WebViewController.loadFile(String)` in favor of `WebViewController.loadFileWithParams(LoadFileParams)`.
+* Introduces `AndroidLoadFileParams` and `WebKitLoadFileParams` to support platform-specific parameters when loading local HTML files on Android and iOS/macOS.
+
 ## 4.13.0
 
 * Adds support to respond to recoverable SSL certificate errors. See `NavigationDelegate(onSSlAuthError)`.

packages/webview_flutter/webview_flutter/example/pubspec.yaml

@@ -20,6 +20,14 @@ dependencies:
   webview_flutter_android: ^4.7.0
   webview_flutter_wkwebview: ^3.22.0
 
+dependency_overrides:
+  webview_flutter_android:
+    path: ../../webview_flutter_android
+  webview_flutter_platform_interface:
+    path: ../../webview_flutter_platform_interface
+  webview_flutter_wkwebview:
+    path: ../../webview_flutter_wkwebview
+
 dev_dependencies:
   build_runner: ^2.1.5
   espresso: ^0.4.0

packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart

@@ -131,10 +131,25 @@ class WebViewController {
   /// `/Users/username/Documents/www/index.html`.
   ///
   /// Throws a `PlatformException` if the [absoluteFilePath] does not exist.
+  @Deprecated('Use loadFileWithParams(LocalFileParams params) instead. '
+      'This method will be removed in a future release.')
   Future<void> loadFile(String absoluteFilePath) {
     return platform.loadFile(absoluteFilePath);
   }
 
+  /// Loads a local HTML file using the provided [params].
+  ///
+  /// The [params] object should contain the absolute path to the
+  /// file as it is stored on the device. For example:
+  /// `/Users/username/Documents/www/index.html`.
+  /// In addition, it may include platform-specific fields,
+  /// such as headers (on Android) or resource paths (on iOS/macOS).
+  ///
+  /// Throws a `PlatformException` if the [absoluteFilePath] does not exist.
+  Future<void> loadFileWithParams(LoadFileParams params) {
+    return platform.loadFileWithParams(params);
+  }
+
   /// Loads the Flutter asset specified in the pubspec.yaml file.
   ///
   /// Throws a `PlatformException` if [key] is not part of the specified assets

packages/webview_flutter/webview_flutter/pubspec.yaml

@@ -2,7 +2,7 @@ name: webview_flutter
 description: A Flutter plugin that provides a WebView widget backed by the system webview.
 repository: https://github.com/flutter/packages/tree/main/packages/webview_flutter/webview_flutter
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+webview%22
-version: 4.13.0
+version: 4.14.0
 
 environment:
   sdk: ^3.6.0
@@ -25,6 +25,14 @@ dependencies:
   webview_flutter_platform_interface: ^2.13.0
   webview_flutter_wkwebview: ^3.22.0
 
+dependency_overrides:
+  webview_flutter_android:
+    path: ../webview_flutter_android
+  webview_flutter_platform_interface:
+    path: ../webview_flutter_platform_interface
+  webview_flutter_wkwebview:
+    path: ../webview_flutter_wkwebview
+
 dev_dependencies:
   build_runner: ^2.1.5
   flutter_test:

packages/webview_flutter/webview_flutter/test/webview_controller_test.dart

@@ -27,6 +27,22 @@ void main() {
     verify(mockPlatformWebViewController.loadFile('file/path'));
   });
 
+  test('loadFileWithParams', () async {
+    final MockPlatformWebViewController mockPlatformWebViewController =
+        MockPlatformWebViewController();
+
+    final WebViewController webViewController = WebViewController.fromPlatform(
+      mockPlatformWebViewController,
+    );
+
+    await webViewController.loadFileWithParams(
+      const LoadFileParams(absoluteFilePath: 'file/path'),
+    );
+    verify(mockPlatformWebViewController.loadFileWithParams(
+      const LoadFileParams(absoluteFilePath: 'file/path'),
+    ));
+  });
+
   test('loadFlutterAsset', () async {
     final MockPlatformWebViewController mockPlatformWebViewController =
         MockPlatformWebViewController();

packages/webview_flutter/webview_flutter/test/webview_controller_test.mocks.dart

@@ -78,6 +78,14 @@ class MockPlatformWebViewController extends _i1.Mock
         returnValueForMissingStub: _i5.Future<void>.value(),
       ) as _i5.Future<void>);
 
+  @override
+  _i5.Future<void> loadFileWithParams(_i2.LoadFileParams? params) =>
+      (super.noSuchMethod(
+        Invocation.method(#loadFileWithParams, [params]),
+        returnValue: _i5.Future<void>.value(),
+        returnValueForMissingStub: _i5.Future<void>.value(),
+      ) as _i5.Future<void>);
+
   @override
   _i5.Future<void> loadFlutterAsset(String? key) => (super.noSuchMethod(
         Invocation.method(#loadFlutterAsset, [key]),

packages/webview_flutter/webview_flutter/test/webview_widget_test.mocks.dart

@@ -91,6 +91,14 @@ class MockPlatformWebViewController extends _i1.Mock
         returnValueForMissingStub: _i7.Future<void>.value(),
       ) as _i7.Future<void>);
 
+  @override
+  _i7.Future<void> loadFileWithParams(_i2.LoadFileParams? params) =>
+      (super.noSuchMethod(
+        Invocation.method(#loadFileWithParams, [params]),
+        returnValue: _i7.Future<void>.value(),
+        returnValueForMissingStub: _i7.Future<void>.value(),
+      ) as _i7.Future<void>);
+
   @override
   _i7.Future<void> loadFlutterAsset(String? key) => (super.noSuchMethod(
         Invocation.method(#loadFlutterAsset, [key]),

packages/webview_flutter/webview_flutter_android/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.8.0
+
+* Introduces `AndroidLoadFileParams`, a platform-specific extension of `LoadFileParams` for Android that adds support for `headers`.
+
 ## 4.7.0
 
 * Adds support to respond to recoverable SSL certificate errors. See `AndroidNavigationDelegate.setOnSSlAuthError`.

packages/webview_flutter/webview_flutter_android/example/pubspec.yaml

@@ -19,6 +19,10 @@ dependencies:
     path: ../
   webview_flutter_platform_interface: ^2.13.0
 
+dependency_overrides:
+  webview_flutter_platform_interface:
+    path: ../../webview_flutter_platform_interface
+
 dev_dependencies:
   espresso: ^0.4.0
   flutter_test:

packages/webview_flutter/webview_flutter_android/lib/src/android_webview_controller.dart

@@ -18,6 +18,48 @@ import 'android_webkit_constants.dart';
 import 'platform_views_service_proxy.dart';
 import 'weak_reference_utils.dart';
 
+/// Object specifying parameters for loading a local file in a
+/// [AndroidWebViewController].
+@immutable
+class AndroidLoadFileParams extends LoadFileParams {
+  /// Constructs a [AndroidLoadFileParams], the subclass of a [LoadFileParams].
+  ///
+  /// Optionally, [headers] map may be included, which contains key-value pairs
+  /// that will be passed as additional HTTP headers when loading the file.
+  AndroidLoadFileParams({
+    required String absoluteFilePath,
+    this.headers = _defaultHeaders,
+  }) : super(
+          absoluteFilePath: absoluteFilePath.startsWith('file://')
+              ? absoluteFilePath
+              : Uri.file(absoluteFilePath).toString(),
+        );
+
+  /// Constructs a [AndroidLoadFileParams] using a [LoadFileParams].
+  factory AndroidLoadFileParams.fromLoadFileParams(
+    LoadFileParams params, {
+    Map<String, String> headers = _defaultHeaders,
+  }) {
+    return AndroidLoadFileParams(
+      absoluteFilePath: params.absoluteFilePath,
+      headers: headers,
+    );
+  }
+
+  /// Default empty headers used when no custom headers are provided.
+  ///
+  /// This constant ensures that the [headers] parameter is never `null`,
+  /// simplifying internal logic and avoiding the need for null checks.
+  static const Map<String, String> _defaultHeaders = <String, String>{};
+
+  /// Additional HTTP headers to be included when loading the local file.
+  ///
+  /// On Android, WebView supports adding headers when loading local or remote
+  /// content. This can be useful for scenarios like authentication,
+  /// content-type overrides, or custom request context.
+  final Map<String, String> headers;
+}
+
 /// Object specifying creation parameters for creating a [AndroidWebViewController].
 ///
 /// When adding additional fields make sure they can be null or have a default
@@ -383,15 +425,19 @@ class AndroidWebViewController extends PlatformWebViewController {
       _webView.pigeon_instanceManager.getIdentifier(_webView)!;
 
   @override
-  Future<void> loadFile(
-    String absoluteFilePath,
-  ) {
-    final String url = absoluteFilePath.startsWith('file://')
-        ? absoluteFilePath
-        : Uri.file(absoluteFilePath).toString();
+  Future<void> loadFileWithParams(LoadFileParams params) {
+    switch (params) {
+      case final AndroidLoadFileParams params:
+        _webView.settings.setAllowFileAccess(true);
+        return _webView.loadUrl(
+          params.absoluteFilePath,
+          params.headers,
+        );
 
-    _webView.settings.setAllowFileAccess(true);
-    return _webView.loadUrl(url, <String, String>{});
+      default:
+        return loadFileWithParams(
+            AndroidLoadFileParams.fromLoadFileParams(params));
+    }
   }
 
   @override