إنشاء اختصارات

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

تعتمد طريقة تقديم المحتوى باستخدام الاختصارات على حالة الاستخدام وما إذا كان سياق الاختصار مستندًا إلى التطبيق أو إلى المستخدم. على الرغم من أنّ سياق الاختصار الثابت لا يتغيّر وسياق الاختصار الديناميكي يتغيّر باستمرار، فإنّ تطبيقك يحدّد السياق في كلتا الحالتَين. في الحالات التي يختار فيها المستخدم كيفية تقديم تطبيقك للمحتوى إليه، مثل اختصار مثبّت، يتم تحديد السياق من قِبل المستخدم. تصف السيناريوهات التالية بعض حالات الاستخدام لكل نوع من أنواع الاختصارات:

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

إنشاء اختصارات ثابتة

توفّر الاختصارات الثابتة روابط تؤدي إلى إجراءات عامة داخل تطبيقك، ويجب أن تظل هذه الإجراءات متسقة طوال مدة استخدام الإصدار الحالي من تطبيقك. تشمل الخيارات الجيدة للاختصارات الثابتة عرض الرسائل المُرسَلة وضبط المنبّه وعرض نشاط تمرين المستخدم لليوم.

لإنشاء اختصار ثابت، اتّبِع الخطوات التالية:

1. في ملف AndroidManifest.xml الخاص بتطبيقك، ابحث عن النشاط الذي تم ضبط intent filter له على الإجراء android.intent.action.MAIN والفئة android.intent.category.LAUNCHER.

2. أضِف عنصر <meta-data> إلى هذا النشاط يشير إلى ملف الموارد الذي يتم فيه تحديد اختصارات التطبيق:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" />
       </activity>
     </application>
   </manifest>
   

3. أنشئ ملف موارد جديدًا باسم res/xml/shortcuts.xml.

4. في ملف الموارد الجديد، أضِف عنصر جذر <shortcuts> يحتوي على قائمة بعناصر <shortcut>. في كل عنصر <shortcut>، أدرِج معلومات عن الاختصار الثابت، بما في ذلك رمزه وتصنيفات الوصف والمهام التي يشغّلها داخل التطبيق:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.Main" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
       <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
   shortcuts.xml

تخصيص قيم السمات المخصّصة

تتضمّن القائمة التالية أوصافًا للسمات المختلفة ضمن اختصار ثابت. أدخِل قيمة لسمة android:shortcutId وandroid:shortcutShortLabel. وجميع القيم الأخرى اختيارية.

android:shortcutId

سلسلة حرفية تمثّل الاختصار عندما ينفّذ عنصر ShortcutManager عمليات عليه.

android:shortcutShortLabel

عبارة موجزة تصف الغرض من الاختصار عند الإمكان، يجب ألّا يتجاوز هذا الوصف القصير 10 أحرف.

لمزيد من المعلومات، يُرجى الاطّلاع على setShortLabel().

android:shortcutLongLabel

عبارة موسّعة تصف الغرض من الاختصار إذا كانت هناك مساحة كافية، يعرض مشغّل التطبيقات هذه القيمة بدلاً من android:shortcutShortLabel. عند الإمكان، يجب ألا يتجاوز عدد أحرف هذا الوصف الطويل 25 حرفًا.

لمزيد من المعلومات، يُرجى الاطّلاع على setLongLabel().

android:shortcutDisabledMessage

The message that appears in a supported launcher when the user attempts to launch a disabled shortcut. يجب أن توضّح الرسالة للمستخدم سبب إيقاف الاختصار. لن يكون لقيمة هذه السمة أي تأثير إذا كانت قيمة android:enabled هي true.

android:enabled

يحدّد ما إذا كان بإمكان المستخدم التفاعل مع الاختصار من مشغّل تطبيقات متوافق. القيمة التلقائية للسياسة android:enabled هي true. إذا ضبطت السياسة على false، اضبط android:shortcutDisabledMessage يشرح سبب إيقاف الاختصار. إذا كنت لا تعتقد أنّك بحاجة إلى تقديم مثل هذه الرسالة، يمكنك إزالة الاختصار من ملف XML بالكامل.

android:icon

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

ضبط العناصر الداخلية

يتيح ملف XML الذي يسرد الاختصارات الثابتة للتطبيق العناصر التالية داخل كل عنصر <shortcut>. يجب تضمين عنصر داخلي intent لكل اختصار ثابت تحدّده.

intent

الإجراء الذي يشغّله النظام عندما يختار المستخدم الاختصار يجب أن يوفّر هذا الغرض قيمة لسمة android:action.

يمكنك تقديم عدة أهداف لاختصار واحد. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة عدة أغراض وأنشطة وتحديد غرض ومرجع فئة TaskStackBuilder.

categories

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

للاطّلاع على قائمة بفئات الاختصارات المتوافقة، يُرجى مراجعة مرجع الفئة ShortcutInfo.

capability-binding

يُعلن عن القدرة المرتبطة بالاختصار.

في المثال السابق، يرتبط الاختصار بإمكانية تم تحديدها لـ CREATE_MESSAGE، وهو هدف مضمّن في إجراءات التطبيقات. يتيح ربط الإمكانات هذا للمستخدمين استخدام الطلبات الصوتية مع "مساعد Google" لتشغيل اختصار.

إنشاء اختصارات ديناميكية

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

مكتبة Jetpack‏ ShortcutManagerCompat هي مكتبة مساعِدة لواجهة برمجة التطبيقات ShortcutManager، وتتيح لك إدارة الاختصارات الديناميكية في تطبيقك. ويؤدي استخدام مكتبة ShortcutManagerCompat إلى تقليل الرموز البرمجية النموذجية ويساعد في ضمان عمل الاختصارات بشكل متّسق على جميع إصدارات Android. هذه المكتبة مطلوبة أيضًا لإرسال الاختصارات الديناميكية لتكون مؤهَّلة للظهور على مساحات عرض Google، مثل "مساعد Google"، باستخدام مكتبة دمج اختصارات Google.

تتيح واجهة برمجة التطبيقات ShortcutManagerCompat لتطبيقك تنفيذ العمليات التالية باستخدام الاختصارات الديناميكية:

• النشر والتعديل: استخدِم pushDynamicShortcut() لنشر الاختصارات الديناميكية وتعديلها. إذا كان هناك اختصارات ديناميكية أو مثبّتة تحمل رقم التعريف نفسه، يتم تعديل كل اختصار قابل للتغيير.
• الإزالة: يمكنك إزالة مجموعة من الاختصارات الديناميكية باستخدام removeDynamicShortcuts(). أزِل جميع الاختصارات الديناميكية باستخدام removeAllDynamicShortcuts().

لمزيد من المعلومات حول تنفيذ العمليات على الاختصارات، يُرجى الاطّلاع على إدارة الاختصارات ومرجع ShortcutManagerCompat.

في ما يلي مثال على إنشاء اختصار ديناميكي وربطه بتطبيقك:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(
        Intent(
            Intent.ACTION_VIEW,
            Uri.parse("https://www.mysite.example.com/")
        )
    )
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)
ShortcutsSnippets.kt

إضافة مكتبة Google Shortcuts Integration

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

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

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

لا توفّر مكتبة Google Shortcuts Integration Library أي وظائف يمكن الوصول إليها. تتيح إضافة هذه المكتبة إلى تطبيقك لمساحات العرض في Google استقبال الاختصارات التي يرسلها تطبيقك باستخدام ShortcutManagerCompat.

لاستخدام هذه المكتبة في تطبيقك، أضِف تبعيات لمكتبة دمج اختصارات Google وShortcutManagerCompat إلى ملف app/build.gradle أو app/build.gradle.kts:

dependencies {
    implementation("androidx.core:core:1.6.0")
    implementation("androidx.core:core-google-shortcuts:1.0.0")
}

dependencies {
    implementation "androidx.core:core:1.6.0"
    implementation 'androidx.core:core-google-shortcuts:1.0.0'
}

بعد إضافة تبعيات المكتبة إلى مشروع Android، يمكن لتطبيقك استخدام طريقة pushDynamicShortcut() من ShortcutManagerCompat لإرسال الاختصارات الديناميكية المؤهَّلة للعرض على مشغّل التطبيقات ومساحات العرض المشارِكة من Google.

إنشاء اختصارات مثبَّتة

في نظام التشغيل Android 8.0 (مستوى واجهة برمجة التطبيقات 26) والإصدارات الأحدث، يمكنك إنشاء اختصارات مثبَّتة. على عكس الاختصارات الثابتة والديناميكية، تظهر الاختصارات المثبَّتة في مشغّلات التطبيقات المتوافقة كرموز منفصلة. يوضح الشكل 1 الفرق بين هذين النوعين من الاختصارات.

لتثبيت اختصار في مشغّل تطبيقات متوافق باستخدام تطبيقك، أكمِل الخطوات التالية:

1. استخدِم isRequestPinShortcutSupported() للتأكّد من أنّ مشغّل التطبيقات التلقائي على الجهاز يتيح تثبيت الاختصارات داخل التطبيق.

2. أنشِئ عنصر ShortcutInfoCompat يحتوي على معرّف وintent وتصنيف قصير للاختصار. إذا كان الاختصار متوفّرًا، استخدِم رقم تعريف الاختصار الحالي. يعثر النظام على جميع المعلومات الأخرى المتعلقة بالاختصار ويثبتها تلقائيًا.

3. ثبِّت الاختصار في مشغّل التطبيقات على الجهاز من خلال استدعاء requestPinShortcut(). خلال هذه العملية، يمكنك تمرير عنصر PendingIntent، والذي يُرسل إشعارًا إلى تطبيقك فقط عند تثبيت الاختصار بنجاح.

   بعد تثبيت اختصار، يمكن لتطبيقك تعديل محتواه باستخدام طريقة updateShortcuts(). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تعديل الاختصارات.

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

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent =
        ShortcutManagerCompat.createShortcutResultIntent(context, pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(
        context, /* request code */ 0,
        pinnedShortcutCallbackIntent, /* flags */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

إنشاء نشاط اختصار مخصّص

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

في ملف بيان تطبيقك، أضِف ACTION_CREATE_SHORTCUT إلى العنصر <intent-filter> الخاص بالنشاط. يؤدي هذا البيان إلى إعداد السلوك التالي عندما يحاول المستخدم إنشاء اختصار:

1. يبدأ النظام النشاط المتخصّص لتطبيقك.
2. يحدّد المستخدم خيارات الاختصار.
3. ينقر المستخدم على زر التأكيد.
4. ينشئ تطبيقك الاختصار باستخدام الإجراء createShortcutResultIntent(). تعرض هذه الطريقة Intent، الذي ينقله تطبيقك إلى النشاط الذي تم تنفيذه سابقًا باستخدام setResult().
5. يستدعي تطبيقك finish() في النشاط المستخدَم لإنشاء الاختصار المخصّص.

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

اختبار الاختصارات

لاختبار اختصارات تطبيقك، ثبِّت تطبيقك على جهاز يتضمّن مشغّل تطبيقات يتيح استخدام الاختصارات. بعد ذلك، نفِّذ الإجراءات التالية:

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