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

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

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

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

لمزيد من المعلومات عن أنواع 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، أنشئ intent وأضِف إضافات كما تفعل لاستدعاء قائمة مشاركة البيانات من 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

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

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