From 1c89a0e888b09660f7a8403209eb735d4983b252 Mon Sep 17 00:00:00 2001 From: Maurice Parrish <10687576+bparrishMines@users.noreply.github.com> Date: Sun, 19 Feb 2023 11:04:23 -0500 Subject: [PATCH] [webview_flutter] Adds examples of accessing platform-specific features for each class (#7089) * start * more docs and version bump * fix main --- .../webview_flutter/CHANGELOG.md | 4 ++ .../webview_flutter/webview_flutter/README.md | 12 +++- .../lib/src/navigation_delegate.dart | 49 +++++++++++++++ .../lib/src/webview_controller.dart | 56 +++++++++++++++++ .../lib/src/webview_cookie_manager.dart | 52 +++++++++++++++ .../lib/src/webview_widget.dart | 63 ++++++++++++++++++- .../webview_flutter/pubspec.yaml | 2 +- 7 files changed, 232 insertions(+), 6 deletions(-) diff --git a/packages/webview_flutter/webview_flutter/CHANGELOG.md b/packages/webview_flutter/webview_flutter/CHANGELOG.md index 6d2e860e29ec..84f890790128 100644 --- a/packages/webview_flutter/webview_flutter/CHANGELOG.md +++ b/packages/webview_flutter/webview_flutter/CHANGELOG.md @@ -1,3 +1,7 @@ +## 4.0.4 + +* Adds examples of accessing platform-specific features for each class. + ## 4.0.3 * Updates example code for `use_build_context_synchronously` lint. diff --git a/packages/webview_flutter/webview_flutter/README.md b/packages/webview_flutter/webview_flutter/README.md index 98f7b667025b..b30b8bc20fa1 100644 --- a/packages/webview_flutter/webview_flutter/README.md +++ b/packages/webview_flutter/webview_flutter/README.md @@ -99,7 +99,7 @@ import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart'; ``` Now, additional features can be accessed through the platform implementations. Classes -`WebViewController`, `WebViewWidget`, `NavigationDelegate`, and `WebViewCookieManager` pass their +[WebViewController], [WebViewWidget], [NavigationDelegate], and [WebViewCookieManager] pass their functionality to a class provided by the current platform. Below are a couple of ways to access additional functionality provided by the platform and is followed by an example. @@ -212,11 +212,17 @@ Below is a non-exhaustive list of changes to the API: * `WebView.userAgent` -> `WebViewController.setUserAgent` * `WebView.backgroundColor` -> `WebViewController.setBackgroundColor` * The following features have been moved to an Android implementation class. See section - `Platform-Specific Features` for details on accessing Android platform specific features. + `Platform-Specific Features` for details on accessing Android platform-specific features. * `WebView.debuggingEnabled` -> `static AndroidWebViewController.enableDebugging` * `WebView.initialMediaPlaybackPolicy` -> `AndroidWebViewController.setMediaPlaybackRequiresUserGesture` * The following features have been moved to an iOS implementation class. See section - `Platform-Specific Features` for details on accessing iOS platform specific features. + `Platform-Specific Features` for details on accessing iOS platform-specific features. * `WebView.gestureNavigationEnabled` -> `WebKitWebViewController.setAllowsBackForwardNavigationGestures` * `WebView.initialMediaPlaybackPolicy` -> `WebKitWebViewControllerCreationParams.mediaTypesRequiringUserAction` * `WebView.allowsInlineMediaPlayback` -> `WebKitWebViewControllerCreationParams.allowsInlineMediaPlayback` + + +[WebViewController]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewController-class.html +[WebViewWidget]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewWidget-class.html +[NavigationDelegate]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/NavigationDelegate-class.html +[WebViewCookieManager]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewCookieManager-class.html \ No newline at end of file diff --git a/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart b/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart index 0651ad45f229..3237fa41c0bb 100644 --- a/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart +++ b/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart @@ -12,6 +12,28 @@ import 'webview_controller.dart'; /// the progress of navigation requests. /// /// See [WebViewController.setNavigationDelegate]. +/// +/// ## Platform-Specific Features +/// This class contains an underlying implementation provided by the current +/// platform. Once a platform implementation is imported, the examples below +/// can be followed to use features provided by a platform's implementation. +/// +/// {@macro webview_flutter.NavigationDelegate.fromPlatformCreationParams} +/// +/// Below is an example of accessing the platform-specific implementation for +/// iOS and Android: +/// +/// ```dart +/// final NavigationDelegate navigationDelegate = NavigationDelegate(); +/// +/// if (WebViewPlatform.instance is WebKitWebViewPlatform) { +/// final WebKitNavigationDelegate webKitDelegate = +/// navigationDelegate.platform as WebKitNavigationDelegate; +/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { +/// final AndroidNavigationDelegate androidDelegate = +/// navigationDelegate.platform as AndroidNavigationDelegate; +/// } +/// ``` class NavigationDelegate { /// Constructs a [NavigationDelegate]. NavigationDelegate({ @@ -32,6 +54,33 @@ class NavigationDelegate { /// Constructs a [NavigationDelegate] from creation params for a specific /// platform. + /// + /// {@template webview_flutter.NavigationDelegate.fromPlatformCreationParams} + /// Below is an example of setting platform-specific creation parameters for + /// iOS and Android: + /// + /// ```dart + /// PlatformNavigationDelegateCreationParams params = + /// const PlatformNavigationDelegateCreationParams(); + /// + /// if (WebViewPlatform.instance is WebKitWebViewPlatform) { + /// params = WebKitNavigationDelegateCreationParams + /// .fromPlatformNavigationDelegateCreationParams( + /// params, + /// ); + /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { + /// params = AndroidNavigationDelegateCreationParams + /// .fromPlatformNavigationDelegateCreationParams( + /// params, + /// ); + /// } + /// + /// final NavigationDelegate navigationDelegate = + /// NavigationDelegate.fromPlatformCreationParams( + /// params, + /// ); + /// ``` + /// {@endtemplate} NavigationDelegate.fromPlatformCreationParams( PlatformNavigationDelegateCreationParams params, { FutureOr Function(NavigationRequest request)? diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart index d632d1e95231..a112f1522579 100644 --- a/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart +++ b/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart @@ -10,12 +10,41 @@ import 'package:flutter/material.dart'; import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart'; import 'navigation_delegate.dart'; +import 'webview_widget.dart'; /// Controls a WebView provided by the host platform. /// /// Pass this to a [WebViewWidget] to display the WebView. +/// +/// A [WebViewController] can only be used by a single [WebViewWidget] at a +/// time. +/// +/// ## Platform-Specific Features +/// This class contains an underlying implementation provided by the current +/// platform. Once a platform implementation is imported, the examples below +/// can be followed to use features provided by a platform's implementation. +/// +/// {@macro webview_flutter.WebViewController.fromPlatformCreationParams} +/// +/// Below is an example of accessing the platform-specific implementation for +/// iOS and Android: +/// +/// ```dart +/// final WebViewController webViewController = WebViewController(); +/// +/// if (WebViewPlatform.instance is WebKitWebViewPlatform) { +/// final WebKitWebViewController webKitController = +/// webViewController.platform as WebKitWebViewController; +/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { +/// final AndroidWebViewController androidController = +/// webViewController.platform as AndroidWebViewController; +/// } +/// ``` class WebViewController { /// Constructs a [WebViewController]. + /// + /// See [WebViewController.fromPlatformCreationParams] for setting parameters + /// for a specific platform. WebViewController() : this.fromPlatformCreationParams( const PlatformWebViewControllerCreationParams(), @@ -23,6 +52,33 @@ class WebViewController { /// Constructs a [WebViewController] from creation params for a specific /// platform. + /// + /// {@template webview_flutter.WebViewCookieManager.fromPlatformCreationParams} + /// Below is an example of setting platform-specific creation parameters for + /// iOS and Android: + /// + /// ```dart + /// PlatformWebViewControllerCreationParams params = + /// const PlatformWebViewControllerCreationParams(); + /// + /// if (WebViewPlatform.instance is WebKitWebViewPlatform) { + /// params = WebKitWebViewControllerCreationParams + /// .fromPlatformWebViewControllerCreationParams( + /// params, + /// ); + /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { + /// params = AndroidWebViewControllerCreationParams + /// .fromPlatformWebViewControllerCreationParams( + /// params, + /// ); + /// } + /// + /// final WebViewController webViewController = + /// WebViewController.fromPlatformCreationParams( + /// params, + /// ); + /// ``` + /// {@endtemplate} WebViewController.fromPlatformCreationParams( PlatformWebViewControllerCreationParams params, ) : this.fromPlatform(PlatformWebViewController(params)); diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart index bffa1b5a71d2..353d7554fcb2 100644 --- a/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart +++ b/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart @@ -5,8 +5,33 @@ import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart'; /// Manages cookies pertaining to all WebViews. +/// +/// ## Platform-Specific Features +/// This class contains an underlying implementation provided by the current +/// platform. Once a platform implementation is imported, the examples below +/// can be followed to use features provided by a platform's implementation. +/// +/// {@macro webview_flutter.WebViewCookieManager.fromPlatformCreationParams} +/// +/// Below is an example of accessing the platform-specific implementation for +/// iOS and Android: +/// +/// ```dart +/// final WebViewCookieManager cookieManager = WebViewCookieManager(); +/// +/// if (WebViewPlatform.instance is WebKitWebViewPlatform) { +/// final WebKitWebViewCookieManager webKitManager = +/// cookieManager.platform as WebKitWebViewCookieManager; +/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { +/// final AndroidWebViewCookieManager androidManager = +/// cookieManager.platform as AndroidWebViewCookieManager; +/// } +/// ``` class WebViewCookieManager { /// Constructs a [WebViewCookieManager]. + /// + /// See [WebViewCookieManager.fromPlatformCreationParams] for setting + /// parameters for a specific platform. WebViewCookieManager() : this.fromPlatformCreationParams( const PlatformWebViewCookieManagerCreationParams(), @@ -14,6 +39,33 @@ class WebViewCookieManager { /// Constructs a [WebViewCookieManager] from creation params for a specific /// platform. + /// + /// {@template webview_flutter.WebViewCookieManager.fromPlatformCreationParams} + /// Below is an example of setting platform-specific creation parameters for + /// iOS and Android: + /// + /// ```dart + /// PlatformWebViewCookieManagerCreationParams params = + /// const PlatformWebViewCookieManagerCreationParams(); + /// + /// if (WebViewPlatform.instance is WebKitWebViewPlatform) { + /// params = WebKitWebViewCookieManagerCreationParams + /// .fromPlatformWebViewCookieManagerCreationParams( + /// params, + /// ); + /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { + /// params = AndroidWebViewCookieManagerCreationParams + /// .fromPlatformWebViewCookieManagerCreationParams( + /// params, + /// ); + /// } + /// + /// final WebViewCookieManager webViewCookieManager = + /// WebViewCookieManager.fromPlatformCreationParams( + /// params, + /// ); + /// ``` + /// {@endtemplate} WebViewCookieManager.fromPlatformCreationParams( PlatformWebViewCookieManagerCreationParams params, ) : this.fromPlatform(PlatformWebViewCookieManager(params)); diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart index b3180115c801..440d0f6654ec 100644 --- a/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart +++ b/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart @@ -10,8 +10,35 @@ import 'package:webview_flutter_platform_interface/webview_flutter_platform_inte import 'webview_controller.dart'; /// Displays a native WebView as a Widget. +/// +/// ## Platform-Specific Features +/// This class contains an underlying implementation provided by the current +/// platform. Once a platform implementation is imported, the examples below +/// can be followed to use features provided by a platform's implementation. +/// +/// {@macro webview_flutter.WebViewWidget.fromPlatformCreationParams} +/// +/// Below is an example of accessing the platform-specific implementation for +/// iOS and Android: +/// +/// ```dart +/// final WebViewController controller = WebViewController(); +/// +/// final WebViewWidget webViewWidget = WebViewWidget(controller: controller); +/// +/// if (WebViewPlatform.instance is WebKitWebViewPlatform) { +/// final WebKitWebViewWidget webKitWidget = +/// webViewWidget.platform as WebKitWebViewWidget; +/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { +/// final AndroidWebViewWidget androidWidget = +/// webViewWidget.platform as AndroidWebViewWidget; +/// } +/// ``` class WebViewWidget extends StatelessWidget { /// Constructs a [WebViewWidget]. + /// + /// See [WebViewWidget.fromPlatformCreationParams] for setting parameters for + /// a specific platform. WebViewWidget({ Key? key, required WebViewController controller, @@ -27,8 +54,40 @@ class WebViewWidget extends StatelessWidget { ), ); - /// Constructs a [WebViewWidget] from creation params for a specific - /// platform. + /// Constructs a [WebViewWidget] from creation params for a specific platform. + /// + /// {@template webview_flutter.WebViewWidget.fromPlatformCreationParams} + /// Below is an example of setting platform-specific creation parameters for + /// iOS and Android: + /// + /// ```dart + /// final WebViewController controller = WebViewController(); + /// + /// PlatformWebViewWidgetCreationParams params = + /// PlatformWebViewWidgetCreationParams( + /// controller: controller.platform, + /// layoutDirection: TextDirection.ltr, + /// gestureRecognizers: const >{}, + /// ); + /// + /// if (WebViewPlatform.instance is WebKitWebViewPlatform) { + /// params = WebKitWebViewWidgetCreationParams + /// .fromPlatformWebViewWidgetCreationParams( + /// params, + /// ); + /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) { + /// params = AndroidWebViewWidgetCreationParams + /// .fromPlatformWebViewWidgetCreationParams( + /// params, + /// ); + /// } + /// + /// final WebViewWidget webViewWidget = + /// WebViewWidget.fromPlatformCreationParams( + /// params: params, + /// ); + /// ``` + /// {@endtemplate} WebViewWidget.fromPlatformCreationParams({ Key? key, required PlatformWebViewWidgetCreationParams params, diff --git a/packages/webview_flutter/webview_flutter/pubspec.yaml b/packages/webview_flutter/webview_flutter/pubspec.yaml index a494f9e9276c..5cef1a731739 100644 --- a/packages/webview_flutter/webview_flutter/pubspec.yaml +++ b/packages/webview_flutter/webview_flutter/pubspec.yaml @@ -2,7 +2,7 @@ name: webview_flutter description: A Flutter plugin that provides a WebView widget on Android and iOS. repository: https://github.com/flutter/plugins/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.0.3 +version: 4.0.4 environment: sdk: ">=2.17.0 <3.0.0"