إنشاء رابط لصفحة في التطبيق لوجهة

في نظام Android، الرابط لصفحة في التطبيق هو رابط ينقلك مباشرةً إلى وجهة معيّنة داخل تطبيق ما.

يتيح لك مكوّن التنقّل إنشاء نوعَين مختلفَين من الروابط لصفحات في التطبيق: صريح وضمني.

إنشاء رابط صريح لصفحة في التطبيق

الرابط الصريح لصفحة في التطبيق هو مثيل واحد لرابط لصفحة في التطبيق يستخدم رمز PendingIntent لنقل المستخدمين إلى موقع معيّن في تطبيقك. يمكنك مثلاً عرض رابط صريح لصفحة في التطبيق كجزء من إشعار أو تطبيق مصغّر.

عندما يفتح المستخدم تطبيقك من خلال رابط صريح لصفحة في التطبيق، تتم clearing إزالة تسلسل المهام للخلف واستبداله بوجهة الرابط لصفحة في التطبيق. عند دمج الرسومات البيانية، تتم أيضًا إضافة وجهة البدء من كل مستوى من مستويات التداخل إلى الحزمة، أي وجهة البدء من كل عنصر <navigation> في التسلسل الهرمي. وهذا يعني أنّه عندما يضغط المستخدم على زر الرجوع من وجهة رابط لصفحة معيّنة في التطبيق، سينتقل إلى أعلى تسلسل التنقل كما لو كان قد دخل إلى تطبيقك من نقطة الدخول.

يمكنك استخدام فئة NavDeepLinkBuilder لإنشاء PendingIntent، كما هو موضّح في المثال أدناه. يُرجى العلم أنّه إذا لم يكن السياق المقدَّم هو Activity، سيستخدم المُنشئ PackageManager.getLaunchIntentForPackage() كالنشاط التلقائي لبدء التشغيل، إذا كان متاحًا.

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

يُطلق الإجراء NavDeepLinkBuilder تلقائيًا الرابط الصريح لصفحة معيّنة في التطبيق على الإطلاق التلقائي Activity الذي تم الإعلان عنه في بيان تطبيقك. إذا كانNavHost في نشاط آخر، يجب تحديد اسم العنصر عند إنشاء أداة إنشاء الروابط لصفحات في التطبيق:

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

إذا كانت لديك ComponentName، يمكنك إرسالها مباشرةً إلى أداة الإنشاء:

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

إذا كان لديك NavController حالي، يمكنك أيضًا إنشاء رابط لصفحة في التطبيق باستخدام NavController.createDeepLink().

إنشاء رابط ضمني لصفحة في التطبيق

يشير الرابط الضمني لصفحة في التطبيق إلى وجهة معيّنة في التطبيق. عند استدعاء الرابط لصفحة في التطبيق، مثلاً عند نقر المستخدم على رابط، يمكن لنظام التشغيل Android فتح تطبيقك للوصول إلى الوجهة المقابلة.

يمكن مطابقة الروابط لصفحات في التطبيق حسب عنوان URL وإجراءات الأهداف وأنواع MIME. يمكنك تحديد أنواع مطابقة متعددة لرابط واحد لصفحة في التطبيق، ولكن يُرجى العلم أنّ مطابقة وسيطة معرّف الموارد المنتظم (URI) تكون الأولوية أولاً، ويتبعها الإجراء، ثم نوع MIME.

في ما يلي مثال على رابط لصفحة في التطبيق يحتوي على معرّف موارد منتظم (URI) وإجراء ونوع MIME:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

يمكنك أيضًا استخدام "أداة التنقّل" لإنشاء رابط لصفحة في التطبيق ضمني إلى وجهة على النحو التالي:

  1. في علامة التبويب تصميم ضمن "محرر التنقّل"، اختَر الوجهة ل الرابط لصفحة في التطبيق.
  2. انقر على + في قسم الروابط لصفحات في التطبيق ضمن لوحة السمات.

  3. في مربّع الحوار إضافة رابط لصفحة في التطبيق الذي يظهر، أدخِل معلومات رابطك لصفحة في التطبيق.

    ملاحظات:

    • يُفترض أنّ معرّفات الموارد المنتظمة التي لا تتضمّن مخطّطًا هي http أو https. على سبيل المثال، www.google.com يتطابق مع كل من http://www.google.com و https://www.google.com.
    • تتطابق عناصر نائبة مَعلمات المسار التي تكون على شكل {placeholder_name} مع حرف واحد أو أكثر. على سبيل المثال، http://www.example.com/users/{id} يطابق http://www.example.com/users/4. يحاول مكوّن التنقّل تحليل قيم العنصر النائب إلى أنواع مناسبة من خلال مطابقة أسماء العناصر النائبة مع المَعلمات التي تم تحديدها لوجهة رابط الصفحة في التطبيق. إذا لم يتم تحديد أيّ وسيطة بالاسم نفسه، يتم استخدام نوع String تلقائي لقيمة الوسيطة. يمكنك استخدام البدل .‎* لمطابقة 0 أو أكثر من الأحرف.
    • يمكن استخدام العناصر النائبة لمَعلمات طلب البحث بدلاً من مَعلمات المسار أو معًا. على سبيل المثال، http://www.example.com/users/{id}?myarg={myarg} يتطابق مع http://www.example.com/users/4?myarg=28.
    • العناصر النائبة لمعلمات طلب البحث للمتغيرات المحددة بقيم تلقائية أو قابلة للقيم الفارغة ليست مطلوبة للمطابقة. على سبيل المثال، تطابق http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} http://www.example.com/users/4?arg2=28 أو http://www.example.com/users/4?arg1=7. لا ينطبق ذلك على مَعلمات ملف المسار. على سبيل المثال، لا يتطابق المسار http://www.example.com/users?arg1=7&arg2=28 مع النمط أعلاه لأنّه لم يتم تقديم مَعلمة المسار المطلوبة.
    • لا تؤثّر مَعلمات طلب البحث غير ذات الصلة في مطابقة معرّف الموارد المنتظم للرابط المؤدي لصفحة معيّنة. على سبيل المثال، يتطابق http://www.example.com/users/{id} مع http://www.example.com/users/4?extraneousParam=7، على الرغم من عدم تعريف extraneousParam في نمط معرّف الموارد المنتظم.

  4. (اختياري) ضَع علامة في المربّع إثبات الملكية تلقائيًا لطلب Google التحقّق من أنّك مالك عنوان URL. لمزيد من المعلومات، يُرجى الاطّلاع على التحقّق من روابط تطبيقات Android.

  5. انقر على إضافة. يظهر رمز رابط فوق الوجهة المحدّدة للإشارة إلى أنّ هذه الوجهة تحتوي على رابط لصفحة في التطبيق.

  6. انقر على علامة التبويب الرمز للتبديل إلى عرض XML. تمت إضافة عنصر <deepLink> مُدمَج إلى الوجهة:

    <deepLink app:uri="https://www.google.com" />

لتفعيل الربط لصفحة معيّنة ضمن التطبيق بشكل ضمني، عليك أيضًا إجراء إضافات إلى ملف manifest.xml في تطبيقك. أضِف عنصر <nav-graph> واحدًا إلى نشاط يشير إلى رسم بياني حالي للتنقّل، كما هو موضّح في المثال التالي:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

عند إنشاء مشروعك، يستبدل مكوِّن "التنقل" عنصر <nav-graph> بعناصر <intent-filter> التي تم إنشاؤها لمطابقة جميع الروابط لمواضع معيّنة في الرسم البياني للتنقل.

عند تنشيط رابط ضمني لصفحة في التطبيق، تعتمد حالة الحزمة الخلفية على ما إذا كان قد تم تشغيل Intent الضمني باستخدام العلامة Intent.FLAG_ACTIVITY_NEW_TASK:

  • في حال ضبط العلامة، يتم محو تسلسل المهام للخلف واستبداله بوجهة الرابط العميق. كما هو الحال مع الروابط الصريحة لصفحات في التطبيق، عند تداخل الرسوم البيانية، تتم أيضًا إضافة وجهة البدء من كل مستوى من مستويات التداخل، أي وجهة البدء من كل عنصر <navigation> في التسلسل الهرمي، إلى الحزمة. وهذا يعني أنّه عندما يضغط المستخدم على زر الرجوع من وجهة رابط لصفحة في التطبيق، سينتقل إلى أعلى حزمة التنقّل كما لو كان قد دخل إلى تطبيقك من نقطة الدخول.
  • في حال عدم ضبط العلامة، ستظل في حزمة المهام للتطبيق السابق حيث تم تنشيط الرابط التلقائي لصفحة في التطبيق. في هذه الحالة، يعيدك زر "Back" (الرجوع) إلى التطبيق السابق، بينما يبدأ الزر "Up" مهمة تطبيقك في الوجهة الرئيسية الهرمية داخل الرسم البياني للتنقل.

التعامل مع الروابط لصفحات معيّنة

ننصح بشدة باستخدام القيمة التلقائية launchMode من standard دائمًا عند استخدام ميزة التنقّل. عند استخدام وضع التشغيل standard، يعالج Navigation الروابط لصفحات في التطبيق تلقائيًا من خلال استدعاء handleDeepLink() لمعالجة أي روابط لصفحات في التطبيق صريحة أو ضمنية ضمن Intent. ومع ذلك، لا يحدث ذلك تلقائيًا في حال إعادة استخدام Activity عند استخدام launchMode بديل، مثل singleTop. في هذه الحالة، من الضروري استدعاء handleDeepLink() يدويًا في onNewIntent()، كما هو موضح في المثال التالي:

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

مصادر إضافية

لمزيد من المعلومات عن التنقّل، يُرجى الاطّلاع على المراجع التالية.

نماذج

الدروس التطبيقية حول الترميز

الفيديوهات