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

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

يرسل مستخدمو التطبيقات الأخرى البيانات إلى تطبيقك بشكل متكرّر من خلال قائمة مشاركة البيانات من Android أو أداة حلّ الأهداف. يجب أن تحدّد التطبيقات التي ترسل البيانات إلى تطبيقك نوع MIME لهذه البيانات. يمكن لتطبيقك تلقّي البيانات التي يرسلها تطبيق آخر بالطرق التالية:

• Activity مع علامة intent-filter مطابقة في البيان
• اختصارات المشاركة التي نشرها تطبيقك

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

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

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

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

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

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

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

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

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

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

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

مشاركة عنوان 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 ومحلّل الأهداف في Android. يتم تحديد كليهما في ملف البيان. يمكنك ضبط تصنيفات فلاتر الأنشطة أو الأهداف لتوفير المزيد من السياق.

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