تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    val shareIntent = Intent.createChooser(sendIntent, null)
    context.startActivity(shareIntent)
}SharesheetSnippets.kt

يمكنك اختياريًا إضافة عناصر إضافية لتضمين المزيد من المعلومات، مثل مستلِمي البريد الإلكتروني (EXTRA_EMAIL, EXTRA_CC, EXTRA_BCC) وموضوع الرسالة الإلكترونية (EXTRA_SUBJECT) وما إلى ذلك.

ملاحظة: تتوقّع بعض تطبيقات البريد الإلكتروني، مثل Gmail، String[] لعناصر إضافية مثل EXTRA_EMAIL وEXTRA_CC. استخدِم putExtra(String, String[]) لإضافة هذه المعلومات إلى هدفك.

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

مشاركة البيانات الثنائية باستخدام الإجراء ACTION_SEND اضبط نوع MIME المناسب وأدرِج معرّف موارد منتظم (URI) للبيانات في الحقل الإضافي EXTRA_STREAM، كما هو موضّح في المثال التالي. يُستخدَم هذا النوع عادةً لمشاركة صورة، ولكن يمكن استخدامه لمشاركة أي نوع من المحتوى الثنائي.

fun shareBinaryContent(context: Context) {
    val shareIntent: Intent = Intent().apply {
        action = ACTION_SEND
        // Example: content://com.google.android.apps.photos.contentprovider/...
        val imageUri: Uri =
            Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1")
        putExtra(Intent.EXTRA_STREAM, imageUri)
        type = "image/jpeg"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}SharesheetSnippets.kt

يحتاج التطبيق المستلِم إلى إذن للوصول إلى البيانات التي يشير إليها 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 الرسمي لأنواع وسائط MIME.

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

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

fun shareMultiple(context: Context) {
    val imageUris: ArrayList<Uri> = arrayListOf(
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1"),
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/2")
    )

    val shareIntent = Intent().apply {
        action = Intent.ACTION_SEND_MULTIPLE
        putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris)
        type = "image/*"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}SharesheetSnippets.kt

تأكَّد من أنّ عناصر Uri المقدَّمة تشير إلى بيانات يمكن للتطبيق المستلِم الوصول إليها.

إضافة محتوى وافٍ إلى معاينات النصوص

اعتبارًا من نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، تعرض "قائمة مشاركة البيانات" من Android معاينة للنص الذي تتم مشاركته. في بعض الحالات، قد يصعب فهم النص الذي تتم مشاركته. ننصحك بمشاركة عنوان URL معقّد، مثل https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. يمكن أن يطمئن المستخدمون بشأن المحتوى الذي تتم مشاركته عند عرض معاينة أكثر تفصيلاً.

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

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

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

fun richContentToTextPreviewShares(context: Context) {
    val share = Intent.createChooser(
        Intent().apply {
            action = 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 =
                Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/A123456789")
            flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
        },
        null
    )
    context.startActivity(share)
}SharesheetSnippets.kt

تبدو المعاينة على النحو التالي:

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

لقطة شاشة للإجراءات المخصّصة في قائمة مشاركة البيانات من Android

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

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

fun sharesheetCustomActions(context: Context, previewText: String) {
    val sendIntent = Intent(ACTION_SEND)
        .setType("text/plain")
        .putExtra(Intent.EXTRA_TEXT, previewText)
    val shareIntent = Intent.createChooser(sendIntent, null)
    val customActions = arrayOf(
        ChooserAction.Builder(
            Icon.createWithResource(context, R.drawable.ic_logo),
            "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)
}SharesheetSnippets.kt

إضافة استهدافات مخصّصة

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

أضِف Intent.EXTRA_CHOOSER_TARGETS وIntent.EXTRA_INITIAL_INTENTS إلى Intent المشاركة بعد استدعاء Intent.createChooser():

val share = Intent.createChooser(shareIntent, null).apply {
    putExtra(
        Intent.EXTRA_CHOOSER_TARGETS,
        arrayOf(chooserTargetJessica, chooserTargetSpyros)
    )
    putExtra(
        Intent.EXTRA_INITIAL_INTENTS,
        arrayOf(intentTargetNearbyShare, intentTargetMaps)
    )
}SharesheetSnippets.kt

يُرجى استخدام هذه الميزة بحذر. يؤدي كل Intent وChooserTarget مخصّصَين تضيفهما إلى تقليل العدد الذي يقترحه النظام. ننصح بشكل عام بعدم إضافة استهدافات مخصّصة. من الأمثلة الشائعة والمناسبة على إضافة Intent.EXTRA_INITIAL_INTENTS توفير إجراءات إضافية يمكن للمستخدمين اتّخاذها بشأن المحتوى المشترَك. على سبيل المثال، يشارك المستخدم صورًا ويتم استخدام Intent.EXTRA_INITIAL_INTENTS للسماح له بإرسال رابط بدلاً من ذلك. من الأمثلة الشائعة والمناسبة لإضافة Intent.EXTRA_CHOOSER_TARGETS عرض الأشخاص أو الأجهزة ذات الصلة التي يوفّرها تطبيقك.

استبعاد استهدافات معيّنة حسب المكوّن

يمكنك استبعاد أهداف معيّنة من خلال تقديم Intent.EXTRA_EXCLUDE_COMPONENTS. يجب إجراء ذلك فقط لإزالة الاستهدافات التي يمكنك التحكّم فيها. من حالات الاستخدام الشائعة إخفاء أهداف المشاركة في تطبيقك عندما يشارك المستخدمون من داخل تطبيقك، لأنّ هدفهم على الأرجح هو المشاركة خارج تطبيقك.

أضِف Intent.EXTRA_EXCLUDE_COMPONENTS إلى نيتك بعد طلب Intent.createChooser():

fun excludeSpecificTargets(context: Context) {
    val share = Intent.createChooser(Intent(ACTION_SEND), null).apply {
        // Only use for components you have control over
        val excludedComponentNames =
            arrayOf(ComponentName("com.example.android", "ExampleClass"))
        putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames)
    }
    context.startActivity(share)
}SharesheetSnippets.kt

قد يكون من المفيد معرفة متى يشارك المستخدمون المحتوى والهدف الذي يختارونه. تتيح لك قائمة مشاركة البيانات من Android الحصول على هذه المعلومات من خلال توفير ComponentName للأهداف التي يختارها المستخدمون باستخدام IntentSender.

أنشئ أولاً PendingIntent لـ BroadcastReceiver وقدِّم IntentSender في Intent.createChooser():

fun infoAboutSharing(context: Context, requestCode: Int) {
    var share = Intent(ACTION_SEND)
    // ...
    val pi = PendingIntent.getBroadcast(
        context, requestCode,
        Intent(context, ShareBroadcastReceiver::class.java),
        PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
    )
    share = Intent.createChooser(share, null, pi.intentSender)
    context.startActivity(share)
}SharesheetSnippets.kt

تلقّي معاودة الاتصال في MyBroadcastReceiver والبحث في Intent.EXTRA_CHOOSER_RESULT:

override fun onReceive(context: Context?, intent: Intent) {
    val TAG = ShareBroadcastReceiver::class.simpleName
    val chooserResult: ChooserResult? = IntentCompat.getParcelableExtra(
        intent,
        Intent.EXTRA_CHOOSER_RESULT,
        ChooserResult::class.java,
    )
    chooserResult?.let {
        Log.i(TAG,
            "Share callback: isShortcut: ${it.isShortcut}, type: ${typeToString(it.type)}, componentName: ${it.selectedComponent}",
        )
    } ?: Log.i(TAG, "chooserResult is null")
}ShareBroadcastReceiver.kt

يمكنك الاطّلاع على نموذج مشاركة المنصة للحصول على مزيد من المعلومات:

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

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

fun customActions(context: Context, text: String) {
    val sendIntent = 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_logo),
            "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)
}SharesheetSnippets.kt

استخدام أداة حلّ الأهداف في Android

لقطة شاشة لـ ACTION_SEND أداة حلّ الأهداف

يُفضّل استخدام أداة حلّ الأهداف في Android عند إرسال البيانات إلى تطبيق آخر كجزء من مسار مهام محدّد جيدًا.

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

إذا كانت هناك عدة تطبيقات مثبَّتة تتضمّن فلاتر تتطابق مع ACTION_SEND ونوع MIME، يعرض النظام مربّع حوار لإزالة الغموض يُسمى محلّل الأهداف يتيح للمستخدم اختيار هدف للمشاركة. إذا تطابق تطبيق واحد، سيتم تشغيله.

في ما يلي مثال على كيفية استخدام أداة تحليل الأهداف في Android لإرسال نص:

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

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

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

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

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

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

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

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

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

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

إضافة محتوى وافٍ إلى معاينات النصوص

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

إضافة استهدافات مخصّصة

استبعاد استهدافات معيّنة حسب المكوّن

الحصول على معلومات حول المشاركة

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

استخدام أداة حلّ الأهداف في Android

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

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