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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لمزيد من المعلومات عن أنواع MIME، يُرجى الاطّلاع على السجلّ الرسمي لأنواع وسائط MIME في IANA.

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

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

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

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

ملاحظة: يتم توفير عنوان URL لمحتوى الصورة من ملف FileProvider، وعادةً ما يكون من ملف <cache-path> تم ضبطه. لمزيد من المعلومات، يُرجى الاطّلاع على مشاركة الملفات. احرص على منح Sharesheet الأذونات المناسبة لقراءة أي صورة تريد استخدامها كصورة مصغّرة. لمزيد من المعلومات، يُرجى الاطّلاع على 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

في الإصدار 14 من نظام التشغيل Android (المستوى 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 المشاركة بعد استدعاء 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 الحصول على هذه المعلومات من خلال توفير 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);
}

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

في الإصدار 14 من نظام التشغيل Android (المستوى 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);

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

لمزيد من المعلومات عن إرسال البيانات، يُرجى الاطّلاع على المقصودات وفلاتر المقصودات.