توفّر الاختصارات أنواعًا محددة من المحتوى للمستخدمين من خلال مساعدتهم للوصول سريعًا إلى أجزاء من تطبيقك.
![صورة توضّح التباين بين اختصارات التطبيقات والاختصارات المثبَّتة](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?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
-
الرسالة التي تظهر في مشغّل تطبيقات متوافق عندما يحاول المستخدم إطلاق اختصار غير مفعَّل يجب أن توضّح الرسالة للمستخدم سبب تم إيقاف الاختصار. لن يكون لقيمة هذه السمة أي تأثير إذا تم
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
المرجع.
في ما يلي مثال على إنشاء اختصار ديناميكي وربطه بـ التطبيق:
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 هي مكتبة اختيارية في Jetpack. أُنشأها جون هنتر، الذي كان متخصصًا دفع الاختصارات الديناميكية التي يمكن عرضها على مساحات عرض Android، مثل ومشغّل التطبيقات ومنصات Google، مثل "مساعد Google". استخدام هذه المكتبة تساعد المستخدمين في اكتشاف اختصاراتك للوصول بسرعة إلى محتوى معيّن أو إعادة تشغيل المحتوى. الإجراءات في تطبيقك.
على سبيل المثال، قد يضع تطبيق مراسلة اختصارًا ديناميكيًا لجهة اتصال باسم "أليكس" بعد أن يرسل المستخدم رسالة إلى هذا الشخص. بعد انتهاء الاختصار الديناميكي إذا طرح المستخدم السؤال التالي: "Ok Google، أريد إرسال رسالة إلى سمير على ExampleApp"، يمكن لمساعد Google تشغيل ExampleApp وإعداده تلقائيًا لإرسال رسالة إلى أليكس.
لا تخضع الاختصارات الديناميكية التي يتم إرسالها إلى هذه المكتبة إلى حدود الاختصارات يتم فرضها على أساس كل جهاز على حدة. ويسمح هذا للتطبيق بوضع اختصار في كل مرة إكمال المستخدِم لإجراء مرتبط في تطبيقك دفع الاختصارات بشكل متكرر لهذا إلى Google فهم أنماط استخدام المستخدم واقتراح محتوى والاختصارات ذات الصلة بها.
على سبيل المثال، يمكن أن يتعلّم "مساعد Google" من الاختصارات المُرسَلة من تطبيق لتتبع اللياقة البدنية يستخدمه المستخدم عادةً كل صباح وبشكل استباقي اقتراح "بدء جولة" اختصار عندما يمسك المستخدم هاتفه من صَبَاح
لا توفّر مكتبة تكامل اختصارات 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?hl=ar)
يمكنك أيضًا إنشاء نشاط متخصص يساعد المستخدمين على إنشاء اختصارات، كاملة بخيارات مخصصة وزر تأكيد. يوضح الشكل 2 مثال على هذا النوع من النشاط في تطبيق Gmail.
في ملف البيان لتطبيقك، أضِف
ACTION_CREATE_SHORTCUT
على النشاط
<intent-filter>
العنصر. يعمل هذا البيان على إعداد السلوك التالي عندما يحاول المستخدم
لإنشاء اختصار:
- يبدأ النظام النشاط المتخصص لتطبيقك.
- يضبط المستخدم خيارات الاختصار.
- ينقر المستخدم على زر التأكيد.
-
سينشئ تطبيقك الاختصار باستخدام
createShortcutResultIntent()
. تُرجع هذه الطريقة دالةIntent
, يُعيد التطبيق توجيه التطبيق إلى النشاط الذي كان يتم تنفيذه سابقًا باستخدامsetResult()
-
يطلب تطبيقك
finish()
على النشاط المستخدَم لإنشاء الاختصار المخصّص
وبالمثل، يمكن لتطبيقك أن يطلب من المستخدمين إضافة اختصارات مثبَّتة إلى الصفحة الرئيسية. الشاشة بعد التثبيت أو عند تشغيل التطبيق لأول مرة. هذه الطريقة فعّالة لأنها تساعد المستخدمين في إنشاء اختصار كجزء من وسير العمل المعتاد.
اختبار الاختصارات
لاختبار اختصارات تطبيقك، يجب تثبيت تطبيقك على جهاز باستخدام مشغِّل تطبيقات. التي تتيح استخدام الاختصارات بعد ذلك، نفِّذ الإجراءات التالية:
- اللمس & اضغط مع الاستمرار على رمز مشغّل تطبيقك لعرض الاختصارات التي تحدّدها لتطبيقك.
- اسحب اختصارًا لتثبيته في مشغِّل الجهاز.