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

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

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

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

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

مزايا استخدام "ورقة مشاركة Android"

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

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

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

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

استخدام ورقة مشاركة Android

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

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

إنّ الاستخدام الأكثر وضوحًا وشائعًا لتطبيق Android Sharesheet هو إرسال محتوى نصي من نشاط إلى آخر. على سبيل المثال، يمكن لمعظم المتصفحات مشاركة عنوان 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، راجع السجلّ الرسمي لأنواع وسائط MIME IANA.

قد تعرض Android Sharesheet معاينة للمحتوى استنادًا إلى نوع 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 Sharesheet معاينة للنص الذي تتم مشاركته. في بعض الحالات، قد يكون من الصعب فهم النص الذي تتم مشاركته. يمكنك مشاركة عنوان 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 Sharesheet

في نظام التشغيل 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 Sharesheet تحديد ما يصل إلى عنصرَين من 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" الحصول على هذه المعلومات من خلال توفير 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);

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

لمزيد من المعلومات حول إرسال البيانات، يمكنك الاطّلاع على فلاتر Intent وIntent.