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

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

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

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

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

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

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

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

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

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

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

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

إذا كان لديك ComponentName، يمكنك تمريرها إلى المطوّر مباشرةً:

val componentName = ...

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

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

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

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

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

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

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

مصادر إضافية

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

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

• الدرس التطبيقي حول التنقّل

الفيديوهات

• Android Jetpack: إدارة التنقّل في واجهة المستخدم باستخدام Navigation Controller (مؤتمر Google I/O لعام 2018)