[webview_flutter_wkwebview] Extended Web View API on iOS to add flexibility when working with local HTML content

packages/webview_flutter/webview_flutter_android/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 4.9.0
+
+* Adds support for `PlatformWebViewController.loadFileWithParams`.
+* Introduces `AndroidLoadFileParams`, a platform-specific extension of `LoadFileParams` for Android that adds support for `headers`.
+
 ## 4.8.2
 
 * Bumps gradle from 8.9.0 to 8.11.1.

packages/webview_flutter/webview_flutter_android/example/pubspec.yaml

@@ -17,7 +17,7 @@ dependencies:
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
     path: ../
-  webview_flutter_platform_interface: ^2.13.0
+  webview_flutter_platform_interface: ^2.14.0
 
 dev_dependencies:
   espresso: ^0.4.0

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

@@ -18,6 +18,41 @@ 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
+base class AndroidLoadFileParams extends LoadFileParams {
+  /// Constructs a [AndroidLoadFileParams], the subclass of a [LoadFileParams].
+  AndroidLoadFileParams({
+    required String absoluteFilePath,
+    this.headers = const <String, String>{},
+  }) : 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 = const <String, String>{},
+  }) {
+    return AndroidLoadFileParams(
+      absoluteFilePath: params.absoluteFilePath,
+      headers: headers,
+    );
+  }
+
+  /// Additional HTTP headers to be included when loading the local file.
+  ///
+  /// If not provided at initialization time, doesn't add any additional headers.
+  ///
+  /// 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
@@ -386,12 +421,29 @@ class AndroidWebViewController extends PlatformWebViewController {
   Future<void> loadFile(
     String absoluteFilePath,
   ) {
-    final String url = absoluteFilePath.startsWith('file://')
-        ? absoluteFilePath
-        : Uri.file(absoluteFilePath).toString();
+    return loadFileWithParams(
+      AndroidLoadFileParams(
+        absoluteFilePath: absoluteFilePath,
+      ),
+    );
+  }
 
-    _webView.settings.setAllowFileAccess(true);
-    return _webView.loadUrl(url, <String, String>{});
+  @override
+  Future<void> loadFileWithParams(
+    LoadFileParams params,
+  ) async {
+    switch (params) {
+      case final AndroidLoadFileParams params:
+        await Future.wait(<Future<void>>[
+          _webView.settings.setAllowFileAccess(true),
+          _webView.loadUrl(params.absoluteFilePath, params.headers),
+        ]);
+
+      default:
+        await loadFileWithParams(
+          AndroidLoadFileParams.fromLoadFileParams(params),
+        );
+    }
   }
 
   @override

packages/webview_flutter/webview_flutter_android/pubspec.yaml

@@ -2,7 +2,7 @@ name: webview_flutter_android
 description: A Flutter plugin that provides a WebView widget on Android.
 repository: https://github.com/flutter/packages/tree/main/packages/webview_flutter/webview_flutter_android
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+webview%22
-version: 4.8.2
+version: 4.9.0
 
 environment:
   sdk: ^3.6.0
@@ -21,7 +21,7 @@ dependencies:
   flutter:
     sdk: flutter
   meta: ^1.10.0
-  webview_flutter_platform_interface: ^2.13.0
+  webview_flutter_platform_interface: ^2.14.0
 
 dev_dependencies:
   build_runner: ^2.1.4

packages/webview_flutter/webview_flutter_android/test/android_webview_controller_test.dart

@@ -274,7 +274,7 @@ void main() {
           ));
     }
 
-    test('loadFile without file prefix', () async {
+    test('Initializing WebView settings on controller creation', () async {
       final MockWebView mockWebView = MockWebView();
       final MockWebSettings mockWebSettings = MockWebSettings();
       createControllerWithMocks(
@@ -292,56 +292,209 @@ void main() {
       verify(mockWebSettings.setUseWideViewPort(false)).called(1);
     });
 
-    test('loadFile without file prefix', () async {
-      final MockWebView mockWebView = MockWebView();
-      final MockWebSettings mockWebSettings = MockWebSettings();
-      final AndroidWebViewController controller = createControllerWithMocks(
-        mockWebView: mockWebView,
-        mockSettings: mockWebSettings,
-      );
+    group('loadFile', () {
+      test('Without file prefix', () async {
+        final MockWebView mockWebView = MockWebView();
+        final MockWebSettings mockWebSettings = MockWebSettings();
+        final AndroidWebViewController controller = createControllerWithMocks(
+          mockWebView: mockWebView,
+          mockSettings: mockWebSettings,
+        );
 
-      await controller.loadFile('/path/to/file.html');
+        await controller.loadFile('/path/to/file.html');
 
-      verify(mockWebSettings.setAllowFileAccess(true)).called(1);
-      verify(mockWebView.loadUrl(
-        'file:///path/to/file.html',
-        <String, String>{},
-      )).called(1);
-    });
+        verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+        verify(mockWebView.loadUrl(
+          'file:///path/to/file.html',
+          <String, String>{},
+        )).called(1);
+      });
 
-    test('loadFile without file prefix and characters to be escaped', () async {
-      final MockWebView mockWebView = MockWebView();
-      final MockWebSettings mockWebSettings = MockWebSettings();
-      final AndroidWebViewController controller = createControllerWithMocks(
-        mockWebView: mockWebView,
-        mockSettings: mockWebSettings,
-      );
+      test('Without file prefix and characters to be escaped', () async {
+        final MockWebView mockWebView = MockWebView();
+        final MockWebSettings mockWebSettings = MockWebSettings();
+        final AndroidWebViewController controller = createControllerWithMocks(
+          mockWebView: mockWebView,
+          mockSettings: mockWebSettings,
+        );
 
-      await controller.loadFile('/path/to/?_<_>_.html');
+        await controller.loadFile('/path/to/?_<_>_.html');
 
-      verify(mockWebSettings.setAllowFileAccess(true)).called(1);
-      verify(mockWebView.loadUrl(
-        'file:///path/to/%3F_%3C_%3E_.html',
-        <String, String>{},
-      )).called(1);
+        verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+        verify(mockWebView.loadUrl(
+          'file:///path/to/%3F_%3C_%3E_.html',
+          <String, String>{},
+        )).called(1);
+      });
+
+      test('With file prefix', () async {
+        final MockWebView mockWebView = MockWebView();
+        final MockWebSettings mockWebSettings = MockWebSettings();
+        final AndroidWebViewController controller = createControllerWithMocks(
+          mockWebView: mockWebView,
+        );
+
+        when(mockWebView.settings).thenReturn(mockWebSettings);
+
+        await controller.loadFile('file:///path/to/file.html');
+
+        verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+        verify(mockWebView.loadUrl(
+          'file:///path/to/file.html',
+          <String, String>{},
+        )).called(1);
+      });
     });
 
-    test('loadFile with file prefix', () async {
-      final MockWebView mockWebView = MockWebView();
-      final MockWebSettings mockWebSettings = MockWebSettings();
-      final AndroidWebViewController controller = createControllerWithMocks(
-        mockWebView: mockWebView,
-      );
+    group('loadFileWithParams', () {
+      group('Using LoadFileParams model', () {
+        test('Without file prefix', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
 
-      when(mockWebView.settings).thenReturn(mockWebSettings);
+          await controller.loadFileWithParams(
+            const LoadFileParams(absoluteFilePath: '/path/to/file.html'),
+          );
 
-      await controller.loadFile('file:///path/to/file.html');
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/file.html',
+            <String, String>{},
+          )).called(1);
+        });
 
-      verify(mockWebSettings.setAllowFileAccess(true)).called(1);
-      verify(mockWebView.loadUrl(
-        'file:///path/to/file.html',
-        <String, String>{},
-      )).called(1);
+        test('Without file prefix and characters to be escaped', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            const LoadFileParams(absoluteFilePath: '/path/to/?_<_>_.html'),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/%3F_%3C_%3E_.html',
+            <String, String>{},
+          )).called(1);
+        });
+
+        test('With file prefix', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            const LoadFileParams(absoluteFilePath: 'file:///path/to/file.html'),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/file.html',
+            <String, String>{},
+          )).called(1);
+        });
+      });
+
+      group('Using WebKitLoadFileParams model', () {
+        test('Without file prefix', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            AndroidLoadFileParams(absoluteFilePath: '/path/to/file.html'),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/file.html',
+            <String, String>{},
+          )).called(1);
+        });
+
+        test('Without file prefix and characters to be escaped', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            AndroidLoadFileParams(absoluteFilePath: '/path/to/?_<_>_.html'),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/%3F_%3C_%3E_.html',
+            <String, String>{},
+          )).called(1);
+        });
+
+        test('With file prefix', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            AndroidLoadFileParams(
+                absoluteFilePath: 'file:///path/to/file.html'),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/file.html',
+            <String, String>{},
+          )).called(1);
+        });
+
+        test('With additional headers', () async {
+          final MockWebView mockWebView = MockWebView();
+          final MockWebSettings mockWebSettings = MockWebSettings();
+          final AndroidWebViewController controller = createControllerWithMocks(
+            mockWebView: mockWebView,
+            mockSettings: mockWebSettings,
+          );
+
+          await controller.loadFileWithParams(
+            AndroidLoadFileParams(
+              absoluteFilePath: 'file:///path/to/file.html',
+              headers: const <String, String>{
+                'Authorization': 'Bearer test_token',
+                'Cache-Control': 'no-cache',
+                'X-Custom-Header': 'test-value',
+              },
+            ),
+          );
+
+          verify(mockWebSettings.setAllowFileAccess(true)).called(1);
+          verify(mockWebView.loadUrl(
+            'file:///path/to/file.html',
+            const <String, String>{
+              'Authorization': 'Bearer test_token',
+              'Cache-Control': 'no-cache',
+              'X-Custom-Header': 'test-value',
+            },
+          )).called(1);
+        });
+      });
     });
 
     test('loadFlutterAsset when asset does not exist', () async {

packages/webview_flutter/webview_flutter_wkwebview/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 3.23.0
+
+* Adds support for `PlatformWebViewController.loadFileWithParams`.
+* Introduces `WebKitLoadFileParams`, a platform-specific extension of `LoadFileParams` for iOS and macOS that adds support for `readAccessPath`.
+
 ## 3.22.1
 
 * Changes the handling of a Flutter method failure from throwing an assertion error to logging the

packages/webview_flutter/webview_flutter_wkwebview/example/pubspec.yaml

@@ -10,7 +10,7 @@ dependencies:
   flutter:
     sdk: flutter
   path_provider: ^2.0.6
-  webview_flutter_platform_interface: ^2.13.0
+  webview_flutter_platform_interface: ^2.14.0
   webview_flutter_wkwebview:
     # When depending on this package from a real application you should use:
     #   webview_flutter: ^x.y.z