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

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

يستخدم 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 إليه. يعرض ذلك إصدارًا من 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 للفيديوهات والمحتوى الصوتي والصور. ومع ذلك، بدءًا من Android 3.0 (المستوى 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، يُرجى الاطّلاع على سجلّ أنواع وسائط MIME الرسمي التابع لهيئة IANA.

قد تعرض "قائمة مشاركة البيانات من 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> تم ضبطه. لمزيد من المعلومات، يُرجى الاطّلاع على مشاركة الملفات. احرِص على منح "قائمة مشاركة البيانات" الأذونات المناسبة لقراءة أي صورة تريد استخدامها كصورة مصغّرة. لمزيد من المعلومات، يُرجى الاطّلاع على 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.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

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

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