تقدّم الاختصارات أنواعًا معيّنة من المحتوى للمستخدمين من خلال مساعدتهم في الوصول بسرعة إلى أجزاء من تطبيقك.
![صورة تعرض التباين بين اختصارات التطبيقات والاختصارات المثبّتة](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?authuser=5&hl=ar)
وتعتمد طريقة عرض المحتوى باستخدام الاختصارات على حالة الاستخدام وما إذا كان سياق الاختصار مستندًا إلى التطبيق أو يستند إلى المستخدم. على الرغم من عدم تغيير سياق الاختصار الثابت وأن سياق الاختصار الديناميكي يتغير باستمرار، إلا أن تطبيقك يقود السياق في كلتا الحالتين. في الحالات التي يختار فيها المستخدم طريقة عرض التطبيق للمحتوى له، كما هو الحال عند استخدام اختصار مثبّت، يتم تحديد السياق بواسطة المستخدم. تصف السيناريوهات التالية بعض حالات الاستخدام لكل نوع اختصار:
- الاختصارات الثابتة هي الأفضل للتطبيقات التي ترتبط بالمحتوى باستخدام بنية متناسقة طوال فترة تفاعل المستخدم مع التطبيق. نظرًا لأن معظم مشغّلات التطبيقات لا تعرض سوى أربعة اختصارات في آنٍ واحد، تكون الاختصارات الثابتة مفيدة لتنفيذ مهمة روتينية بطريقة متسقة، مثلاً إذا أراد المستخدم الاطّلاع على التقويم أو البريد الإلكتروني بطريقة محددة .
- يتم استخدام الاختصارات الديناميكية لتنفيذ الإجراءات في التطبيقات الحسّاسة للسياق. يتم تصميم الاختصارات الحسّاسة للسياق وفقًا للإجراءات التي ينفّذها المستخدمون في تطبيق معيّن. على سبيل المثال، إذا كنت تنشئ لعبة تتيح للمستخدم البدء من المستوى الحالي عند إطلاق التطبيق، عليك تعديل الاختصار بشكل متكرّر. يتيح لك استخدام اختصار ديناميكي تعديل الاختصار في كل مرة يمحو فيها المستخدم مستوى.
- يتم استخدام الاختصارات المثبَّتة لإجراءات محدّدة تستند إلى المستخدم. على سبيل المثال، قد يريد المستخدم تثبيت موقع إلكتروني معيّن على مشغّل التطبيقات. ويُعدّ هذا الإجراء مفيدًا لأنّه يتيح للمستخدم تنفيذ إجراء مخصّص، مثل الانتقال إلى الموقع الإلكتروني بخطوة واحدة، بسرعة أكبر من استخدام مثيل تلقائي من المتصفح.
إنشاء اختصارات ثابتة
توفّر الاختصارات الثابتة روابط تؤدي إلى إجراءات عامة داخل تطبيقك، ويجب أن تظل هذه الإجراءات متسقة على مدار الإصدار الحالي من تطبيقك. تتضمن الخيارات الجيدة للاختصارات الثابتة عرض الرسائل المرسلة، وضبط المنبه، وعرض نشاط المستخدم الرياضي خلال اليوم.
لإنشاء اختصار ثابت، اتّبِع الخطوات التالية:
-
في ملف
AndroidManifest.xml
الخاص بتطبيقك، ابحث عن النشاط الذي تم ضبط فلاتر الأهداف الخاصة به على الإجراءandroid.intent.action.MAIN
والفئةandroid.intent.category.LAUNCHER
. -
أضِف عنصر
<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>
-
أنشئ ملف موارد جديدًا باسم
res/xml/shortcuts.xml
. -
في ملف المورد الجديد، أضِف عنصر جذر
<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 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
.
لاستخدام هذه المكتبة في تطبيقك، يُرجى اتّباع الخطوات التالية:
-
عليك تعديل ملف
gradle.properties
ليتوافق مع مكتبات AndroidX:android.useAndroidX=true # Automatically convert third-party libraries to use AndroidX android.enableJetifier=true
-
في
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 الفرق بين هذين النوعين من الاختصارات.
لتثبيت اختصار على مشغّل تطبيقات متوافق باستخدام تطبيقك، أكمِل الخطوات التالية:
-
استخدِم
isRequestPinShortcutSupported()
للتأكّد من أنّ مشغّل التطبيقات التلقائي على الجهاز يتيح تثبيت الاختصارات داخل التطبيق. -
يمكنك إنشاء كائن
ShortcutInfo
بإحدى الطريقتين، وذلك حسب ما إذا كان الاختصار متوفّرًا:-
في حال توفُّر الاختصار، أنشِئ عنصر
ShortcutInfo
يحتوي على رقم تعريف الاختصار الحالي فقط. يعثر النظام تلقائيًا على جميع المعلومات الأخرى ذات الصلة بالاختصار ويثبّتها. -
إذا كنت تثبّت اختصارًا جديدًا، أنشِئ عنصر
ShortcutInfo
يحتوي على معرّف وهدف وتصنيف قصير للاختصار الجديد.
-
في حال توفُّر الاختصار، أنشِئ عنصر
-
ثبِّت الاختصار على مشغِّل الجهاز من خلال طلب الرقم
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()); }
إنشاء نشاط اختصار مخصّص
![صورة تعرض نشاط مربّع الحوار المخصّص الذي يعرض رسالة المطالبة "هل تريد
إضافة رمز مشغّل تطبيق Gmail إلى الشاشة الرئيسية؟" الخيارات المخصّصة هي "لا، شكرًا" و"إضافة رمز".](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?authuser=5&hl=ar)
يمكنك أيضًا إنشاء نشاط متخصص يساعد المستخدمين في إنشاء اختصارات، والانتهاء بخيارات مخصصة وزر تأكيد. يوضح الشكل 2 مثالاً لهذا النوع من النشاط في تطبيق Gmail.
في ملف البيان لتطبيقك، أضِف
ACTION_CREATE_SHORTCUT
إلى عنصر
<intent-filter>
في النشاط. يُعد هذا البيان السلوك التالي عندما يحاول المستخدم إنشاء اختصار:
- يبدأ النظام النشاط المتخصّص لتطبيقك.
- يضبط المستخدم خيارات الاختصار.
- يختار المستخدم زر التأكيد.
-
ينشئ تطبيقك الاختصار باستخدام طريقة
createShortcutResultIntent()
. تعرض هذه الطريقةIntent
، الذي يعيده تطبيقك إلى النشاط المُنفّذ سابقًا باستخدامsetResult()
. -
يطلب تطبيقك
finish()
على النشاط المستخدَم لإنشاء الاختصار المخصّص.
وبالمثل، يمكن لتطبيقك أن يطلب من المستخدمين إضافة اختصارات مثبتة إلى الشاشة الرئيسية بعد التثبيت أو عند تشغيل التطبيق لأول مرة. هذه الطريقة فعالة لأنها تساعد المستخدمين في إنشاء اختصار كجزء من سير العمل العادي.
اختبار الاختصارات
لاختبار اختصارات التطبيق، عليك تثبيته على جهاز باستخدام مشغّل تطبيقات يتوافق مع الاختصارات. ثم نفِّذ الإجراءات التالية:
- انقر مع الاستمرار على رمز مشغّل تطبيقك لعرض الاختصارات التي تحدّدها لتطبيقك.
- اسحب اختصارًا لتثبيته على مشغِّل الجهاز.