[webview_flutter] Update webview platform interface with new methods for running JavaScript. (#4401)

Author: BeMacized

packages/webview_flutter/webview_flutter_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.2.0
+
+* Added `runJavascript` and `runJavascriptReturningResult` interface methods to supersede `evaluateJavascript`.
+
 ## 1.1.0
 
 * Add `zoomEnabled` functionality to `WebSettings`.

packages/webview_flutter/webview_flutter_platform_interface/lib/src/method_channel/webview_method_channel.dart

@@ -123,9 +123,21 @@ class MethodChannelWebViewPlatform implements WebViewPlatformController {
   }
 
   @override
-  Future<String> evaluateJavascript(String javascriptString) {
+  Future<String> evaluateJavascript(String javascript) {
     return _channel
-        .invokeMethod<String>('evaluateJavascript', javascriptString)
+        .invokeMethod<String>('evaluateJavascript', javascript)
+        .then((result) => result!);
+  }
+
+  @override
+  Future<void> runJavascript(String javascript) async {
+    await _channel.invokeMethod<String>('runJavascript', javascript);
+  }
+
+  @override
+  Future<String> runJavascriptReturningResult(String javascript) {
+    return _channel
+        .invokeMethod<String>('runJavascriptReturningResult', javascript)
         .then((result) => result!);
   }
 

packages/webview_flutter/webview_flutter_platform_interface/lib/src/platform_interface/webview_platform_controller.dart

@@ -106,12 +106,30 @@ abstract class WebViewPlatformController {
   /// Evaluates a JavaScript expression in the context of the current page.
   ///
   /// The Future completes with an error if a JavaScript error occurred, or if the type of the
-  /// evaluated expression is not supported(e.g on iOS not all non primitive type can be evaluated).
-  Future<String> evaluateJavascript(String javascriptString) {
+  /// evaluated expression is not supported (e.g on iOS not all non-primitive types can be evaluated).
+  Future<String> evaluateJavascript(String javascript) {
     throw UnimplementedError(
         "WebView evaluateJavascript is not implemented on the current platform");
   }
 
+  /// Runs the given JavaScript in the context of the current page.
+  ///
+  /// The Future completes with an error if a JavaScript error occurred.
+  Future<void> runJavascript(String javascript) {
+    throw UnimplementedError(
+        "WebView runJavascript is not implemented on the current platform");
+  }
+
+  /// Runs the given JavaScript in the context of the current page, and returns the result.
+  ///
+  /// The Future completes with an error if a JavaScript error occurred, or if the
+  /// type the given expression evaluates to is unsupported. Unsupported values include
+  /// certain non-primitive types on iOS, as well as `undefined` or `null` on iOS 14+.
+  Future<String> runJavascriptReturningResult(String javascript) {
+    throw UnimplementedError(
+        "WebView runJavascriptReturningResult is not implemented on the current platform");
+  }
+
   /// Adds new JavaScript channels to the set of enabled channels.
   ///
   /// For each value in this list the platform's webview should make sure that a corresponding
@@ -130,7 +148,7 @@ abstract class WebViewPlatformController {
 
   /// Removes JavaScript channel names from the set of enabled channels.
   ///
-  /// This disables channels that were previously enabled by [addJavaScriptChannels] or through
+  /// This disables channels that were previously enabled by [addJavascriptChannels] or through
   /// [CreationParams.javascriptChannelNames].
   Future<void> removeJavascriptChannels(Set<String> javascriptChannelNames) {
     throw UnimplementedError(

packages/webview_flutter/webview_flutter_platform_interface/lib/src/types/javascript_channel.dart

@@ -4,14 +4,14 @@
 
 import 'javascript_message.dart';
 
-/// Callback type for handling messages sent from Javascript running in a web view.
+/// Callback type for handling messages sent from JavaScript running in a web view.
 typedef void JavascriptMessageHandler(JavascriptMessage message);
 
 final RegExp _validChannelNames = RegExp('^[a-zA-Z_][a-zA-Z0-9_]*\$');
 
 /// A named channel for receiving messaged from JavaScript code running inside a web view.
 class JavascriptChannel {
-  /// Constructs a Javascript channel.
+  /// Constructs a JavaScript channel.
   ///
   /// The parameters `name` and `onMessageReceived` must not be null.
   JavascriptChannel({
@@ -24,7 +24,7 @@ class JavascriptChannel {
   /// The channel's name.
   ///
   /// Passing this channel object as part of a [WebView.javascriptChannels] adds a channel object to
-  /// the Javascript window object's property named `name`.
+  /// the JavaScript window object's property named `name`.
   ///
   /// The name must start with a letter or underscore(_), followed by any combination of those
   /// characters plus digits.

packages/webview_flutter/webview_flutter_platform_interface/pubspec.yaml

@@ -4,7 +4,7 @@ repository: https://github.com/flutter/plugins/tree/master/packages/webview_flut
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+webview_flutter%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 1.1.0
+version: 1.2.0
 
 environment:
   sdk: ">=2.12.0 <3.0.0"

packages/webview_flutter/webview_flutter_platform_interface/test/src/method_channel/webview_method_channel_test.dart

@@ -30,6 +30,7 @@ void main() {
         case 'canGoBack':
         case 'canGoForward':
           return true;
+        case 'runJavascriptReturningResult':
         case 'evaluateJavascript':
           return methodCall.arguments as String;
         case 'getScrollX':
@@ -266,16 +267,50 @@ void main() {
     test('evaluateJavascript', () async {
       final String evaluateJavascript =
           await webViewPlatform.evaluateJavascript(
-        'This simulates some Javascript code.',
+        'This simulates some JavaScript code.',
       );
 
-      expect('This simulates some Javascript code.', evaluateJavascript);
+      expect('This simulates some JavaScript code.', evaluateJavascript);
       expect(
         log,
         <Matcher>[
           isMethodCall(
             'evaluateJavascript',
-            arguments: 'This simulates some Javascript code.',
+            arguments: 'This simulates some JavaScript code.',
+          ),
+        ],
+      );
+    });
+
+    test('runJavascript', () async {
+      await webViewPlatform.runJavascript(
+        'This simulates some JavaScript code.',
+      );
+
+      expect(
+        log,
+        <Matcher>[
+          isMethodCall(
+            'runJavascript',
+            arguments: 'This simulates some JavaScript code.',
+          ),
+        ],
+      );
+    });
+
+    test('runJavascriptReturningResult', () async {
+      final String evaluateJavascript =
+          await webViewPlatform.runJavascriptReturningResult(
+        'This simulates some JavaScript code.',
+      );
+
+      expect('This simulates some JavaScript code.', evaluateJavascript);
+      expect(
+        log,
+        <Matcher>[
+          isMethodCall(
+            'runJavascriptReturningResult',
+            arguments: 'This simulates some JavaScript code.',
           ),
         ],
       );