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

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

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

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

2. تحديد navDeepLink في الرسم البياني للتنقّل في Compose: بدلاً من اعتراض Intent وتحليله يدويًا داخل طريقتَي onCreate أو onNewIntent في النشاط، استخدِم ميزة الروابط المؤدية إلى صفحات في تطبيقك في Compose Navigation. أرفِق navDeepLink الذي يطابق الإجراء ونوع MIME مباشرةً بالوجهة القابلة للإنشاء التي يجب أن تعرض المحتوى. سيعترض NavController تلقائيًا على Intent ويوجه المستخدم مباشرةً إلى تلك الشاشة.

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

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

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

يُرجى الرجوع إلى سجلّ أنواع وسائط MIME الرسمي الخاص بمنظمة IANA.

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

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

تلقّي البيانات من خلال نشاط

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

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

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

<activity android:name=".ui.MyActivity" >
    <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()، يتم إدراج تطبيقك كخيار في ورقة المشاركة أو أداة حل intent في Android. إذا اختار المستخدم تطبيقك، سيبدأ النشاط المقابل (.ui.MyActivity في المثال السابق). ويعود إليك بعد ذلك أمر التعامل مع المحتوى بشكل مناسب ضمن الرمز وواجهة المستخدم.

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

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

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

@Composable
fun SharesheetHandler() {
    val context = LocalContext.current
    val intent = (context as? Activity)?.intent

    when (intent?.action) {
        ACTION_SEND -> {
            if ("text/plain" == intent.type) {
                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
        }
    }
}

fun handleSendText(intent: Intent) {
    intent.getStringExtra(Intent.EXTRA_TEXT)?.let {
        // Update ViewModel state to change state of text being shared
    }
}

fun handleSendImage(intent: Intent) {
    IntentCompat.getParcelableExtra(intent, Intent.EXTRA_STREAM, Uri::class.java).let {
        // Update ViewModel state to change state of image being shared
    }
}

fun handleSendMultipleImages(intent: Intent) {
    IntentCompat.getParcelableArrayListExtra(intent, Intent.EXTRA_STREAM, Uri::class.java).let {
        // Update ViewModel state to change state of image(s) being shared
    }
}
SharesheetSnippets.kt

يمكن أن يكون تعديل واجهة المستخدِم بعد تلقّي البيانات بسيطًا مثل ملء 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 ViewModel state to change state image being shared and the EXTRA_TEXT
    // if available
}
SharesheetSnippets.kt

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

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

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