إرسال بيانات بسيطة إلى تطبيقات أخرى

يستخدم Android الأهداف والعناصر الإضافية المرتبطة بها للسماح للمستخدمين بمشاركة المعلومات بسرعة بسهولة باستخدام تطبيقاتهم المفضلة.

يوفّر Android طريقتَين للمستخدمين لمشاركة البيانات بين التطبيقات:

• تم تصميم "قائمة مشاركة البيانات" من Android في المقام الأول لإرسال المحتوى إلى خارج تطبيقك و/أو بشكل مباشر. إلى مستخدم آخر. على سبيل المثال، مشاركة عنوان URL مع صديق.
• يُعد برنامج حل النية بالشراء من Android هو الأنسب لتمرير البيانات إلى المرحلة التالية من مهمة محددة جيدًا. على سبيل المثال، عند فتح ملف PDF من تطبيقك والسماح للمستخدمين واختيار العارض المفضل لديهم.

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

مميزات استخدام "قائمة مشاركة البيانات من Android"

ننصح بشدة باستخدام "قائمة مشاركة البيانات" في Android لتحقيق الاتساق بين المستخدمين على جميع التطبيقات. عدم عرض قائمة أهداف المشاركة الخاصة بتطبيقك أو إنشاء قائمة خاصة بك الصيغ المختلفة لورقة المشاركة.

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

تتضمّن صفحة المشاركة في Android أيضًا العديد من الميزات المفيدة للمطوّرين. على سبيل المثال، يمكنك قم بما يلي:

• معرفة متى يكمل المستخدمون عملية المشاركة ومكانها
• إضافة ChooserTarget مخصّصة واستهدافات التطبيقات
• توفير معاينات للمحتوى النصي المنسّق، بدءًا من Android 10 (المستوى 29 من واجهة برمجة التطبيقات)
• استبعاد الأهداف التي تتطابق مع أسماء مكوّنات معيّنة

استخدام "قائمة مشاركة البيانات" من Android

بالنسبة إلى جميع أنواع المشاركة، أنشئ هدفًا واضبط الإجراء على Intent.ACTION_SEND لعرض "قائمة مشاركة البيانات" من Android، اتصل Intent.createChooser(), وتمريره كائن Intent. ويعرض هذا النموذج نسخة من الغرض الذي يعرض دائمًا "قائمة مشاركة البيانات من Android".

إرسال محتوى نصي

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

val sendIntent: Intent = Intent().apply {
    action = Intent.ACTION_SEND
    putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
    type = "text/plain"
}

val shareIntent = Intent.createChooser(sendIntent, null)
startActivity(shareIntent)

Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send.");
sendIntent.setType("text/plain");

Intent shareIntent = Intent.createChooser(sendIntent, null);
startActivity(shareIntent);

يمكنك، إذا شئت، إدراج عناصر إضافية لتضمين المزيد من المعلومات، مثل مستلمي الرسائل الإلكترونية. (EXTRA_EMAIL، EXTRA_CC, EXTRA_BCC)، موضوع رسالة البريد الإلكتروني (EXTRA_SUBJECT) وغير ذلك

ملاحظة: تتوقع بعض تطبيقات البريد الإلكتروني، مثل Gmail، String[] للحصول على مزايا إضافية مثل "EXTRA_EMAIL" و"EXTRA_CC" استخدام putExtra(String, String[]) لإضافتها إلى هدفك.

إرسال محتوى ثنائي

مشاركة البيانات الثنائية باستخدام الإجراء ACTION_SEND عليك ضبط نوع MIME المناسب ووضع معرّف موارد منتظم (URI) للبيانات في EXTRA_STREAM، باسم كما هو موضح في المثال التالي. ويشيع استخدامه لمشاركة صورة، ولكن يمكن استخدامه لمشاركة أي نوع من المحتوى الثنائي.

val shareIntent: Intent = Intent().apply {
    action = Intent.ACTION_SEND
    // Example: content://com.google.android.apps.photos.contentprovider/...
    putExtra(Intent.EXTRA_STREAM, uriToImage)
    type = "image/jpeg"
}
startActivity(Intent.createChooser(shareIntent, null))

Intent shareIntent = new Intent();
shareIntent.setAction(Intent.ACTION_SEND);
// Example: content://com.google.android.apps.photos.contentprovider/...
shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage);
shareIntent.setType("image/jpeg");
startActivity(Intent.createChooser(shareIntent, null));

يحتاج تطبيق الاستلام إلى إذن للوصول إلى بيانات Uri. ويشير إليه. هناك طريقتان مقترحتان للقيام بذلك:

• يمكنك تخزين البيانات في ContentProvider الخاص بك، مع التأكد من عدم تضمين أي امتلاك الإذن الصحيح للوصول إلى مقدّم الخدمة. الآلية المفضلة لتوفير الوصول إليها هو استخدام أذونات حسب عنوان URI، وهي مؤقتة وتمنح إمكانية الدخول إلى التطبيق المستلم فقط. هناك طريقة سهلة لإنشاء ContentProvider مثل هذه هي استخدام صف مساعد واحد (FileProvider).
• استخدِم النظام MediaStore. MediaStore مخصصة بشكل أساسي لأنواع الفيديو والصوت والصور بتنسيق MIME. ومع ذلك، بدءًا من Android 3.0 (واجهة برمجة التطبيقات المستوى 11)، بل يمكنها أيضًا تخزين أنواع غير الوسائط. لمزيد من المعلومات، يُرجى مراجعة MediaStore.Files يمكن إدراج الملفات في MediaStore باستخدام scanFile(), وبعد ذلك Uri بنمط content:// المناسبة للمشاركة يتم تمريرها إلى المقدم onScanCompleted() معاودة الاتصال. يُرجى ملاحظة أنّه بعد إضافة المحتوى إلى النظام MediaStore، يمكن أي تطبيق على الجهاز.

استخدام نوع MIME الصحيح

تقديم نوع MIME الأكثر تحديدًا للبيانات التي الإرسال. على سبيل المثال، يمكنك استخدام text/plain عند مشاركة نص عادي. إليك بعض الأمثلة أنواع MIME الشائعة عند إرسال بيانات بسيطة في Android:

لمزيد من المعلومات حول أنواع MIME، يُرجى مراجعة هيئة أرقام الإنترنت المخصصة (IANA) السجلّ الرسمي لأنواع وسائط MIME

قد تعرض "قائمة المشاركة في Android" معاينة للمحتوى، استنادًا إلى نوع MIME الذي تم تقديمه. بعض الإشعارات تتوفّر ميزات المعاينة لأنواع معيّنة فقط.

مشاركة عدة أجزاء من المحتوى

لمشاركة عدة أجزاء من المحتوى، استخدِم ACTION_SEND_MULTIPLE. مع قائمة معرفات الموارد المنتظمة (URI) التي تشير إلى المحتوى. يختلف نوع MIME وفقًا من المحتوى الذي تشاركه. على سبيل المثال، إذا شاركت ثلاث صور بتنسيق JPEG، فإنك تستخدم النوع "image/jpg" بالنسبة إلى مزيج من أنواع الصور، استخدِم "image/*" لمطابقة نشاط معالجة أي نوع من الصور. وفي حين أنه من الممكن مشاركة مزيج من الأنواع، فإننا نحرص على عدم تشجيع ذلك، لأنه عدم وضوح ما سيتم إرساله إلى المُستلِم إذا كان من الضروري إرسال أنواع متعددة، استخدم "*/*" يعود الأمر إلى تطبيق الاستلام في تحليل بياناتك ومعالجتها. وفي ما يلي مثال لذلك:

val imageUris: ArrayList<Uri> = arrayListOf(
        // Add your image URIs here
        imageUri1,
        imageUri2
)

val shareIntent = Intent().apply {
    action = Intent.ACTION_SEND_MULTIPLE
    putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris)
    type = "image/*"
}
startActivity(Intent.createChooser(shareIntent, null))

ArrayList<Uri> imageUris = new ArrayList<Uri>();
imageUris.add(imageUri1); // Add your image URIs here
imageUris.add(imageUri2);

Intent shareIntent = new Intent();
shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE);
shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris);
shareIntent.setType("image/*");
startActivity(Intent.createChooser(shareIntent, null));

تأكَّد من أنّ عناصر Uri المقدّمة تشير إلى البيانات التي يمكن لأي تطبيق مستلم الوصول إليها.

إضافة محتوى وافٍ إلى معاينات النص

بدءًا من نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، تعرض "قائمة مشاركة البيانات" في Android معاينة للنص مشاركة البيانات. في بعض الحالات، قد يكون من الصعب فهم النص الذي تتم مشاركته. ننصحك بمشاركة عنوان URL معقدًا مثل https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. المعاينة لطمأنة المستخدمين بما تتم مشاركته.

إذا كنت تعاين النص، يمكنك ضبط عنوان أو صورة مصغّرة أو كليهما. إضافة وصف إلى يُرجى Intent.EXTRA_TITLE قبل الاتصال بـ Intent.createChooser()، وإضافة صورة مصغّرة ذات صلة باستخدام ClipData.

ملاحظة: يتم توفير معرِّف الموارد المنتظم (URI) لمحتوى الصورة من FileProvider، عادةً من <cache-path> تم إعداده. لمزيد من المعلومات، يُرجى الاطّلاع على مشاركة الملفات. تأكد من إعطاء يمكنك مشاركة الأذونات المناسبة لقراءة أي صورة تريد استخدامها كصورة مصغّرة. لمزيد من المعلومات يمكنك الاطّلاع على Intent.FLAG_GRANT_READ_URI_PERMISSION.

وفي ما يلي مثال لذلك:

 val share = Intent.createChooser(Intent().apply {
      action = Intent.ACTION_SEND
      putExtra(Intent.EXTRA_TEXT, "https://developer.android.com/training/sharing/")

      // (Optional) Here you're setting the title of the content
      putExtra(Intent.EXTRA_TITLE, "Introducing content previews")

      // (Optional) Here you're passing a content URI to an image to be displayed
      data = contentUri
      flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
  }, null)
  startActivity(share)

Intent sendIntent = new Intent(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, "https://developer.android.com/training/sharing/");

// (Optional) Here you're setting the title of the content
sendIntent.putExtra(Intent.EXTRA_TITLE, "Introducing content previews");

// (Optional) Here you're passing a content URI to an image to be displayed
sendIntent.setData(contentUri);
sendIntent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);

// Show the Sharesheet
startActivity(Intent.createChooser(sendIntent, null));

تبدو المعاينة كما يلي:

إضافة إجراءات مخصصة إلى ورقة المشاركة

لقطة شاشة للإجراءات المخصّصة في "قائمة مشاركة البيانات" من Android.

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

لإضافة إجراءات مخصصة في "قائمة مشاركة البيانات" في Android، عليك أولاً إنشاء ChooserAction مع ChooserAction.Builder ويمكنك تحديد "PendingIntent" كالإجراء الذي تم استدعاءه عند النقر على الرمز. إنشاء المحتوى مصفوفة تحتوي على جميع الإجراءات المخصصة وتحديدها على أنها EXTRA_CHOOSER_CUSTOM_ACTIONS من الحصة Intent.

val sendIntent = Intent(Intent.ACTION_SEND)
    .setType("text/plain")
    .putExtra(Intent.EXTRA_TEXT, text)
val shareIntent = Intent.createChooser(sendIntent, null)
val customActions = arrayOf(
    ChooserAction.Builder(
        Icon.createWithResource(context, R.drawable.ic_custom_action),
        "Custom",
        PendingIntent.getBroadcast(
            context,
            1,
            Intent(Intent.ACTION_VIEW),
            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
        )
    ).build()
)
shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
context.startActivity(shareIntent)

Intent sendIntent = new Intent(Intent.ACTION_SEND)
        .setType("text.plain")
        .putExtra(Intent.EXTRA_TEXT, text);
Intent shareIntent = Intent.createChooser(sendIntent, null);
ChooserAction[] actions = new ChooserAction[]{
        new ChooserAction.Builder(
                Icon.createWithResource(context, R.drawable.ic_custom_action),
                "Custom",
                PendingIntent.getBroadcast(
                        context,
                        1,
                        new Intent(Intent.ACTION_VIEW),
                        PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_CANCEL_CURRENT
                )
        ).build()
};
shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, actions);
context.startActivity(shareIntent);

إضافة استهدافات مخصّصة

تتيح لك "قائمة مشاركة البيانات من Android" تحديد ما يصل إلى كائنَين ChooserTarget تظهر قبل اختصارات المشاركة وأهداف المنتقي التي يتم تحميلها من ChooserTargetServices. يمكنك أيضًا تحديد ما يصل إلى هدفين يشيران إلى الأنشطة المدرجة قبل اقتراحات التطبيق:

إضافة Intent.EXTRA_CHOOSER_TARGETS وIntent.EXTRA_INITIAL_INTENTS إلى نية المشاركة بعد الاتصال Intent.createChooser():

val share = Intent.createChooser(myShareIntent, null).apply {
    putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray)
    putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray)
}

Intent shareIntent = Intent.createChooser(sendIntent, null);
share.putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray);
share.putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray);

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

استبعاد أهداف معينة حسب المكون

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

إضافة Intent.EXTRA_EXCLUDE_COMPONENTS إلى هدفك بعد الاتصال بالرقم Intent.createChooser():

  val share = Intent.createChooser(Intent(), null).apply {
    // Only use for components you have control over
    val excludedComponentNames = arrayOf(ComponentName("com.example.android", "ExampleClass"))
    putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames)
  }

  Intent shareIntent = Intent.createChooser(new Intent(), null);
  // Only use for components you have control over
  ComponentName[] excludedComponentNames = {
          new ComponentName("com.example.android", "ExampleClass")
  };
  shareIntent.putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames);

الحصول على معلومات حول المشاركة

قد يكون من المفيد معرفة الوقت الذي يشارك فيه المستخدمون المحتوى والهدف الذي يختارونه. تشير رسالة الأشكال البيانية تتيح لك Android Sharesheet الحصول على هذه المعلومات من خلال توفير ComponentName تستهدف المستخدمين الذين يختارهم باستخدام IntentSender.

عليك أولاً إنشاء PendingIntent لـ "BroadcastReceiver" وتوفيره. IntentSender في Intent.createChooser():

var share = Intent(Intent.ACTION_SEND)
// ...
val pi = PendingIntent.getBroadcast(
    myContext, requestCode,
    Intent(myContext, MyBroadcastReceiver::class.java),
    PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
)
share = Intent.createChooser(share, null, pi.intentSender)

Intent share = new Intent(ACTION_SEND);
...
PendingIntent pi = PendingIntent.getBroadcast(myContext, requestCode,
        new Intent(myContext, MyBroadcastReceiver.class),
        PendingIntent.FLAG_MUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
share = Intent.createChooser(share, null, pi.getIntentSender());

تلقّي معاودة الاتصال خلال MyBroadcastReceiver ومراجعة Intent.EXTRA_CHOSEN_COMPONENT:

override fun onReceive(context: Context, intent: Intent) {
  ...
  val clickedComponent : ComponentName = intent.getParcelableExtra(EXTRA_CHOSEN_COMPONENT);
}

@Override public void onReceive(Context context, Intent intent) {
  ...
  ComponentName clickedComponent = intent.getParcelableExtra(EXTRA_CHOSEN_COMPONENT);
}

إضافة إجراءات مخصصة إلى ورقة المشاركة

في نظام التشغيل Android 14 (المستوى 34 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن للتطبيقات إضافة إجراءات مخصَّصة إلى "قائمة مشاركة البيانات" من Android. إنشاء ChooserAction مع ChooserAction.Builder ويمكنك تحديد "PendingIntent" كالإجراء الذي تم استدعاءه عند النقر على الرمز. إنشاء المحتوى مصفوفة تحتوي على جميع الإجراءات المخصصة وتحديدها على أنها EXTRA_CHOOSER_CUSTOM_ACTIONS من الحصة Intent.

val sendIntent = Intent(Intent.ACTION_SEND)
    .setType("text/plain")
    .putExtra(Intent.EXTRA_TEXT, text)
val shareIntent = Intent.createChooser(sendIntent, null)
val customActions = arrayOf(
    ChooserAction.Builder(
        Icon.createWithResource(context, R.drawable.ic_custom_action),
        "Custom",
        PendingIntent.getBroadcast(
            context,
            1,
            Intent(Intent.ACTION_VIEW),
            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
        )
    ).build()
)
shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
context.startActivity(shareIntent)

Intent sendIntent = new Intent(Intent.ACTION_SEND)
        .setType("text.plain")
        .putExtra(Intent.EXTRA_TEXT, text);
Intent shareIntent = Intent.createChooser(sendIntent, null);
ChooserAction[] actions = new ChooserAction[]{
        new ChooserAction.Builder(
                Icon.createWithResource(context, R.drawable.ic_custom_action),
                "Custom",
                PendingIntent.getBroadcast(
                        context,
                        1,
                        new Intent(Intent.ACTION_VIEW),
                        PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_CANCEL_CURRENT
                )
        ).build()
};
shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, actions);
context.startActivity(shareIntent);

استخدام برنامج تحديد الأهداف في Android

لقطة شاشة لأداة حلّ الأهداف "ACTION_SEND"

من الأفضل استخدام "أداة حل النية بالشراء" في Android عند إرسال البيانات إلى تطبيق آخر كجزء من تدفق مهمة محدد جيدًا.

لاستخدام أداة حل النية بالشراء من Android، أنشِئ هدفًا وأضِف المزيد كما تريد. "قائمة مشاركة البيانات" من Android. ومع ذلك، لا تتصل Intent.createChooser()

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

في ما يلي مثال على كيفية استخدام برنامج تحديد الأهداف في Android لإرسال رسالة نصية:

val sendIntent: Intent = Intent().apply {
    action = Intent.ACTION_SEND
    putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
    type = "text/plain"
}
startActivity(sendIntent)

Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send.");
sendIntent.setType("text/plain");
startActivity(sendIntent);

مزيد من المعلومات

لمزيد من المعلومات حول إرسال البيانات، راجع فلاتر الأهداف والغايات: