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

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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)

Java

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

Kotlin

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

Java

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، يُرجى الاطّلاع على السجلّ الرسمي لأنواع وسائط MIME في IANA .

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

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

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

Kotlin

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

Java

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.

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

Kotlin

 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)

Java

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.

Kotlin

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)

Java

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

Kotlin

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

Java

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

Kotlin

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

Java

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

Kotlin

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)

Java

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:

Kotlin

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

Java

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

Kotlin

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)

Java

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

Kotlin

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

Java

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

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

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

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