به برنامه های دیگر اجازه دهید فعالیت شما را شروع کنند

اگر برنامه شما می‌تواند عملی را انجام دهد که ممکن است برای برنامه دیگری مفید باشد، با مشخص کردن فیلتر intent مناسب در activity خود، آن را برای پاسخ به درخواست‌های عمل آماده کنید.

برای مثال، اگر یک برنامه اجتماعی می‌سازید که می‌تواند پیام‌ها یا عکس‌ها را با دوستان کاربر به اشتراک بگذارد، از هدف ACTION_SEND پشتیبانی کنید. سپس، هنگامی که کاربران یک عمل "اشتراک‌گذاری" را از برنامه دیگری آغاز می‌کنند، برنامه شما به عنوان یک گزینه در کادر انتخاب (که به عنوان کادر ابهام‌زدایی نیز شناخته می‌شود) ظاهر می‌شود، همانطور که در شکل 1 نشان داده شده است.

شکل ۱. پنجره انتخابگر.

برای اینکه به برنامه‌های دیگر اجازه دهید activity شما را از این طریق شروع کنند، باید یک عنصر <intent-filter> در فایل مانیفست خود برای عنصر <activity> مربوطه اضافه کنید.

وقتی برنامه شما روی یک دستگاه نصب می‌شود، سیستم فیلترهای intent شما را شناسایی کرده و اطلاعات را به یک کاتالوگ داخلی از intentهای پشتیبانی شده توسط همه برنامه‌های نصب شده اضافه می‌کند. وقتی یک برنامه startActivity() یا startActivityForResult() را با یک intent ضمنی فراخوانی می‌کند، سیستم activityهایی را که می‌توانند به intent پاسخ دهند، بررسی می‌کند.

یک فیلتر intent اضافه کنید

برای تعریف صحیح اینکه اکتیویتی شما کدام intentها را می‌تواند مدیریت کند، هر فیلتر intent که اضافه می‌کنید را تا حد امکان از نظر نوع عمل و داده‌هایی که اکتیویتی می‌پذیرد، خاص کنید.

سیستم ممکن است یک Intent مشخص را به یک اکتیویتی ارسال کند، اگر آن اکتیویتی دارای فیلتر Intent باشد که معیارهای زیر را برای شیء Intent برآورده کند:

اکشن

رشته‌ای که عملی را که باید انجام شود نامگذاری می‌کند. معمولاً یکی از مقادیر تعریف‌شده توسط پلتفرم، مانند ACTION_SEND یا ACTION_VIEW .

این را در فیلتر intent خود با عنصر <action> مشخص کنید. مقداری که در این عنصر مشخص می‌کنید باید نام رشته‌ای کامل برای اکشن باشد، نه ثابت API، همانطور که در مثال‌های این صفحه نشان داده شده است.

داده‌ها

شرح داده‌های مرتبط با هدف.

این مورد را در فیلتر intent خود با عنصر <data> مشخص کنید. با استفاده از یک یا چند ویژگی در این عنصر، می‌توانید نوع MIME، پیشوند URI، طرح URI یا ترکیبی از این موارد و موارد دیگر را که نوع داده پذیرفته شده را نشان می‌دهند، مشخص کنید.

نکته: اگر نیازی به اعلام جزئیات مربوط به Uri داده ندارید، مثلاً زمانی که activity شما به جای URI، نوع دیگری از داده‌های «اضافی» را مدیریت می‌کند، فقط ویژگی android:mimeType را برای اعلام نوع داده‌ای که activity شما مدیریت می‌کند، مانند text/plain یا image/jpeg ، مشخص کنید.

دسته بندی

یک روش اضافی برای توصیف فعالیتی که intent را مدیریت می‌کند، ارائه می‌دهد که معمولاً مربوط به حرکت کاربر یا مکانی است که از آن شروع شده است. چندین دسته مختلف توسط سیستم پشتیبانی می‌شوند، اما اکثر آنها به ندرت استفاده می‌شوند. با این حال، همه intentهای ضمنی به طور پیش‌فرض با CATEGORY_DEFAULT تعریف می‌شوند.

این مورد را در فیلتر intent خود با عنصر <category> مشخص کنید.

در فیلتر intent خود، می‌توانید با تعریف هر یک از معیارهایی که activity شما می‌پذیرد، به همراه عناصر XML مربوطه که در عنصر <intent-filter> قرار گرفته‌اند، مشخص کنید که کدام معیارها را می‌پذیرد.

برای مثال، در اینجا یک اکتیویتی با یک فیلتر intent وجود دارد که intent ACTION_SEND را زمانی که نوع داده متن یا تصویر است، مدیریت می‌کند:

<activity android:name="ShareActivity">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
        <data android:mimeType="image/*"/>
    </intent-filter>
</activity>

نکته: اگر می‌خواهید آیکون موجود در کادر انتخاب با آیکون پیش‌فرض اکتیویتی شما متفاوت باشد، android:icon در عنصر <intent-filter> اضافه کنید.

هر intent ورودی فقط یک action و یک نوع داده را مشخص می‌کند، اما می‌توان چندین نمونه از عناصر <action> ، <category> و <data> را در هر <intent-filter> تعریف کرد.

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

برای مثال، فرض کنید activity شما هم متن و هم تصاویر را برای هر دو intents ACTION_SEND و ACTION_SENDTO مدیریت می‌کند. در این حالت، شما باید دو فیلتر intent جداگانه برای دو action تعریف کنید، زیرا یک intent ACTION_SENDTO باید از داده Uri برای مشخص کردن آدرس گیرنده با استفاده از طرح send یا sendto URI استفاده کند. این موضوع در مثال زیر نشان داده شده است:

<activity android:name="ShareActivity">
    <!-- Filter for sending text; accepts SENDTO action with sms URI schemes -->
    <intent-filter>
        <action android:name="android.intent.action.SENDTO"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="sms" />
        <data android:scheme="smsto" />
    </intent-filter>
    <!-- Filter for sending text or images; accepts SEND action and text or image data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

نکته: برای دریافت intent های ضمنی، باید دسته CATEGORY_DEFAULT را در فیلتر intent قرار دهید. متدهای startActivity() و startActivityForResult() با تمام intent ها طوری رفتار می کنند که انگار دسته CATEGORY_DEFAULT تعریف کرده اند. اگر آن را در فیلتر intent خود تعریف نکنید، هیچ intent ضمنی به activity شما اعمال نمی شود.

برای اطلاعات بیشتر در مورد ارسال و دریافت اینتنت‌های ACTION_SEND که رفتارهای اشتراک‌گذاری اجتماعی را انجام می‌دهند، به دریافت داده‌های ساده از سایر برنامه‌ها مراجعه کنید. همچنین می‌توانید اطلاعات مفیدی در مورد اشتراک‌گذاری داده‌ها در Sharing simple data و Sharing files بیابید.

هدف (intent) را در اکتیویتی خود مدیریت کنید

برای تصمیم‌گیری در مورد اینکه چه عملی را در اکتیویتی خود انجام دهید، Intent مورد استفاده برای شروع آن را بخوانید.

همزمان با شروع activity، تابع getIntent() را برای بازیابی Intent ای که activity را آغاز کرده است، فراخوانی کنید. می‌توانید این کار را در هر زمانی در طول چرخه حیات activity انجام دهید، اما معمولاً این کار را در فراخوانی‌های اولیه، مانند onCreate() یا onStart() انجام می‌دهید.

این در مثال زیر نشان داده شده است:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main)

    val data: Uri? = intent?.data

    // Figure out what to do based on the intent type
    if (intent?.type?.startsWith("image/") == true) {
        // Handle intents with image data
    } else if (intent?.type == "text/plain") {
        // Handle intents with text
    }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    // Get the intent that started this activity
    Intent intent = getIntent();
    Uri data = intent.getData();

    // Figure out what to do based on the intent type
    if (intent.getType().indexOf("image/") != -1) {
        // Handle intents with image data
    } else if (intent.getType().equals("text/plain")) {
        // Handle intents with text
    }
}

برگرداندن نتیجه

اگر می‌خواهید نتیجه‌ای را به اکتیویتی که اکتیویتی شما را فراخوانی کرده است، برگردانید، تابع setResult() را برای مشخص کردن کد نتیجه و Intent نتیجه فراخوانی کنید. وقتی عملیات شما انجام شد و کاربر به اکتیویتی اصلی بازگشت، تابع finish() را برای بستن و از بین بردن اکتیویتی خود فراخوانی کنید. این موضوع در مثال زیر نشان داده شده است:

// Create intent to deliver some kind of result data
Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri")).also { result ->
    setResult(Activity.RESULT_OK, result)
}
finish()

// Create intent to deliver some kind of result data
Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri"));
setResult(Activity.RESULT_OK, result);
finish();

شما همیشه باید یک کد نتیجه (result code) را به همراه نتیجه مشخص کنید. معمولاً این کد یا RESULT_OK یا RESULT_CANCELED است. سپس می‌توانید در صورت لزوم، داده‌های اضافی را با یک Intent ارائه دهید.

نکته: نتیجه به طور پیش‌فرض روی RESULT_CANCELED تنظیم شده است. بنابراین، اگر کاربر قبل از تکمیل عملیات و قبل از تنظیم نتیجه توسط شما، دکمه بازگشت را بزند، اکتیویتی اصلی نتیجه "لغو شده" را دریافت می‌کند.

اگر صرفاً نیاز دارید یک عدد صحیح را برگردانید که نشان‌دهنده یکی از چندین گزینه نتیجه باشد، می‌توانید کد نتیجه را روی هر مقداری بالاتر از 0 تنظیم کنید. اگر از کد نتیجه برای ارائه یک عدد صحیح استفاده می‌کنید و نیازی به گنجاندن Intent ندارید، می‌توانید setResult() فراخوانی کرده و فقط یک کد نتیجه را ارسال کنید:

setResult(RESULT_COLOR_RED)
finish()

setResult(RESULT_COLOR_RED);
finish();

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

نکته: نیازی نیست بررسی کنید که آیا activity شما با startActivity() یا startActivityForResult() شروع شده است یا خیر. اگر intent که activity شما را شروع کرده است، انتظار نتیجه‌ای داشته باشد، کافیست setResult() را فراخوانی کنید. اگر activity مبدا startActivityForResult() را فراخوانی کرده باشد، سیستم نتیجه‌ای را که شما به setResult() ارائه می‌دهید، به آن تحویل می‌دهد؛ در غیر این صورت، نتیجه نادیده گرفته می‌شود.