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

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

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

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

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

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

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

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

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

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"

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

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

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() على النشاط المستخدَم لإنشاء الاختصار المخصّص

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

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

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

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