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

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

في التطبيقات التي تستخدم ميزة "التنقّل في Compose"، يتطلّب تلقّي البيانات المُرسَلة من تطبيق آخر ثلاث خطوات:

1. تحديد <intent-filter> في ملف البيان: يجب إضافة فلتر أهداف إلى النشاط في ملف AndroidManifest.xml. يُعلم ذلك نظام التشغيل Android بأنّ تطبيقك قادر على تلقّي إجراءات معيّنة (مثل ACTION_SEND) وأنواع MIME (مثل text/plain).

2. حدِّد navDeepLink في الرسم البياني للتنقّل في Compose: أرفِق navDeepLink يطابق الإجراء ونوع MIME مباشرةً بالوجهة القابلة للإنشاء التي من المفترض أن تعرض المحتوى. يعترض NavController الطلب الوارد تلقائيًا ويوجه المستخدم مباشرةً إلى تلك الشاشة.

3. استخراج حمولة بيانات واردة: في شاشة الوجهة، يمكنك الوصول إلى إضافات intent (مثل EXTRA_TEXT أو EXTRA_STREAM) لاسترداد المحتوى المشترَك وتعديل حالة واجهة المستخدم.

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

أنواع MIME المتوافقة

من الناحية المثالية، يجب أن يكون التطبيق قادرًا على تلقّي أكبر نطاق ممكن من أنواع MIME. على سبيل المثال، تطبيق المراسلة المصمَّم لإرسال النصوص والصور والفيديوهات يجب أن يتيح تلقّي text/* وimage/* وvideo/*. في ما يلي بعض أنواع MIME الشائعة لإرسال البيانات وتلقّيها في Android.

يمكنك الاطّلاع على سجلّ IANA الرسمي لأنواع وسائط MIME.

إنشاء أهداف مشاركة رائعة

عندما ينقر المستخدمون على هدف مشاركة مرتبط بنشاط معيّن، اسمح لهم بالتأكيد على المحتوى المشترَك وتعديله قبل أن يستخدمه تطبيقك. ويُعدّ ذلك مهمًا بشكل خاص للبيانات النصية.

تلقّي البيانات في تطبيقك

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

تعديل ملف البيان

تُعلم فلاتر Intent النظام بالأهداف التي يقبلها مكوِّن التطبيق. على غرار كيفية إنشاء intent باستخدام إجراء ACTION_SEND في درس إرسال البيانات إلى تطبيقات أخرى، يمكنك إنشاء intent filters لتلقّي intents باستخدام هذا الإجراء. يمكنك تحديد intent filter في ملف البيان باستخدام عنصر <intent-filter>. على سبيل المثال، إذا كان تطبيقك يتعامل مع تلقّي محتوى نصي، سيبدو البيان الذي يتضمّن صورة واحدة أو أكثر من أي نوع على النحو التالي:

<activity android:name=".ui.MyActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="image/*" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SEND_MULTIPLE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="image/*" />
    </intent-filter>
</activity>

عندما يحاول تطبيق آخر مشاركة أي من هذه العناصر من خلال إنشاء intent وتمريره إلى startActivity()، يتم إدراج تطبيقك كخيار في قائمة مشاركة البيانات من Android أو أداة حل الأهداف في Android. إذا اختار المستخدم تطبيقك، سيؤدي ذلك إلى بدء النشاط المقابل (.ui.MyActivity في المثال السابق). ويعود إليك بعد ذلك التعامل مع المحتوى بشكل مناسب ضمن الرمز وواجهة المستخدم.

تحديد رابط لصفحة معيّنة في الرسم البياني للتنقّل

في Compose Navigation، أرفِق navDeepLink مباشرةً بالوجهة القابلة للإنشاء التي يجب أن تعرض المحتوى. عندما يشارك تطبيق آخر بيانات تتطابق مع فلتر الأهداف، يوجّه Compose Navigation المستخدم مباشرةً إلى هذه الوجهة:

composable(
    route = "incoming_share",
    deepLinks = listOf(
        navDeepLink {
            action = Intent.ACTION_SEND
            mimeType = "text/plain"
        },
        navDeepLink {
            action = Intent.ACTION_SEND
            mimeType = "image/*"
        },
        navDeepLink {
            action = Intent.ACTION_SEND_MULTIPLE
            mimeType = "image/*"
        }
    )
) {
    SharesheetHandler()
}
SharesheetSnippets.kt

تتم المطابقة في navDeepLink استنادًا إلى الإجراء ونوع MIME للغرض الوارد من أجل الانتقال إلى شاشة الوجهة الصحيحة. بعد الوصول إلى هذا الوجهة، يفحص المعالج الغرض لتحديد الحمولة التي تم تلقّيها (مثل صورة واحدة مقابل صور متعددة) ويستخرج الإضافات المقابلة.

التعامل مع المحتوى الوارد

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

يجب توخّي الحذر الشديد عند التحقّق من البيانات الواردة، فقد يكون نوع MIME غير صحيح، أو قد تكون الصورة التي يتم إرسالها كبيرة جدًا. معالجة البيانات الثنائية أو عمليات الإدخال/الإخراج الكثيفة (مثل فك ترميز الصور الكبيرة أو كتابة الملفات) بشكل غير متزامن باستخدام الروتينات الفرعية (مثل Dispatchers.IO) بدلاً من سلسلة التعليمات الرئيسية لواجهة المستخدم

@Composable
fun SharesheetHandler() {
    val activity = LocalActivity.current
    val intent = activity?.intent

    when (intent?.action) {
        Intent.ACTION_SEND -> {
            if (intent.type == "text/plain") {
                handleSendText(intent) // Handle text being sent
            } else if (intent.type?.startsWith("image/") == true) {
                handleSendImage(intent) // Handle single image being sent
            }
        }

        Intent.ACTION_SEND_MULTIPLE -> {
            if (intent.type?.startsWith("image/") == true) {
                handleSendMultipleImages(intent) // Handle multiple images being sent
            }
        }

        else -> {
            // Handle other intents, such as being started from the home screen
        }
    }
}

private fun handleSendText(intent: Intent) {
    intent.getStringExtra(Intent.EXTRA_TEXT)?.let {
        // Update UI state with the shared text
    }
}

private fun handleSendImage(intent: Intent) {
    val imageUri = IntentCompat.getParcelableExtra(intent, Intent.EXTRA_STREAM, Uri::class.java)
    imageUri?.let {
        // Update UI state with the shared image
    }
}

private fun handleSendMultipleImages(intent: Intent) {
    val imageUris =
        IntentCompat.getParcelableArrayListExtra(intent, Intent.EXTRA_STREAM, Uri::class.java)
    imageUris?.let {
        // Update UI state with the shared images
    }
}
SharesheetSnippets.kt

عند استخراج بيانات ثنائية أو معرّفات موارد منتظمة (URI) من إضافات Intent (مثل EXTRA_STREAM)، استخدِم IntentCompat.getParcelableExtra() أو IntentCompat.getParcelableArrayListExtra() من مكتبة AndroidX Core، كما هو موضّح في الدالتَين handleSendImage وhandleSendMultipleImages السابقتَين. في الإصدار 13 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 33)، تم إيقاف طريقة Intent.getParcelableExtra(String) غير المحدَّدة المَعلمات نهائيًا واستبدالها بطرق منع أخطاء الكتابة التي تستخدم نوع الفئة المتوقَّع.

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

مشاركة عنوان URL للقطة الشاشة

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

IntentCompat.getParcelableExtra(intent, Intent.EXTRA_STREAM, Uri::class.java).let {
    // Handle the EXTRA_TEXT as well
    val extraText = intent.getCharSequenceExtra(Intent.EXTRA_TEXT)
    // Update UI state with the shared image and the EXTRA_TEXT if available
}
SharesheetSnippets.kt

التأكّد من أنّ المستخدمين يتعرّفون على تطبيقك

يتم تمثيل تطبيقك من خلال رمزه وتصنيفه في قائمة مشاركة البيانات من Android ومحلّل الأهداف. يتم تحديد كليهما في البيان. يمكنك ضبط تصنيفات فلاتر الأنشطة أو الأهداف لتوفير المزيد من السياق.

اعتبارًا من الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات)، لا تستخدم قائمة مشاركة البيانات من Android سوى الرموز التي تم ضبطها في ملف البيان ضمن العلامة application. يتجاهل نظام التشغيل Android الرموز التي تم ضبطها على العلامتَين intent-filter وactivity.

تلقّي محتوى وافٍ

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

• اللصق من الحافظة (قائمة النقر مع الاستمرار)
• إدراج الوسائط مباشرةً من لوحة المفاتيح الافتراضية (IME)، مثل الملصقات أو صور GIF
• سحب المحتوى وإفلاته من تطبيق آخر في وضع النوافذ المتعددة أو وضع تقسيم الشاشة

في واجهات المستخدم المستندة إلى العرض، يقدّم الإصدار Android 12 (المستوى 31 لواجهة برمجة التطبيقات) وAndroidX Core 1.7 واجهة برمجة التطبيقات الموحّدة OnReceiveContentListener. يجمع هذا المستمع بين معالجة المحتوى من الحافظة ولوحة المفاتيح والسحب والإفلات في استدعاء واحد. للحصول على تعليمات مفصّلة حول تنفيذ ذلك في "طرق العرض"، يُرجى الاطّلاع على تلقّي محتوى وافٍ.

في Jetpack Compose، يمكنك التعامل مع تلقّي المحتوى الوافي الذي يتم إدراجه في مكوّنات واجهة المستخدم (مثل حقول النص) باستخدام المُعدِّل Modifier.contentReceiver أو مُعدِّلات السحب والإفلات.