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

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

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

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

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

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

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

1. في ملف AndroidManifest.xml الخاص بتطبيقك، ابحث عن النشاط الذي تم ضبط فلاتر الأهداف الخاصة به على الإجراء 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>
   

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

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

android:shortcutId

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

android:shortcutShortLabel

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

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

android:shortcutLongLabel

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

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

android:shortcutDisabledMessage

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

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

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

مكتبة ShortcutManagerCompat Jetpack هي أداة مساعدة لواجهة برمجة التطبيقات 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)

إضافة مكتبة دمج اختصارات Google

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

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

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

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

لاستخدام هذه المكتبة في تطبيقك، اتّبِع الخطوات التالية:

1. عدِّل ملف gradle.properties ليتوافق مع مكتبات AndroidX:

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. في app/build.gradle، أضِف التبعيات الخاصة بمكتبة Google Shortcuts Integration وShortcutManagerCompat:

   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. أنشئ عنصر ShortcutInfo بإحدى الطريقتَين التاليتَين، وذلك حسب ما إذا كان الاختصار متوفّرًا أم لا:

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

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

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

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

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").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 = shortcutManager.createShortcutResultIntent(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 */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

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

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

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

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

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

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

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

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