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

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

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

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

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

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

برای بررسی داده‌های ورودی دقت بیشتری داشته باشید: ممکن است نوع 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 از موارد اضافی هدف (مانند 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)، مانند برچسب‌ها یا فایل‌های GIF
• کشیدن و رها کردن محتوا از برنامه دیگری در حالت چندپنجره‌ای یا صفحهٔ دونیمه

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

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