![](https://developer.android.com/static/training/sharing/direct-share-targets.png?authuser=6&hl=ar)
استخدِم أهداف "المشاركة المباشرة" لتسهّل على مستخدمي التطبيقات الأخرى مشاركة عناوين URL أو الصور أو أنواع أخرى من البيانات مع تطبيقك. وتعمل ميزة "المشاركة المباشرة" من خلال عرض جهات الاتصال من المراسلة والتطبيقات الاجتماعية مباشرةً على ورقة المشاركة في Android، بدون الحاجة إلى النقر على التطبيق ثم البحث عن جهة الاتصال.
ShortcutManagerCompat
هي واجهة برمجة تطبيقات لنظام التشغيل AndroidX توفّر "اختصارات المشاركة"، وهي متوافقة مع الأنظمة القديمة
مع واجهة برمجة التطبيقات ChooserTargetService
المتوقّفة. هذه هي الطريقة المفضّلة لنشر كل من اختصارات المشاركة وChooserTargets
. للحصول على التعليمات،
راجع استخدام AndroidX لتوفير كل من اختصارات المشاركة وChooserTargets
في هذه الصفحة.
نشر أهداف المشاركة المباشرة
لا يعرض صف "المشاركة المباشرة في ورقة البيانات" سوى الاختصارات الديناميكية التي توفّرها واجهة برمجة التطبيقات Shared Shortcuts API. أكمِل الخطوات التالية لنشر أهداف المشاركة المباشرة.
في ملف موارد XML الخاص بتطبيقك، حدِّد عناصر
share-target
.<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
عند بدء تطبيقك، استخدِم
setDynamicShortcuts
لترتيب الاختصارات الديناميكية حسب الأهمية.يشير انخفاض المؤشر إلى المزيد من الأهمية. إذا كنت تنشئ تطبيقًا للتواصل، يمكن أن يكون أهم المحادثات مرتبة حسب الحداثة كما تظهر في التطبيق. ولا تنشر الاختصارات القديمة، حيث إن المحادثة التي لا تتضمن أي نشاط للمستخدم في آخر 30 يومًا تُعتبر قديمة.
Kotlin
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
إذا كنت تطوّر تطبيقًا للتواصل، عليك الإبلاغ عن استخدام الاختصارات من خلال
pushDynamicShortcut
على الفور في كل مرة يتلقّى المستخدم رسالة أو يرسلها إلى جهة اتصال. راجع الإبلاغ عن استخدام اختصارات تطبيقات الاتصالات في هذه الصفحة للحصول على مزيد من المعلومات. مثلاً، يمكنك الإبلاغ عن استخدام الرسائل المُرسَلة من المستخدم من خلال تحديد عمليات ربط الإمكانات في الاختصار من خلالShortcutInfoCompat.Builder#addCapabilityBinding
باستخدام الميزةactions.intent.SEND_MESSAGE
.Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
إذا حذف المستخدم جهة اتصال، استخدِم
removeLongLivedShortcut
. هذه هي الطريقة المفضّلة لإزالة الاختصار بغض النظر عمّا إذا كان مخزَّنًا مؤقتًا في خدمات النظام أم لا. ويعرض مقتطف الرمز التالي مثالاً على كيفية إجراء ذلك.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
تحسين ترتيب أهداف "المشاركة المباشرة"
تعرض ورقة المشاركة في Android عددًا ثابتًا من أهداف "المشاركة المباشرة". يتم فرز هذه الاقتراحات حسب الترتيب. على الأرجح، يمكنك تحسين ترتيب الاختصارات عن طريق إجراء ما يلي:
- تأكَّد من أنّ كل
shortcutIds
فريدة ولا تتم إعادة استخدامها أبدًا لأهداف مختلفة. - تأكَّد من أنّ الاختصار طويل الأمد من خلال طلب الرمز
setLongLived(true)
. - بالنسبة إلى الاختصارات المرتبطة بالمحادثة، يمكنك الإبلاغ عن استخدام الاختصارات
للرسائل الصادرة والواردة من خلال إعادة نشر الاختصارات المقابلة
من خلال
ShortcutManagerCompat.pushDynamicShortcut
. يُرجى الاطّلاع على مقالة الإبلاغ عن استخدام اختصارات تطبيقات الاتصالات في هذه الصفحة لمزيد من التفاصيل. - تجنَّب تقديم أهداف مشاركة مباشرة غير ملائمة أو قديمة، على سبيل المثال، جهات الاتصال التي لم يراسلها المستخدم خلال آخر 30 يومًا.
- بالنسبة إلى تطبيقات الرسائل القصيرة SMS، تجنَّب تقديم اختصارات للرموز القصيرة أو المحادثات التي يتم تحديدها على أنّها يُحتمَل أن تكون غير مرغوب فيها. من غير المرجح بشدة أن يشارك المستخدمون في تلك المحادثات.
- عليك استدعاء
setCategories()
لربط الاختصار بسماتmimeType
المناسبة. على سبيل المثال، بالنسبة إلى تطبيق SMS، إذا لم تكن جهة الاتصال متوافقة مع خدمة RCS أو رسالة وسائط متعددة، لن تربط الاختصار المقابل بأنواع MIME غير نصية مثلimage/*
وvideo/*
. - بالنسبة إلى محادثة معيّنة، بعد الدفع باختصار ديناميكي والإبلاغ عن الاستخدام، لا تغيّر معرّف الاختصار. يضمن ذلك الاحتفاظ ببيانات الاستخدام من أجل الترتيب
إذا نقر المستخدم على أي هدف من خلال ميزة "المشاركة المباشرة"، يجب أن ينقله التطبيق إلى واجهة المستخدم حيث يمكنه تنفيذ إجراء بشأن الموضوع المستهدَف مباشرةً. لا تُقدِّم للمستخدم واجهة مستخدم واضحة، ولا تضعه في واجهة مستخدم غير مرتبطة بالهدف الذي تم النقر عليه. على سبيل المثال، في أحد تطبيقات المراسلة، يؤدي النقر على هدف المشاركة المباشرة إلى نقل المستخدم إلى عرض محادثة مع الشخص الذي اختاره. تكون لوحة المفاتيح مرئية وتتم تعبئة الرسالة مسبقًا بالبيانات المشتركة.
واجهة برمجة التطبيقات الخاصة بالاختصارات
بدءًا من نظام التشغيل Android 10 (المستوى 29 لواجهة برمجة التطبيقات)،
أضافت أداة ShortcutInfo.Builder
طرقًا وتحسينات
توفِّر معلومات إضافية عن مشاركة البيانات المستهدفة:
setCategories()
- بدءًا من نظام التشغيل Android 10، تُستخدَم الفئات أيضًا لفلترة الاختصارات التي يمكنها التعامل مع أغراض المشاركة أو إجراءاتها. راجع تحديد هدف الحصة للاطّلاع على التفاصيل. هذا الحقل مطلوب للاختصارات المراد استخدامها كأهداف مشاركة.
setLongLived()
تحدِّد هذه السياسة ما إذا كان الاختصار صالحًا عندما يتم إلغاء نشره أو جعله غير مرئي بواسطة التطبيق (كاختصار ديناميكي أو مثبَّت). إذا كان الاختصار متوفّرًا منذ فترة طويلة، يمكن تخزينه مؤقتًا من خلال خدمات نظام مختلفة حتى بعد إلغاء نشره كاختصار ديناميكي.
يمكن أن يؤدي إنشاء اختصار طويل الأمد إلى تحسين ترتيبه. راجع الحصول على أفضل ترتيب لمعرفة التفاصيل.
setShortLabel()
،setLongLabel()
عند نشر اختصار إلى شخص واحد، يرجى تضمين اسمه بالكامل في
setLongLabel()
وأي اسم مختصر، مثل اللقب أو الاسم الأول فيsetShortLabel()
.
اطّلِع على مثال على اختصارات مشاركة المشاركة على GitHub.
تقديم صور مختصرة
لإنشاء اختصار مشاركة، عليك إضافة صورة من خلال setIcon()
.
يمكن أن تظهر اختصارات المشاركة على أسطح النظام وقد يتم إعادة تشكيلها.
بالإضافة إلى ذلك، قد تعرض بعض الأجهزة التي تعمل بإصدارات Android 7 أو 8 أو 9 (مستويات واجهة برمجة التطبيقات 25 و26 و27 و28) رموزًا نقطية فقط بدون خلفية، ما يؤدي إلى
تقليل التباين بشكل كبير. لضمان ظهور الاختصار كما هو مطلوب،
قدِّم صورة نقطية تكيُّفية باستخدام IconCompat.createWithAdaptiveBitmap()
.
تأكد من أن الصور النقطية التكيُّفية تتبع نفس الإرشادات والأبعاد المحددة للرموز التكيُّفية. الطريقة الأكثر شيوعًا لتنفيذ هذا الإجراء هي تغيير حجم الصورة النقطية المربّعة المطلوبة إلى 72x72 بكسل مستقل الكثافة وتوسيط داخل لوحة شفافة تبلغ 108x108 بكسل مستقل الكثافة. إذا كان رمزك يتضمن مناطق شفافة، فأنت بحاجة إلى تضمين لون خلفية، وإلا ستظهر المناطق الشفافة باللون الأسود.
لا توفِّر صورًا مقنعة لشكل معيّن. على سبيل المثال، قبل استخدام
Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، كان من الشائع توفير صور رمزية للمستخدمين ضمن ميزة "المشاركة المباشرة"
ChooserTarget
بحيث يتم حجبها في دائرة. يبرز تطبيق Android Sharesheet والنظام الآخر في Android 10 الآن صور اختصارات للأشكال والمظاهر.
إنّ الطريقة المفضّلة لتوفير "اختصارات المشاركة" من خلال ShortcutManagerCompat
تعمل تلقائيًا على تشكيل عناصر "المشاركة المباشرة" ChooserTarget
لتكون متوافقة مع الخلفية من أجل مساعدتك.
تعريف هدف حصة
يجب الإعلان عن أهداف المشاركة في ملف موارد التطبيق، على غرار تعريفات الاختصارات الثابتة. أضِف تعريفات استهداف المشاركة داخل العنصر الجذر <shortcuts>
في ملف المورد، إلى جانب تعريفات الاختصارات الثابتة الأخرى. يحتوي كل عنصر <share-targets>
على معلومات حول نوع البيانات المشتركة والفئات المطابقة
والفئة المستهدفة التي ستتعامل مع الرغبة في المشاركة. يبدو رمز XML على النحو التالي:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
يتشابه عنصر البيانات في هدف المشاركة مع مواصفات البيانات في فلتر الأهداف. يمكن أن يحتوي كل هدف مشاركة على فئات متعددة تُستخدم فقط لمطابقة الاختصارات المنشورة للتطبيق مع تعريفات الهدف المشتركة له. يمكن أن تحتوي الفئات على أي قيم عشوائية يتم تحديدها من خلال التطبيق.
في حال اختار المستخدم اختصار المشاركة في "ورقة مشاركة Android" الذي يتطابق مع مثال مشاركة الهدف أعلاه، سيحصل التطبيق على الغرض التالي من المشاركة:
Action: Intent.ACTION_SEND ComponentName: {com.example.android.sharingshortcuts / com.example.android.sharingshortcuts.SendMessageActivity} Data: Uri to the shared content EXTRA_SHORTCUT_ID: <ID of the selected shortcut>
إذا فتح المستخدم هدف المشاركة من اختصارات مشغّل التطبيقات، سيحصل على الغرض الذي تم إنشاؤه عند إضافة اختصار المشاركة إلى ShortcutManagerCompat.
وبما أنّ الغرض من ذلك مختلف، لن يكون Intent.EXTRA_SHORTCUT_ID
متاحًا، وعليك ضبط المعرّف يدويًا إذا كنت بحاجة إليه.
الإبلاغ عن استخدام الاختصارات لتطبيقات الاتصال
إذا كنت تطور تطبيقًا للتواصل، يمكنك تحسين ترتيبك في
ورقة مشاركة Android من خلال الإبلاغ عن استخدام الرسائل الصادرة والواردة.
لإجراء ذلك، أعِد نشر اختصار المحادثة الذي يمثّل جهة الاتصال من خلال
ShortcutManagerCompat.pushDynamicShortcut
.
تتوافق روابط استخدام الاختصارات والإمكانات مع الإصدارات السابقة من Android 5.0 (واجهة برمجة التطبيقات 21).
الإبلاغ عن استخدام الاختصارات للرسائل الصادرة
يتشابه عمليًا لإعداد التقارير عن الرسائل التي يرسلها المستخدم للنقر على زر "إرسال" بعد إنشاء رسالة.
لتفعيل إعداد تقارير الاستخدام، حدِّد عمليات ربط الإمكانات في الاختصار
من خلال ShortcutInfoCompat.Builder#addCapabilityBinding
باستخدام الميزة actions.intent.SEND_MESSAGE
.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
في حال كانت الرسالة الصادرة لمحادثة جماعية، عليك أيضًا إضافة قيمة المَعلمة Audience
لأن النوع recipient
مرتبط بهذه الميزة.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
الإبلاغ عن استخدام الاختصارات للرسائل الواردة
لتفعيل ميزة إعداد تقارير الاستخدام عندما يتلقّى المستخدم رسالة مثل رسالة قصيرة SMS أو رسالة محادثة أو رسالة إلكترونية أو إشعارات، عليك أيضًا تحديد عمليات ربط الإمكانات في الاختصار من خلال ShortcutInfoCompat.Builder#addCapabilityBinding
مع إمكانية actions.intent.RECEIVE_MESSAGE
.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
في حال كانت الرسالة الواردة من محادثة جماعية، عليك أيضًا إضافة قيمة المَعلمة Audience
لأن النوع sender
مرتبط بالقدرة.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
استخدام AndroidX لتوفير كل من اختصارات المشاركة وأداة الاختيار
وليتمكّن من العمل مع مكتبة التوافق مع AndroidX، يجب أن يشتمل ملف بيان التطبيق
على مجموعة أدوات اختيار البيانات الوصفية وخدمة الاستهداف وفلاتر الأهداف. يمكنك الاطّلاع على
واجهة برمجة تطبيقات المشاركة المباشرة الحالية في ChooserTargetService
.
سبق أن تم تعريف هذه الخدمة في مكتبة التوافق، لذلك لا يحتاج المستخدم إلى تعريف المستخدم بها في ملف بيان التطبيق. ومع ذلك، يجب مراعاة الرابط من نشاط المشاركة إلى الخدمة باعتباره موفّرًا مستهدفًا للمُختار.
في المثال التالي، يتمثّل تنفيذ ChooserTargetService
في السمة androidx.core.content.pm.ChooserTargetServiceCompat
، وهي محدّدة مسبقًا في AndroidX:
<activity android:name=".SendMessageActivity" android:label="@string/app_name" android:theme="@style/SharingShortcutsDialogTheme"> <!-- This activity can respond to Intents of type SEND --> <intent-filter> <action android:name="android.intent.action.SEND" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="text/plain" /> </intent-filter> <!-- Only needed if you import the sharetarget AndroidX library that provides backwards compatibility with the old DirectShare API. The activity that receives the Sharing Shortcut intent needs to be taken into account with this chooser target provider. --> <meta-data android:name="android.service.chooser.chooser_target_service" android:value="androidx.sharetarget.ChooserTargetServiceCompat" /> </activity>
الأسئلة الشائعة حول مشاركة الاختصارات
كيف يتم تخزين بيانات استخدام الاختصار وهل يغادر الجهاز؟
يتم تخزين الاختصارات بالكامل على الجهاز في دليل بيانات النظام في قسم قرص مشفّر. لا يمكن الوصول إلى المعلومات في الاختصارات، مثل الرمز والغرض وأسماء المستخدمين والموارد، إلا من خلال خدمات النظام والتطبيق نفسه الذي ينشر الاختصارات.
ما هو سجلّ "المشاركة المباشرة"؟
قدّمنا ميزة "المشاركة المباشرة" في الإصدار Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) للسماح للتطبيقات
بتوفير عناصر ChooserTarget
من خلال ChooserTargetService
. وقد تم استرداد النتائج بشكل تفاعلي عند الطلب، ما أدى إلى بطء وقت تحميل الأهداف.
في نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، تم استبدال واجهات برمجة التطبيقات للمشاركة المباشرة في ChooserTargetService
بواجهة برمجة التطبيقات Shared Shortcuts API الجديدة. بدلاً من استرداد النتائج عند الطلب بشكل تفاعلي، تسمح واجهة برمجة التطبيقات Shared Shortcuts API للتطبيقات بنشر أهداف "المشاركة المباشرة" مسبقًا. وأدّى ذلك إلى تسريع عملية استرداد أهداف "المشاركة المباشرة"
عند إعداد "ورقة البيانات المشتركة". ستستمر آلية المشاركة المباشرة في "ChooserTargetService
" في العمل،
إلا أنّ النظام يرتب الأهداف التي يتم تقديمها
بهذه الطريقة أقل من أي استهداف يستخدم واجهة برمجة التطبيقات Shared Shortcuts API.
أوقف نظام التشغيل Android 11 (المستوى 30 من واجهة برمجة التطبيقات) خدمة ChooserTargetService
نهائيًا،
وتكون واجهة برمجة التطبيقات Shared Shortcuts API هي الطريقة الوحيدة لتوفير أهداف "المشاركة المباشرة".
كيف تختلف الاختصارات المنشورة لأهداف المشاركة عن اختصارات مشغّل مشغّل التطبيقات (الاستخدام العادي للاختصارات عند الضغط مع الاستمرار على أيقونات التطبيقات في مشغّل التطبيقات)؟
وأي اختصارات يتم نشرها لغرض "مشاركة الهدف" هي أيضًا اختصار لمشغِّل التطبيقات، وستظهر في القائمة عند الضغط مع الاستمرار على رمز التطبيق. وينطبق الحد الأقصى لعدد الاختصارات لكل نشاط أيضًا على إجمالي عدد الاختصارات التي ينشرها التطبيق (مشاركة الأهداف واختصارات مشغّل التطبيقات القديمة مجمّعة).
ما هي الإرشادات حول عدد اختصارات المشاركة التي يجب نشرها على المستخدم.
يتم تقييد عدد اختصارات المشاركة بالحد نفسه من الاختصارات الديناميكية
المتاحة من خلال getMaxShortcutCountPerActivity(android.content.Context)
. ويمكن للمرء نشر أي رقم ضمن هذا الحد ولكن يجب أن تضع في اعتبارك أن اختصارات المشاركة يمكن أن تكون مرئية
عند الضغط مع الاستمرار في مشغّل التطبيقات وفي ورقة المشاركة. تعرض معظم مشغّلات التطبيقات عند الضغط مع الاستمرار أربعة أو خمسة اختصارات كحد أقصى في الوضع الرأسي وثمانية اختصارات في الوضع الأفقي. راجِع الأسئلة الشائعة هذه لمعرفة مزيد من التفاصيل والإرشادات حول مشاركة الاختصارات.