本頁面由 Cloud Translation API 翻譯而成。

將 WebView 加入 Flutter 應用程式

1. 簡介

上次更新時間：2021 年 10 月 19 日

您可以使用 WebView Flutter 外掛程式，在 Android 或 iOS Flutter 應用程式中加入 WebView 小工具。在 iOS 上，WebView 小工具是由 WKWebView 支援，而在 Android 上，WebView 小工具是由 WebView 支援。外掛程式可以在網頁檢視畫面中算繪 Flutter 小工具。舉例來說，您可以在網頁檢視畫面中算繪下拉式選單。

建構項目

在本程式碼研究室中，您將使用 Flutter SDK 逐步建構行動應用程式，並加入 WebView。您的應用程式將會：

在 WebView 中顯示網頁內容
顯示堆疊在 WebView 上方的 Flutter 小工具
對網頁載入進度事件做出反應
透過 WebViewController 控制 WebView
使用 NavigationDelegate 封鎖網站
評估 JavaScript 運算式
使用 JavascriptChannels 處理 JavaScript 的回呼
設定、移除、新增或顯示 Cookie
從素材資源、檔案或包含 HTML 的字串載入及顯示 HTML

iPhone 模擬器正在執行 Flutter 應用程式，內嵌的 WebView 顯示 Flutter.dev 首頁

Android 模擬器正在執行 Flutter 應用程式，內嵌的網頁畫面顯示 Flutter.dev 首頁

課程內容

在本程式碼研究室中，您將瞭解如何以各種方式使用 webview_flutter 外掛程式，包括：

如何設定 webview_flutter 外掛程式
如何監聽網頁載入進度事件
如何控制頁面導覽
如何命令 WebView 在記錄中前後移動
如何評估 JavaScript，包括使用傳回的結果
如何註冊回呼，從 JavaScript 呼叫 Dart 程式碼
如何管理 Cookie
如何從素材資源、檔案或包含 HTML 的字串載入及顯示 HTML 網頁

軟硬體需求

Android Studio 4.1 以上版本 (適用於 Android 開發)
Xcode 12 以上版本 (適用於 iOS 開發)
Flutter SDK
程式碼編輯器，例如 Android Studio 或 Visual Studio Code。

2. 設定 Flutter 開發環境

您需要兩項軟體才能完成本實驗室活動：Flutter SDK 和編輯器。

您可以使用下列任一裝置執行程式碼研究室：

連線至電腦並設為開發人員模式的實體 Android 或 iOS 裝置。
iOS 模擬器 (需要安裝 Xcode 工具)。
Android Emulator (需在 Android Studio 中設定)。

3. 開始使用

開始使用 Flutter

建立新的 Flutter 專案有多種方法，Android Studio 和 Visual Studio Code 都提供這項工作的工具。您可以按照連結的程序建立專案，也可以在方便的指令列終端機中執行下列指令。

$ flutter create --platforms=android,ios webview_in_flutter
Creating project webview_in_flutter...
Resolving dependencies in `webview_in_flutter`...
Downloading packages...
Got dependencies in `webview_in_flutter`.
Wrote 74 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd webview_in_flutter
  $ flutter run

Your application code is in webview_in_flutter/lib/main.dart.

將 WebView Flutter 外掛程式新增為依附元件

如要為 Flutter 應用程式新增其他功能，最好使用 Pub 套件。在本程式碼研究室中，您將在專案中新增 webview_flutter 外掛程式。在終端機中執行下列指令。

$ cd webview_in_flutter
$ flutter pub add webview_flutter
Resolving dependencies...
Downloading packages...
  collection 1.18.0 (1.19.0 available)
  leak_tracker 10.0.5 (10.0.7 available)
  leak_tracker_flutter_testing 3.0.5 (3.0.7 available)
  material_color_utilities 0.11.1 (0.12.0 available)
+ plugin_platform_interface 2.1.8
  string_scanner 1.2.0 (1.3.0 available)
  test_api 0.7.2 (0.7.3 available)
+ webview_flutter 4.9.0
+ webview_flutter_android 3.16.7
+ webview_flutter_platform_interface 2.10.0
+ webview_flutter_wkwebview 3.15.0
Changed 5 dependencies!
6 packages have newer versions incompatible with dependency constraints.
Try `flutter pub outdated` for more information.

檢查 pubspec.yaml 時，您會發現依附元件區段中有一行 webview_flutter 外掛程式。

設定 Android minSDK

如要在 Android 上使用 webview_flutter 外掛程式，請將 minSDK 設為 20。按照下列方式修改 android/app/build.gradle 檔案：

android/app/build.gradle

android {
    //...

    defaultConfig {
        applicationId = "com.example.webview_in_flutter"
        minSdk = 20                                         // Modify this line
        targetSdk = flutter.targetSdkVersion
        versionCode = flutterVersionCode.toInteger()
        versionName = flutterVersionName
    }

4. 在 Flutter 應用程式中新增 WebView 小工具

在這個步驟中，您要在應用程式中新增 WebView。WebView 是代管的內建檢視區塊，應用程式開發人員可選擇在應用程式中代管這些內建檢視區塊的方式。在 Android 上，您可以選擇使用 Android 的預設選項「虛擬螢幕」，或是「混合組合」。不過，iOS 一律使用混合合成。

如要深入瞭解虛擬螢幕和混合組合之間的差異，請參閱「在 Flutter 應用程式中透過平台檢視區塊代管原生 Android 和 iOS 檢視區塊」一文。

在畫面上放置 WebView

將 lib/main.dart 改成以下內容：

lib/main.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

void main() {
  runApp(
    MaterialApp(
      theme: ThemeData(useMaterial3: true),
      home: const WebViewApp(),
    ),
  );
}

class WebViewApp extends StatefulWidget {
  const WebViewApp({super.key});

  @override
  State<WebViewApp> createState() => _WebViewAppState();
}

class _WebViewAppState extends State<WebViewApp> {
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..loadRequest(
        Uri.parse('https://flutter.dev'),
      );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter WebView'),
      ),
      body: WebViewWidget(
        controller: controller,
      ),
    );
  }
}

在 iOS 或 Android 上執行這項操作時，裝置會顯示 WebView，做為全出血的瀏覽器視窗，也就是說，瀏覽器會以全螢幕模式顯示在裝置上，且沒有任何形式的邊框或邊界。捲動時，您會發現網頁的某些部分看起來有點奇怪。這是因為 JavaScript 已停用，而正確算繪 flutter.dev 需要 JavaScript。

執行應用程式

在 iOS 或 Android 中執行 Flutter 應用程式，即可看到顯示 flutter.dev 網站的 WebView。您也可以在 Android 模擬器或 iOS 模擬器中執行應用程式。您可以將初始 WebView 網址替換為自己的網站等。

$ flutter run

假設您已執行適當的模擬器或模擬器，或已附加實體裝置，將應用程式編譯並部署至裝置後，您應該會看到類似下列內容：

iPhone 模擬器正在執行 Flutter 應用程式，內嵌的 WebView 顯示 Flutter.dev 首頁

Android 模擬器正在執行 Flutter 應用程式，內嵌的網頁畫面顯示 Flutter.dev 首頁

5. 監聽網頁載入事件

WebView 小工具提供多個網頁載入進度事件，應用程式可以監聽這些事件。在 WebView 網頁載入週期中，系統會觸發三種不同的網頁載入事件：onPageStarted、onProgress 和 onPageFinished。在這個步驟中，您將實作網頁載入指標。此外，這也會顯示您可以在 WebView 內容區域上算繪 Flutter 內容。

在應用程式中加入網頁載入事件

在 lib/src/web_view_stack.dart 建立新的來源檔案，並填入下列內容：

lib/src/web_view_stack.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class WebViewStack extends StatefulWidget {
  const WebViewStack({super.key});

  @override
  State<WebViewStack> createState() => _WebViewStackState();
}

class _WebViewStackState extends State<WebViewStack> {
  var loadingPercentage = 0;
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..setNavigationDelegate(NavigationDelegate(
        onPageStarted: (url) {
          setState(() {
            loadingPercentage = 0;
          });
        },
        onProgress: (progress) {
          setState(() {
            loadingPercentage = progress;
          });
        },
        onPageFinished: (url) {
          setState(() {
            loadingPercentage = 100;
          });
        },
      ))
      ..loadRequest(
        Uri.parse('https://flutter.dev'),
      );
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        WebViewWidget(
          controller: controller,
        ),
        if (loadingPercentage < 100)
          LinearProgressIndicator(
            value: loadingPercentage / 100.0,
          ),
      ],
    );
  }
}

這段程式碼已將 WebView 小工具包裝在 Stack 中，當網頁載入百分比小於 100% 時，會以 LinearProgressIndicator 覆蓋 WebView。由於這涉及隨時間變更的程式狀態，因此您已將此狀態儲存在與 StatefulWidget 相關聯的 State 類別中。

如要使用這個新的 WebViewStack 小工具，請按照下列方式修改 lib/main.dart：

lib/main.dart

import 'package:flutter/material.dart';

import 'src/web_view_stack.dart';

void main() {
  runApp(
    MaterialApp(
      theme: ThemeData(useMaterial3: true),
      home: const WebViewApp(),
    ),
  );
}

class WebViewApp extends StatefulWidget {
  const WebViewApp({super.key});

  @override
  State<WebViewApp> createState() => _WebViewAppState();
}

class _WebViewAppState extends State<WebViewApp> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter WebView'),
      ),
      body: const WebViewStack(),
    );
  }
}

執行應用程式時，視網路狀況而定，以及瀏覽器是否已快取您要前往的網頁，您會在 WebView 內容區域上方看到網頁載入指標。

6. 使用 WebViewController

WebView 小工具可透過 WebViewController 進行程式輔助控制。建構 WebView 小工具後，系統會透過回呼提供這個控制器。由於這個控制器是異步提供，因此非常適合做為 Dart 的異步 Completer<T> 類別。

請按照下列方式更新 lib/src/web_view_stack.dart：

lib/src/web_view_stack.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class WebViewStack extends StatefulWidget {
  const WebViewStack({required this.controller, super.key}); // MODIFY

  final WebViewController controller;                        // ADD

  @override
  State<WebViewStack> createState() => _WebViewStackState();
}

class _WebViewStackState extends State<WebViewStack> {
  var loadingPercentage = 0;
  // REMOVE the controller that was here

  @override
  void initState() {
    super.initState();
    // Modify from here...
    widget.controller.setNavigationDelegate(
      NavigationDelegate(
        onPageStarted: (url) {
          setState(() {
            loadingPercentage = 0;
          });
        },
        onProgress: (progress) {
          setState(() {
            loadingPercentage = progress;
          });
        },
        onPageFinished: (url) {
          setState(() {
            loadingPercentage = 100;
          });
        },
      ),
    );
    // ...to here.
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        WebViewWidget(
          controller: widget.controller,                     // MODIFY
        ),
        if (loadingPercentage < 100)
          LinearProgressIndicator(
            value: loadingPercentage / 100.0,
          ),
      ],
    );
  }
}

WebViewStack 小工具現在會使用周圍小工具中建立的控制器。這樣一來，應用程式的其他部分就能共用 WebViewWidget 的控制器。

擁有可運作的 WebView 是一回事，但能夠在頁面記錄中前後瀏覽及重新載入頁面，會是一組實用的附加功能。幸好，您可以使用 WebViewController 將這項功能新增至應用程式。

在 lib/src/navigation_controls.dart 建立新的來源檔案，並填入下列內容：

lib/src/navigation_controls.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class NavigationControls extends StatelessWidget {
  const NavigationControls({required this.controller, super.key});

  final WebViewController controller;

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        IconButton(
          icon: const Icon(Icons.arrow_back_ios),
          onPressed: () async {
            final messenger = ScaffoldMessenger.of(context);
            if (await controller.canGoBack()) {
              await controller.goBack();
            } else {
              messenger.showSnackBar(
                const SnackBar(content: Text('No back history item')),
              );
              return;
            }
          },
        ),
        IconButton(
          icon: const Icon(Icons.arrow_forward_ios),
          onPressed: () async {
            final messenger = ScaffoldMessenger.of(context);
            if (await controller.canGoForward()) {
              await controller.goForward();
            } else {
              messenger.showSnackBar(
                const SnackBar(content: Text('No forward history item')),
              );
              return;
            }
          },
        ),
        IconButton(
          icon: const Icon(Icons.replay),
          onPressed: () {
            controller.reload();
          },
        ),
      ],
    );
  }
}

這個小工具會使用建構時與其共用的 WebViewController，讓使用者透過一系列 IconButton 控制 WebView。

現在您已取得更新後的 WebViewStack 和新製作的 NavigationControls，接下來請將所有內容整合到更新後的 WebViewApp。我們將在此建構共用 WebViewController。由於 WebViewApp 位於這個應用程式的「小工具」樹狀結構頂端附近，因此在這個層級建立是合理的做法。

按照下列方式更新 lib/main.dart 檔案：

lib/main.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';  // ADD

import 'src/navigation_controls.dart';                  // ADD
import 'src/web_view_stack.dart';

void main() {
  runApp(
    MaterialApp(
      theme: ThemeData(useMaterial3: true),
      home: const WebViewApp(),
    ),
  );
}

class WebViewApp extends StatefulWidget {
  const WebViewApp({super.key});

  @override
  State<WebViewApp> createState() => _WebViewAppState();
}

class _WebViewAppState extends State<WebViewApp> {
  // Add from here...
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();
    controller = WebViewController()
      ..loadRequest(
        Uri.parse('https://flutter.dev'),
      );
  }
  // ...to here.

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter WebView'),
        // Add from here...
        actions: [
          NavigationControls(controller: controller),
        ],
        // ...to here.
      ),
      body: WebViewStack(controller: controller),       // MODIFY
    );
  }
}

執行應用程式後，應該會顯示含有控制項的網頁：

iPhone 模擬器執行 Flutter 應用程式，內嵌的 WebView 顯示 Flutter.dev 首頁，並提供上一頁、下一頁和重新載入頁面控制項

Android 模擬器正在執行 Flutter 應用程式，內嵌網頁畫面顯示 Flutter.dev 首頁，並提供上一頁、下一頁和重新載入頁面控制項

7. 使用 NavigationDelegate 追蹤導覽作業

WebView 會為應用程式提供 NavigationDelegate,，讓應用程式追蹤及控制 WebView 小工具的網頁瀏覽作業。當 WebView, 啟動導覽時 (例如使用者點選連結)，系統會呼叫 NavigationDelegate。NavigationDelegate 回呼可用來控制 WebView 是否繼續導覽。

註冊自訂 NavigationDelegate

在這個步驟中，您將註冊 NavigationDelegate 回呼，以封鎖前往 YouTube.com 的導覽。請注意，這個簡化的實作方式也會封鎖內嵌的 YouTube 內容，這類內容會出現在各種 Flutter API 說明文件頁面中。

將 lib/src/web_view_stack.dart 更新為下列內容：

lib/src/web_view_stack.dart

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class WebViewStack extends StatefulWidget {
  const WebViewStack({required this.controller, super.key});

  final WebViewController controller;

  @override
  State<WebViewStack> createState() => _WebViewStackState();
}

class _WebViewStackState extends State<WebViewStack> {
  var loadingPercentage = 0;

  @override
  void initState() {
    super.initState();
    widget.controller.setNavigationDelegate(
      NavigationDelegate(
        onPageStarted: (url) {
          setState(() {
            loadingPercentage = 0;
          });
        },
        onProgress: (progress) {
          setState(() {
            loadingPercentage = progress;
          });
        },
        onPageFinished: (url) {
          setState(() {
            loadingPercentage = 100;
          });
        },
        // Add from here...
        onNavigationRequest: (navigation) {
          final host = Uri.parse(navigation.url).host;
          if (host.contains('youtube.com')) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(
                  'Blocking navigation to $host',
                ),
              ),
            );
            return NavigationDecision.prevent;
          }
          return NavigationDecision.navigate;
        },
        // ...to here.
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        WebViewWidget(
          controller: widget.controller,
        ),
        if (loadingPercentage < 100)
          LinearProgressIndicator(
            value: loadingPercentage / 100.0,
          ),
      ],
    );
  }
}

在下一個步驟中，您將新增選單項目，以便使用 WebViewController 類別測試 NavigationDelegate。讀者可自行練習擴增回呼的邏輯，只封鎖前往 YouTube.com 的全頁面導覽，但仍允許 API 說明文件中的內嵌 YouTube 內容。

8. 在 AppBar 中新增選單按鈕

在接下來的幾個步驟中，您將在 AppBar 小工具中製作選單按鈕，用於評估 JavaScript、叫用 JavaScript 管道及管理 Cookie。總而言之，這確實是實用的選單。

在 lib/src/menu.dart 建立新的來源檔案，並填入下列內容：

將 WebView 加入 Flutter 應用程式

1. 簡介

建構項目

課程內容

軟硬體需求

2. 設定 Flutter 開發環境

3. 開始使用

開始使用 Flutter

將 WebView Flutter 外掛程式新增為依附元件

設定 Android minSDK

4. 在 Flutter 應用程式中新增 WebView 小工具

在畫面上放置 WebView

執行應用程式

5. 監聽網頁載入事件

在應用程式中加入網頁載入事件

6. 使用 WebViewController

從 WebView 小工具存取 WebViewController

製作導覽控制選項

在 AppBar 中新增導覽控制項

7. 使用 NavigationDelegate 追蹤導覽作業

註冊自訂 NavigationDelegate

8. 在 AppBar 中新增選單按鈕

9. 評估 JavaScript

10. 使用 JavaScript 頻道

11. 管理 Cookie

取得所有 Cookie 的清單

清除所有 Cookie

新增 Cookie

使用 CookieManager 設定 Cookie

移除 Cookie

新增 CookieManager 選單項目

練習使用 CookieManager

12. 在 WebView 中載入 Flutter 資產、檔案和 HTML 字串

載入 Flutter 資產

載入本機檔案

載入 HTML 字串

新增菜單品項

13. 大功告成！