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

يستخدم نظام التشغيل 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 المناسب، وضَع معرّف موارد منتظم (URI) للبيانات في الإضافة 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، يُرجى الاطّلاع على سجلّ IANA الرسمي لأنواع وسائط MIME.

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

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

لمشاركة عدة عناصر من المحتوى، استخدِم الإجراء ACTION_SEND_MULTIPLE مع قائمة بمعرّفات الموارد الموحّدة (URI) التي تشير إلى المحتوى. يختلف نوع 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 من واجهة برمجة التطبيقات)، تعرض &quot;ورقة المشاركة&quot; في Android معاينة للنص الذي تتم مشاركته. في بعض الحالات، قد يصعب فهم النص الذي تتم مشاركته. لنفترض أنّك تريد مشاركة عنوان 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.

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

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

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

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

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

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

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

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