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

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

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

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

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

عندما يفتح أحد المستخدمين تطبيقك من خلال رابط صريح لصفحة في التطبيق، يتم محو حزمة الرجوع للمهمة واستبدالها بوجهة الرابط لصفحة معيّنة في التطبيق. عند دمج الرسوم البيانية، تتم أيضًا إضافة وجهة البدء من كل مستوى من مستويات التداخل، أي وجهة البدء من كل عنصر <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 فتح تطبيقك إلى الوجهة المناسبة.

يمكن مطابقة الروابط لصفحات في التطبيق حسب معرّف الموارد المنتظم (URI) وإجراءات الأهداف وأنواع 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. في مربّع الحوار إضافة رابط لصفحة في التطبيق، أدخِل معلومات الرابط لصفحة معيّنة في التطبيق.

    لاحظ ما يلي:

    • يتم اعتبار معرّفات الموارد المنتظمة (URI) بدون مخطط على أنّها 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 مع النمط أعلاه لأنّه لم يتم توفير معلَمة المسار المطلوبة.
    • ولا تؤثر مَعلمات طلبات البحث غير الضرورية في مطابقة معرّف الموارد المنتظم (URI) لرابط صفحة معيّنة في التطبيق. على سبيل المثال، يتطابق http://www.example.com/users/{id} مع http://www.example.com/users/4?extraneousParam=7، على الرغم من أنّه لم يتم تحديد extraneousParam في نمط عنوان URI.

  4. (اختياري) يمكنك وضع علامة في مربع الإثبات التلقائي لمطالبة Google بإثبات أنك مالك معرّف الموارد المنتظم (URI). لمزيد من المعلومات، يُرجى الاطّلاع على التحقّق من روابط تطبيقات 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> في التسلسل الهرمي، إلى المكدّس. وهذا يعني أنه عندما يضغط المستخدم على زر الرجوع من وجهة رابط لموضع معين، فإنه يتنقل مرة أخرى إلى أعلى حزمة التنقل كما لو أنه دخل تطبيقك من نقطة الدخول الخاصة به.
  • وإذا لم يتم ضبط العلامة، ستظل في حزمة المهام للتطبيق السابق الذي تم تشغيل الرابط الضمني لصفحة معيّنة فيه. في هذه الحالة، يعيدك زر الرجوع إلى التطبيق السابق، بينما يبدأ الزر لأعلى مهمة تطبيقك على الوجهة الرئيسية الهرمية ضمن الرسم البياني للتنقل.

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

ننصح بشدة باستخدام الإعداد التلقائي launchMode الذي يبلغ standard عند استخدام ميزة التنقّل. عند استخدام وضع التشغيل standard، تعالج ميزة "التنقل" تلقائيًا الروابط لصفحات في التطبيق من خلال استدعاء 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);
}

مراجع إضافية

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

عيّنات

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

الفيديوهات الطويلة