اگر برنامه شما میتواند عملی را انجام دهد که ممکن است برای برنامه دیگری مفید باشد، آن را برای پاسخ به درخواستهای اقدام با تعیین فیلتر هدف مناسب در فعالیت خود آماده کنید.
برای مثال، اگر یک برنامه اجتماعی میسازید که میتواند پیامها یا عکسها را با دوستان کاربر به اشتراک بگذارد، از هدف ACTION_SEND
پشتیبانی کنید. سپس، هنگامی که کاربران یک اقدام "اشتراک گذاری" را از یک برنامه دیگر آغاز می کنند، برنامه شما به عنوان یک گزینه در گفتگوی انتخابگر (همچنین به عنوان گفتگوی ابهام زدایی شناخته می شود) ظاهر می شود، همانطور که در شکل 1 نشان داده شده است.
![](https://developer.android.com/static/images/training/basics/intent-chooser.png?authuser=0&hl=fa)
شکل 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()
ارائه می کنید، تحویل می دهد. در غیر این صورت، نتیجه نادیده گرفته می شود.