تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إضافة WebView إلى تطبيق Flutter

1. مقدمة

تاريخ آخر تعديل: 19-10-2021

باستخدام مكوّن WebView الإضافي في Flutter، يمكنك إضافة أداة WebView إلى تطبيق Android أو iOS Flutter. في نظام التشغيل iOS، تستند أداة WebView إلى WKWebView، بينما تستند أداة WebView في نظام التشغيل Android إلى WebView. يمكن أن تعرض الإضافة عناصر واجهة مستخدم Flutter فوق عرض الويب. على سبيل المثال، يمكن عرض قائمة منسدلة فوق عرض الويب.

ما ستنشئه

في هذا الدرس التطبيقي، ستنشئ تطبيقًا على الأجهزة الجوّالة خطوة بخطوة يتضمّن WebView باستخدام حزمة تطوير البرامج (SDK) من Flutter. سيتم إجراء ما يلي في تطبيقك:

عرض محتوى الويب في WebView
عرض تطبيقات Flutter المصغّرة مكدّسة فوق WebView
الاستجابة لأحداث تقدّم تحميل الصفحة
التحكّم في WebView من خلال WebViewController
حظر المواقع الإلكترونية باستخدام NavigationDelegate
تقييم عبارات JavaScript
التعامل مع عمليات رد الاتصال من JavaScript باستخدام JavascriptChannels
ضبط ملفات تعريف الارتباط أو إزالتها أو إضافتها أو عرضها
تحميل وعرض HTML من مواد العرض أو الملفات أو السلاسل التي تحتوي على HTML

محاكي iPhone يعرض تطبيق Flutter يتضمّن عرضًا مضمّنًا لصفحة Flutter.dev الرئيسية

محاكي Android يشغّل تطبيق Flutter مع عرض مضمّن لصفحة Flutter.dev الرئيسية

المُعطيات

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام webview_flutter الإضافة بطرق متنوعة، بما في ذلك:

كيفية ضبط إعدادات المكوّن الإضافي webview_flutter
كيفية الاستماع إلى أحداث تقدّم تحميل الصفحة
كيفية التحكّم في التنقّل بين الصفحات
كيفية توجيه WebView للانتقال إلى الخلف والأمام في سجلّه
كيفية تقييم JavaScript، بما في ذلك استخدام النتائج التي تم إرجاعها
كيفية تسجيل عمليات رد الاتصال لاستدعاء رمز Dart من JavaScript
كيفية إدارة ملفات تعريف الارتباط
كيفية تحميل صفحات HTML وعرضها من مواد العرض أو الملفات أو السلسلة التي تحتوي على HTML

المتطلبات

‫Android Studio 4.1 أو إصدار أحدث (لتطوير تطبيقات Android)
‫Xcode 12 أو إصدار أحدث (لتطوير تطبيقات iOS)
حزمة تطوير البرامج (SDK) في Flutter
محرِّر رموز، مثل استوديو Android أو Visual Studio Code

2. إعداد بيئة تطوير Flutter

يجب توفّر برنامجَين لإكمال هذا الدرس التطبيقي، وهما حزمة تطوير البرامج (SDK) الخاصة بإطار عمل Flutter ومحرِّر.

يمكنك تشغيل الدرس العملي باستخدام أيّ من الأجهزة التالية:

جهاز Android أو iOS فعلي متصل بالكمبيوتر وتم ضبطه على وضع "المطوّر"
محاكي iOS (يتطلّب تثبيت أدوات Xcode)
محاكي Android (يتطلّب الإعداد في "استوديو Android")

3- الخطوات الأولى

بدء استخدام Flutter

تتوفّر طرق متنوعة لإنشاء مشروع Flutter جديد، إذ يوفّر كلّ من "استوديو Android" و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 الإضافي.

ضبط minSDK لنظام التشغيل Android

لاستخدام المكوّن الإضافي webview_flutter على Android، عليك ضبط 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. إضافة أداة WebView إلى تطبيق Flutter

في هذه الخطوة، ستضيف WebView إلى تطبيقك. إنّ WebViews هي طرق عرض مضمّنة مستضافة، ويمكنك كمطوّر تطبيقات اختيار طريقة استضافة طرق العرض المضمّنة هذه في تطبيقك. على نظام التشغيل Android، يمكنك الاختيار بين "الشاشات الافتراضية"، وهي الإعداد التلقائي لنظام التشغيل Android، و"التركيب المختلط". ومع ذلك، يستخدم نظام التشغيل iOS دائمًا التركيب المختلط.

للحصول على مناقشة مفصّلة حول الاختلافات بين "الشاشات الافتراضية" و"التركيب المختلط"، يمكنك الاطّلاع على المستندات حول استضافة عروض Android وiOS الأصلية في تطبيق Flutter باستخدام "عروض المنصات" .

وضع 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.

تشغيل التطبيق

شغِّل تطبيق Flutter على iOS أو Android لعرض Webview الذي يعرض الموقع الإلكتروني flutter.dev. يمكنك بدلاً من ذلك تشغيل التطبيق في محاكي Android أو محاكي iOS. يمكنك استبدال عنوان URL الأوّلي لـ WebView بعنوان موقعك الإلكتروني مثلاً.

$ flutter run

بافتراض أنّ لديك المحاكي المناسب أو جهازًا فعليًا متصلاً، بعد تجميع التطبيق ونشره على جهازك، من المفترض أن يظهر لك ما يلي:

محاكي iPhone يعرض تطبيق Flutter يتضمّن عرضًا مضمّنًا لصفحة Flutter.dev الرئيسية

محاكي Android يشغّل تطبيق Flutter مع عرض مضمّن لصفحة Flutter.dev الرئيسية

5- الاستماع إلى أحداث تحميل الصفحة

يوفّر التطبيق المصغّر WebView العديد من أحداث تقدّم تحميل الصفحة التي يمكن لتطبيقك الاستماع إليها. أثناء دورة تحميل الصفحة WebView، يتم تنشيط ثلاثة أحداث مختلفة لتحميل الصفحة، وهي: onPageStarted وonProgress وonPageFinished. في هذه الخطوة، عليك تنفيذ مؤشر تحميل الصفحة. بالإضافة إلى ذلك، سيُظهر هذا أنّ بإمكانك عرض محتوى Flutter على مساحة المحتوى WebView.

إضافة أحداث تحميل الصفحة إلى تطبيقك

أنشئ ملف مصدر جديدًا في 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، ويتم بشكل مشروط عرض WebView مع LinearProgressIndicator عندما تكون النسبة المئوية لتحميل الصفحة أقل من %100. بما أنّ ذلك يتضمّن حالة البرنامج التي تتغيّر بمرور الوقت، عليك تخزين هذه الحالة في فئة State مرتبطة بـ StatefulWidget.

للاستفادة من التطبيق المصغّر الجديد 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 من خلال دالة ردّ الاتصال. إنّ الطبيعة غير المتزامنة لمدى توفّر وحدة التحكّم هذه تجعلها مرشّحًا رئيسيًا لفئة Completer<T> غير المتزامنة في Dart.

عدِّل 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 الذي تمت مشاركته معه في وقت الإنشاء لتمكين المستخدم من التحكّم في WebView من خلال سلسلة من IconButton.

بعد تعديل 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 مع عرض ويب مضمّن يعرض الصفحة الرئيسية لموقع 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,
          ),
      ],
    );
  }
}

في الخطوة التالية، ستضيف عنصر قائمة لتفعيل اختبار NavigationDelegate باستخدام الفئة WebViewController. يُترك للقارئ مهمة تحسين منطق معاودة الاتصال لحظر التنقّل في الصفحة الكاملة إلى YouTube.com فقط، مع السماح بعرض محتوى YouTube المضمّن في مستندات واجهة برمجة التطبيقات.

‫8. إضافة زر قائمة إلى شريط التطبيق

خلال الخطوات القليلة التالية، ستصمّم زر قائمة في أداة AppBar تُستخدَم لتقييم JavaScript واستدعاء قنوات JavaScript وإدارة ملفات تعريف الارتباط. بشكل عام، إنّها قائمة مفيدة حقًا.

أنشئ ملف مصدر جديدًا في lib/src/menu.dart واملأه بما يلي:

إضافة WebView إلى تطبيق Flutter

1. مقدمة

ما ستنشئه

المُعطيات

المتطلبات

2. إعداد بيئة تطوير Flutter

3- الخطوات الأولى

بدء استخدام Flutter

إضافة مكوّن WebView الإضافي في Flutter كعنصر تابع

ضبط minSDK لنظام التشغيل Android

4. إضافة أداة WebView إلى تطبيق Flutter

وضع Webview على الشاشة

تشغيل التطبيق

5- الاستماع إلى أحداث تحميل الصفحة

إضافة أحداث تحميل الصفحة إلى تطبيقك

6. التعامل مع WebViewController

الوصول إلى WebViewController من أداة WebView

تصميم عناصر التحكّم في التنقّل

إضافة عناصر التحكّم في التنقّل إلى شريط التطبيقات

7. تتبُّع التنقّل باستخدام NavigationDelegate

تسجيل NavigationDelegate مخصّص

‫8. إضافة زر قائمة إلى شريط التطبيق

9- تقييم JavaScript

10. العمل مع قنوات JavaScript

11. إدارة ملفات تعريف الارتباط

الحصول على قائمة بجميع ملفات تعريف الارتباط

محو جميع ملفات تعريف الارتباط

إضافة ملف تعريف ارتباط

إعداد ملف تعريف ارتباط باستخدام CookieManager

إزالة ملف تعريف ارتباط

إضافة عناصر قائمة CookieManager

استخدام CookieManager

12. تحميل مواد عرض Flutter وملفاتها وسلاسل HTML في WebView

تحميل مادة عرض Flutter

تحميل ملف محلي

تحميل سلسلة HTML

إضافة عناصر القائمة

13. أكملت الخطوات بنجاح