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

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

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

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

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

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

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

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.ComposeActivity" />
         <!-- 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)

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

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

إضافة Google Shortcuts Integration Library (مكتبة دمج اختصارات Google)

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

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

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

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

لا توفّر Google Shortcuts Integration Library (مكتبة اختصارات 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 و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::class.java)

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)
}

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new 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.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

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

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

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

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

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

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

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

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

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

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