دریافت داده از برنامه‌های دیگر

همان‌طور که برنامه می‌تواند داده‌ها را به برنامه‌های دیگر ارسال کند، می‌تواند داده‌ها را از برنامه‌های دیگر نیز دریافت کند. به نحوه تعامل کاربران با برنامه‌تان و انواع داده‌هایی که می‌خواهید از برنامه‌های دیگر دریافت کنید فکر کنید. برای مثال، یک برنامه شبکه اجتماعی ممکن است بخواهد محتوای نوشتاری، مانند یک نشانی وب جالب، را از برنامه دیگری دریافت کند.

در برنامه‌ای که از «ناوبری Compose» استفاده می‌کند، دریافت داده‌های ارسالی از برنامه دیگر یک فرایند سه‌مرحله‌ای است:

1. اعلام <intent-filter> در مانیفست: همچنان باید فیلتر هدف را به فعالیتتان در فایل AndroidManifest.xml اضافه کنید. این کار به سیستم عامل Android می‌گوید که برنامه شما می‌تواند کنش‌های خاص (مثل ACTION_SEND) و انواع رسانه (مثل text/plain) را دریافت کند.

2. یک navDeepLink در نمودار Compose Navigation خود تعریف کنید: یک navDeepLink که با کنش و نوع MIME مطابقت دارد مستقیماً به مقصد قابل‌ترکیب که باید محتوا را نمایش دهد پیوست کنید. NavController به‌طور خودکار قصد ورودی را رهگیری می‌کند و کاربر را مستقیماً به آن صفحه هدایت می‌کند.

3. استخراج بار داده‌های ورودی: در صفحه مقصد، به intent extras (مانند EXTRA_TEXT یا EXTRA_STREAM) دسترسی پیدا کنید تا محتوای هم‌رسانی‌شده را بازیابی کنید و وضعیت میانای کاربر را به‌روز کنید.

هدف‌های «هم‌رسانی مستقیم» پیوندهای عمیقی به فعالیت خاصی در برنامه شما هستند. این هدف‌ها اغلب نشان‌دهنده شخص یا گروهی هستند و «برگه هم‌رسانی Android» آن‌ها را نشان می‌دهد. برای مثال، برنامه پیام‌رسانی می‌تواند هدف «هم‌رسانی مستقیم» را برای فردی که مستقیماً به مکالمه با آن فرد پیوند عمیق می‌دهد ارائه دهد. برای دستورالعمل‌های دقیق، به ارائه اهداف «هم‌رسانی مستقیم» مراجعه کنید.

پشتیبانی از انواع MIME

در حالت ایده‌آل، یک برنامه باید بتواند گسترده‌ترین محدوده ممکن از انواع MIME را دریافت کند. برای مثال، برنامه پیام‌رسانی که برای ارسال نوشتار، تصویر، و ویدیو طراحی شده است به‌طور ایده‌آل از دریافت text/*، image/*، و video/* پشتیبانی می‌کند. در اینجا چند نوع MIME رایج برای ارسال و دریافت داده در Android آورده شده است.

دفتر ثبت رسمی IANA برای انواع رسانه MIME را ببینید.

هدف‌های هم‌رسانی عالی ایجاد کنید

وقتی کاربران روی هدف هم‌رسانی مرتبط با فعالیت خاصی تک‌ضرب می‌زنند، به آن‌ها اجازه دهید محتوای هم‌رسانی‌شده را قبل‌از اینکه برنامه‌تان از آن استفاده کند تأیید و ویرایش کنند. این امر به‌ویژه برای داده‌های نوشتاری اهمیت دارد.

دریافت داده در برنامه

دریافت داده‌های هم‌رسانی‌شده در برنامه‌ای که از Compose استفاده می‌کند شامل اعلام فیلترهای هدف در مانیفست، مسیریابی هدف‌های ورودی به صفحه مناسب با پیوندهای عمیق، و استخراج بار مفید از هدف برای به‌روزرسانی واسط کاربر است.

به‌روزرسانی مانیفست

فیلترهای قصد به سیستم اطلاع می‌دهند که مؤلفه برنامه کدام قصدها را می‌پذیرد. مشابه روشی که در درس ارسال داده به برنامه‌های دیگر با کنش ACTION_SEND هدف ایجاد کردید، فیلترهای هدف را برای دریافت اهداف با این کنش ایجاد می‌کنید. فیلتر قصد را در مانیفست بااستفاده از عنصر <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>

وقتی برنامه دیگری تلاش می‌کند هریک از این موارد را با ساختن هدف و ارسال آن به startActivity() هم‌رسانی کند، برنامه شما به‌عنوان گزینه‌ای در «برگ هم‌رسانی 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 با کنش و نوع رسانه هدف ورودی مطابقت دارد تا به صفحه مقصد صحیح پیمایش کند. وقتی به آن مقصد رسیدید، گرداننده شما قصد را بررسی می‌کند تا تعیین کند کدام محموله دریافت شده است (مانند یک تصویر تکی در مقابل چندین تصویر) و موارد اضافی مربوطه را استخراج می‌کند.

مدیریت محتوای ورودی

برای بازیابی محتوای ارائه‌شده توسط Intent، فعالیت فعلی را از LocalActivity.current در composable خود بخوانید، سپس 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

هنگام استخراج داده‌های باینری یا نشانی‌های وب از موارد اضافی هدف (مثل EXTRA_STREAM)، از IntentCompat.getParcelableExtra() یا IntentCompat.getParcelableArrayListExtra() از کتابخانه AndroidX Core، همان‌طور که در توابع handleSendImage و handleSendMultipleImages قبلی نشان داده شده است، استفاده کنید. ‫Android 13 (میانای برنامه‌سازی کاربردی سطح ۳۳) روش بدون پارامتر Intent.getParcelableExtra(String) را به‌نفع روش‌های نوع امن که نوع کلاس موردانتظار را می‌گیرند منسوخ می‌کند.

به‌روزرسانی واسط کاربر پس‌از دریافت داده‌ها می‌تواند به‌سادگی به‌روزرسانی وضعیت برای پر کردن TextField یا به‌پیچیدگی اعمال فیلتر روی تصویر باشد. اینکه بعداً چه اتفاقی می‌افتد به برنامه شما بستگی دارد.

هم‌رسانی نشانی وب نماگرفت

هنگام گرفتن نماگرفت، می‌توانید نماگرفت و هر نشانی وب مرتبط را هم‌رسانی کنید. این کار تجربه کاربری غنی‌تری را ارائه می‌دهد. هنگام دریافت نشانی وب، حتماً فیلد 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» و حل‌کننده هدف نمایش داده می‌شود. هر دو در مانیفست تعریف شده‌اند. می‌توانید برچسب‌های فیلتر قصد یا فعالیت را تنظیم کنید تا بافت بیشتری ارائه دهید.

از Android 10 (سطح API ‏۲۹)، «برگه هم‌رسانی Android» فقط از نمادهای تنظیم‌شده در مانیفست روی برچسب application شما استفاده می‌کند. Android نمادهای تنظیم‌شده در برچسب‌های intent-filter و activity را نادیده می‌گیرد.

دریافت محتوای غنی

درحالی‌که ACTION_SEND هدف امکان دریافت داده از «برگ هم‌رسانی Android» و حل‌کننده هدف را در سطح فعالیت یا پیمایش فراهم می‌کند، برنامه‌ها همچنین می‌توانند محتوای غنی (مثل تصاویر، ویدیوها، فایل‌های صوتی، و نوشتار سبک‌دار) را ازطریق تعامل‌های مستقیم با رابط کاربری دریافت کنند. این سازوکارها شامل موارد زیر می‌شود:

• جای‌گذاری از بریده‌دان (منوی لمس کردن و نگه داشتن)
• درج مستقیم رسانه از صفحه‌کلید نرم‌افزاری (IME)، مانند برچسب‌ها یا گیف‌ها
• کشیدن و رها کردن محتوا از برنامه دیگری در حالت چندپنجره‌ای یا صفحهٔ دونیمه

در «واسط‌های کاربر مبتنی بر نما»، Android 12 (میانای برنامه‌سازی کاربردی سطح ۳۱) و AndroidX Core 1.7 میانای برنامه‌سازی کاربردی یکپارچه OnReceiveContentListener را معرفی می‌کنند. این شنونده، مدیریت محتوا را از کلیپ‌بورد، صفحه‌کلید، و کشیدن و رها کردن در یک فراخوانی برگشتی واحد ادغام می‌کند. برای دستورالعمل‌های دقیق درباره پیاده‌سازی این ویژگی در «نماها»، به دریافت محتوای غنی مراجعه کنید.

در Jetpack Compose، می‌توانید دریافت محتوای غنی درج‌شده در عناصر میانای کاربر (مثل فیلدهای نوشتاری) را بااستفاده از اصلاح‌گر Modifier.contentReceiver یا اصلاح‌گرهای کشیدن و رها کردن مدیریت کنید.