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

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

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

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

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

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

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

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

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

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

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

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

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

KotlinJava
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، باسم كما هو موضح في المثال التالي. ويُستخدَم هذا الإجراء عادةً لمشاركة صورة، ولكن يمكن استخدامه لمشاركة أي نوع من المحتوى الثنائي.

KotlinJava
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 للفيديوهات والصوت والصور. ومع ذلك، اعتبارًا من الإصدار 3.0 من Android (المستوى 11 من واجهة برمجة التطبيقات)، يمكنه أيضًا تخزين أنواع غير الوسائط. لمزيد من المعلومات، يُرجى الاطّلاع على MediaStore.Files. يمكن إدراج الملفات في MediaStore باستخدام scanFile()، بعد ذلك يتم تمرير Uri بأسلوب content:// مناسب للمشاركة إلى onScanCompleted() المقدَّمة. يُرجى العِلم أنّه بعد إضافة المحتوى إلى النظام MediaStore، يمكن الوصول إليه باستخدام أي تطبيق على الجهاز.

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

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

تسجيل المستلمين لـ إرسال المرسلين
text/*
  • text/plain
  • text/rtf
  • text/html
  • text/json
`image/*`
  • image/jpg
  • image/png
  • image/gif
video/*
  • video/mp4
  • video/3gp
امتدادات الملفات المتوافقة application/pdf

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

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

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

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

KotlinJava
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 معاينة للنص الذي تتم jegoمشاركة. في بعض الحالات، قد يكون من الصعب فهم النص الذي تتم مشاركته. ننصحك بمشاركة عنوان URL معقد مثل https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. المعاينة لطمأنة المستخدمين بما تتم مشاركته.

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

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

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

KotlinJava
 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.

KotlinJava
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 المشاركة بعد استدعاء Intent.createChooser():

KotlinJava
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():

KotlinJava
  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():

KotlinJava
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:

KotlinJava
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);
}

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

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

KotlinJava
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 لإرسال نص:

KotlinJava
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);

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

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