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

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

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

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

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

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

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

لإنشاء اختصار ثابت، قم بما يلي:

  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.

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

Kotlin


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)

Java


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"

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

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

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

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

Kotlin

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

Java

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

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

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

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

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

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

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

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

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

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