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

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

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

شکل 1. گفتگوی انتخابگر.

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

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

یک فیلتر قصد اضافه کنید

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

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

اقدام

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

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

داده ها

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

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

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

دسته بندی

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

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

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

به عنوان مثال، در اینجا یک فعالیت با یک فیلتر قصد است که زمانی که نوع داده متن یا تصویر است، هدف 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> اضافه کنید.

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

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

برای مثال، فرض کنید فعالیت شما هم متن و هم تصاویر را برای مقاصد ACTION_SEND و ACTION_SENDTO کنترل می‌کند. در این حالت، باید دو فیلتر هدف مجزا برای دو اقدام تعریف کنید، زیرا یک 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>

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

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

هدف را در فعالیت خود مدیریت کنید

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

با شروع فعالیت شما، getIntent() را فراخوانی کنید تا Intent که فعالیت را شروع کرده است بازیابی کنید. شما می‌توانید این کار را در هر زمانی در طول چرخه حیات فعالیت انجام دهید، اما معمولاً این کار را در هنگام تماس‌های اولیه، مانند 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_OK یا RESULT_CANCELED است. سپس در صورت لزوم می توانید داده های اضافی را با یک Intent ارائه دهید.

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

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

setResult(RESULT_COLOR_RED)
finish()

setResult(RESULT_COLOR_RED);
finish();

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

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