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

إدارة الاختصارات

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

توضّح هذه الصفحة هذه الطرق والعديد من الطرق الشائعة الأخرى لإدارة الاختصارات.

سلوك الاختصار

تحتوي الأقسام التالية على معلومات عامة حول سلوك الاختصارات، بما في ذلك مستوى العرض وترتيب العرض والترتيب.

إذن الوصول إلى الاختصار

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

توفّر الفئة LauncherApps واجهات برمجة تطبيقات لتطبيقات مشغّل التطبيقات للوصول إلى الاختصارات.

بما أنّ الاختصارات المثبّتة تظهر في مشغّل التطبيقات نفسه، فهي تكون مرئية دائمًا. لا تتم إزالة اختصار مثبَّت من مشغّل التطبيقات إلا في الحالات التالية:

يزيلها المستخدم.
تم إلغاء تثبيت التطبيق المرتبط بالاختصار.
يمحو المستخدم بيانات التطبيق من خلال الانتقال إلى الإعدادات > التطبيقات والإشعارات، ثم اختيار التطبيق والنقر على مساحة التخزين > محو مساحة التخزين.

أهداف المشاركة هي مجموعة فرعية من الاختصارات الديناميكية التي تظهر في صف المشاركة المباشرة في قائمة مشاركة البيانات من Android.

ترتيب عرض الاختصارات

عندما يعرض مشغّل التطبيقات اختصارات أحد التطبيقات، يجب أن تظهر بالترتيب التالي:

الاختصارات الثابتة: هي الاختصارات التي تُرجع فيها الطريقة isDeclaredInManifest() القيمة true.
الاختصارات الديناميكية: هي الاختصارات التي تُرجع الطريقة ShortcutInfo.isDynamic() الخاصة بها القيمة true.

ضمن كل نوع من أنواع الاختصارات، سواء كانت ثابتة أو ديناميكية، يتم ترتيب الاختصارات حسب الترتيب التصاعدي وفقًا لـ ShortcutInfo.getRank. يأخذ "مساعد Google" أيضًا في الاعتبار ترتيب الاختصارات عند تحديد الاختصارات السياقية التي سيتم عرضها للمستخدمين.

الترتيبات هي أعداد صحيحة متسلسلة غير سالبة. يتم ترتيب الاختصارات الثابتة من الأول إلى الأخير حسب ترتيب ظهورها في ملف shortcuts.xml. بالنسبة إلى الاختصارات الديناميكية، يمكنك تعديل ترتيب الاختصارات الحالية عند استدعاء updateShortcuts(Context, List) أو addDynamicShortcuts(Context, List) أو pushDynamicShortcut(Context, ShortcutInfoCompat) أو setDynamicShortcuts(Context, List).

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

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

إدارة الأهداف والأنشطة المتعددة

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

بدء نشاط من نشاط آخر

لا يمكن أن تحتوي الاختصارات الثابتة على علامات مخصّصة للنيّة بالشراء. يتم دائمًا ضبط Intent.FLAG_ACTIVITY_NEW_TASK وIntent.FLAG_ACTIVITY_CLEAR_TASK في الغرض الأول من الاختصار الثابت. وهذا يعني أنّه عندما يكون تطبيقك قيد التشغيل، يتم إتلاف جميع الأنشطة الحالية في التطبيق عند تشغيل اختصار ثابت. إذا كنت لا تريد هذا السلوك، يمكنك استخدام نشاط الترامبولين، وهو نشاط غير مرئي يبدأ نشاطًا آخر، من خلال استدعاء finish داخل كتلة تشغيل أو onCreate قبل ضبط محتوى Compose:

في AndroidManifest.xml file، قم بتضمين تعيين السمة android:taskAffinity="" في نشاط الترامبولين.
في ملف موارد الاختصارات، يمكنك الإشارة إلى نشاط الترامبولين في الهدف ضمن الاختصار الثابت.

لمزيد من المعلومات حول أنشطة الترامبولين، يُرجى الاطّلاع على بدء نشاط من نشاط آخر.

ضبط علامات Intent

يمكنك نشر الاختصارات الديناميكية باستخدام أي مجموعة من علامات Intent. ويُفضَّل تحديد مجموعة Intent.FLAG_ACTIVITY_SINGLE_TOP وIntent.FLAG_ACTIVITY_CLEAR_TOP في نية الاختصار. يضمن ذلك أنّه إذا كان ComponentActivity نشطًا، يتم إحضاره إلى المقدّمة وإعادة استخدامه بدون إتلافه، ما يسمح لبنية النشاط الواحد بمعالجة حدث الاختصار بسلاسة من خلال onNewIntent().

لمزيد من المعلومات حول المهام وعلامات intent، يُرجى الاطّلاع على المهام والأنشطة السابقة.

تعديل الاختصارات

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

عند تثبيت اختصار ديناميكي، يظل الاختصار المثبَّت مرئيًا وقابلاً للتشغيل حتى إذا أزاله الناشر كاختصار ديناميكي. يتيح هذا الإعداد للتطبيق الحصول على أكثر من getMaxShortcutCountPerActivity اختصار.

انظر المثال التالي الذي يفترض أنّ القيمة التي تعرضها الدالة getMaxShortcutCountPerActivity هي 4:

ينشر تطبيق محادثات أربعة اختصارات ديناميكية تمثّل المحادثات الأربع الأخيرة: c1 وc2 وc3 وc4.
يثبّت المستخدم جميع الاختصارات الأربعة.
بعد ذلك، يبدأ المستخدم ثلاث محادثات إضافية: c5 وc6 وc7. يعيد تطبيق الناشر نشر اختصاراته الديناميكية. قائمة الاختصارات الديناميكية الجديدة هي: c4 وc5 وc6 وc7.

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

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

يمكن للتطبيق استخدام updateShortcuts(Context, List) لتعديل أي من الاختصارات السبعة الحالية. على سبيل المثال، يمكنك تعديل هذه المجموعة من الاختصارات عند تغيير رموز أطراف المحادثة.
يمكنك استخدام الطريقتَين addDynamicShortcuts(Context, List) وsetDynamicShortcuts(Context, List) لتعديل الاختصارات الحالية التي تتضمّن أرقام التعريف نفسها. ومع ذلك، لا يمكنك استخدامها لتعديل الاختصارات غير الديناميكية المثبَّتة، لأنّ هاتين الطريقتين تحاولان تحويل قوائم الاختصارات المحدّدة إلى اختصارات ديناميكية.

ما مِن حدّ أقصى لعدد الاختصارات التي يمكن إرسالها للعرض على تطبيقات المساعد، مثل "مساعد Google". استخدِم طريقة pushDynamicShortcut من مكتبة ShortcutManagerCompat Jetpack لإنشاء وتعديل الاختصارات لاستخدامها في تطبيقات المساعد. أضِف أيضًا مكتبة Google Shortcuts Integration إلى تطبيقك لكي تصبح الروابط الديناميكية مؤهَّلة للظهور على "مساعد Google".

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

التعامل مع التغييرات في لغة النظام

يجب أن تعدّل التطبيقات الاختصارات الديناميكية والمثبَّتة عند تلقّي البث Intent.ACTION_LOCALE_CHANGED الذي يشير إلى تغيير في لغة النظام.

تتبُّع استخدام الاختصارات

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

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

يتتبّع تطبيقك استخدام الاختصارات الديناميكية من خلال استدعاء الطريقة pushDynamicShortcut وتمرير معرّف الاختصار إليها عند وقوع حدث ذي صلة. يؤدي استخدام الاختصارات الديناميكية بهذه الطريقة إلى السماح لتطبيقات المساعد، مثل "مساعد Google"، باقتراح اختصارات ذات صلة للمستخدمين. بما أنّ طريقة pushDynamicShortcut تُبلغ عن الاستخدام عند استدعائها، لا تستدعِ طريقة reportShortcutUsed للاختصارات نفسها.

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

إيقاف الاختصارات

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

تقييد معدّل الزيارات على الويب

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

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

عندما يتم فتح تطبيق في المقدّمة
تغيير لغة النظام
ينفّذ المستخدم إجراء الردّ المضمّن على إشعار.

إذا واجهت مشكلة في الحدّ من معدّل الاستخدام أثناء التطوير أو الاختبار، يمكنك اختيار خيارات المطوّرين > إعادة ضبط الحدّ من معدّل استخدام ShortcutManager من إعدادات الجهاز، أو يمكنك إدخال الأمر التالي في adb:

adb shell cmd shortcut reset-throttling [ --user your-user-id ]

النسخ الاحتياطي والاسترداد

يمكنك السماح للمستخدمين بإجراء عمليات الاحتفاظ بنسخة احتياطية واستعادتها على تطبيقك عند تغيير الأجهزة من خلال تضمين السمة android:allowBackup="true" في ملف بيان تطبيقك. إذا كنت تتيح الاحتفاظ بنسخة احتياطية واستعادتها، يُرجى مراعاة النقاط التالية بشأن اختصارات التطبيقات:

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

يوضّح مقتطف الرمز التالي أفضل طريقة لاستعادة الاختصارات الديناميكية لتطبيقك وكيفية التحقّق من الاحتفاظ بالاختصارات المثبَّتة لتطبيقك:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}ShortcutsSnippets.kt

إضافة إمكانات إلى الاختصارات

تنفيذ أفضل الممارسات للاختصارات