داده های ساده را از سایر برنامه ها دریافت کنید

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

In an app using Compose Navigation, receiving data sent by another app is a two-step process:

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

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

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

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

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

ثبت نام گیرندگان برای	فرستنده‌ها ارسال می‌کنند
text/*	text/plain text/rtf text/html text/json
image/*	image/jpg image/png image/gif
video/*	video/mp4 video/3gp
پسوندهای فایل پشتیبانی شده	application/pdf

Refer to the IANA official registry of MIME media types.

Caution: Although you can receive a MIME type of */* , we strongly discourage doing so unless your app is fully capable of handling any type of incoming content.

اهداف سهم بزرگی را تعیین کنید

When a user taps on a share target associated with a specific activity they should be able to confirm and edit the shared content before using it. This is especially important for text data.

دریافت داده‌ها با یک فعالیت

Receiving data with an activity involves updating your manifest, handling the incoming content, and ensuring that the user recognizes your app.

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

فیلترهای Intent به سیستم اطلاع می‌دهند که یک کامپوننت برنامه کدام intentها را می‌پذیرد. مشابه نحوه ساخت یک intent با اکشن ACTION_SEND در درس ارسال داده‌های ساده به برنامه‌های دیگر ، شما فیلترهای intent را برای دریافت intentها با این اکشن ایجاد می‌کنید. شما یک فیلتر intent را در manifest خود با استفاده از عنصر <intent-filter> تعریف می‌کنید. به عنوان مثال، اگر برنامه شما دریافت محتوای متنی را مدیریت می‌کند، یک manifest که شامل یک یا چند تصویر از هر نوع است، مانند قطعه کد زیر خواهد بود:

<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 فهرست می‌شود. اگر کاربر برنامه‌ی شما را انتخاب کند، activity مربوطه ( .ui.MyActivity در مثال قبلی) شروع می‌شود. سپس این به شما بستگی دارد که محتوا را به طور مناسب در کد و رابط کاربری خود مدیریت کنید.

Note: For more information about intent filters and intent resolution, read Intents and Intent Filters .

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

برای مدیریت محتوای ارائه شده توسط یک Intent ، تابع getIntent() را برای دریافت شیء Intent فراخوانی کنید. پس از دریافت شیء، می‌توانید محتوای آن را بررسی کنید تا مشخص شود در مرحله بعد چه کاری باید انجام دهید. اگر این فعالیت می‌تواند از سایر بخش‌های سیستم (مانند لانچر) شروع شود، هنگام بررسی intent این نکته را در نظر بگیرید.

برای بررسی داده‌های ورودی دقت بیشتری داشته باشید، شما هرگز نمی‌دانید که برنامه‌های دیگر چه چیزی ممکن است برای شما ارسال کنند. برای مثال، ممکن است نوع MIME اشتباه تنظیم شده باشد، یا تصویری که ارسال می‌شود بسیار بزرگ باشد. همچنین، به یاد داشته باشید که داده‌های باینری را در یک نخ جداگانه به جای نخ اصلی ("UI") پردازش کنید.

@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 را از intent دریافت می‌کنید، همانطور که در مثال زیر نشان داده شده است:

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

مطمئن شوید که کاربران اپلیکیشن شما را می‌شناسند

برنامه شما توسط آیکون و برچسب آن در برگه اشتراک‌گذاری اندروید و تحلیلگر intent نمایش داده می‌شود. هر دوی این موارد در مانیفست تعریف شده‌اند. می‌توانید برچسب‌های فیلتر activity یا intent را برای ارائه زمینه بیشتر تنظیم کنید.

As of Android 10 (API level 29), the Android Sharesheet only uses icons set in the manifest on your application tag. Android ignores icons set on intent-filter and activity tags.

نکته: اهداف اشتراک‌گذاری مؤثر نیازی به برچسب و آیکون در فیلتر فعالیت یا هدف مرتبط ندارند. نام و آیکون برنامه‌ی دریافت‌کننده باید به تنهایی برای کاربر کافی باشد تا بفهمد هنگام اشتراک‌گذاری چه اتفاقی می‌افتد.