إذا كان بإمكان تطبيقك تنفيذ إجراء قد يكون مفيدًا لتطبيق آخر، فجهِّزه للاستجابة لطلبات الإجراءات من خلال تحديد intent filter المناسب في نشاطك.
على سبيل المثال، إذا كنت تنشئ تطبيقًا اجتماعيًا يمكنه مشاركة الرسائل أو الصور مع أصدقاء المستخدم، يمكنك إتاحة استخدام الغرض ACTION_SEND.
بعد ذلك، عندما يبدأ المستخدمون إجراء "مشاركة" من تطبيق آخر، يظهر تطبيقك كخيار في مربّع حوار الاختيار (المعروف أيضًا باسم مربّع حوار إزالة الغموض)، كما هو موضّح في الشكل 1.
الشكل 1: مربّع حوار أداة الاختيار
للسماح للتطبيقات الأخرى ببدء نشاطك بهذه الطريقة، عليك إضافة عنصر <intent-filter> في ملف البيان لعنصر <activity> المقابل.
عند تثبيت تطبيقك على جهاز، يحدّد النظام فلاتر الأهداف ويضيف المعلومات إلى قائمة داخلية بالأهداف التي تتيحها جميع التطبيقات المثبّتة.
عندما يستدعي أحد التطبيقات startActivity() أو startActivityForResult()
باستخدام نية ضمنية، يتحقّق النظام من الأنشطة التي يمكنها الاستجابة
للنية.
إضافة فلتر أهداف
لتحديد intents التي يمكن لنشاطك التعامل معها بشكل صحيح، اجعل كل intent filter تضيفه محددًا قدر الإمكان من حيث نوع الإجراء والبيانات التي يقبلها النشاط.
قد يرسل النظام Intent معيّنًا إلى نشاط إذا كان هذا النشاط يحتوي على intent filter يستوفي المعايير التالية لكائن Intent:
- الإجراء
- سلسلة تحدّد الإجراء المطلوب تنفيذه عادةً ما تكون إحدى القيم المحدّدة من خلال المنصة، مثل
ACTION_SENDأوACTION_VIEW.ويمكنك تحديد ذلك في intent filter باستخدام العنصر
<action>. يجب أن تكون القيمة التي تحدّدها في هذا العنصر هي اسم السلسلة الكامل للإجراء، بدلاً من ثابت واجهة برمجة التطبيقات، كما هو موضّح في الأمثلة على هذه الصفحة. - البيانات
- وصف للبيانات المرتبطة بالطلب
ويمكنك تحديد ذلك في intent filter باستخدام العنصر
<data>. باستخدام سمة واحدة أو أكثر في هذا العنصر، يمكنك تحديد نوع MIME أو بادئة معرّف الموارد المنتظم (URI) أو مخطّط URI أو مجموعة من هذه السمات وغيرها من السمات التي تشير إلى نوع البيانات المقبول.ملاحظة: إذا لم تكن بحاجة إلى الإفصاح عن تفاصيل حول البيانات
Uri، مثلاً عندما يتعامل نشاطك مع نوع آخر من البيانات "الإضافية"، بدلاً من معرّف الموارد المنتظم (URI)، حدِّد السمةandroid:mimeTypeفقط للإفصاح عن نوع البيانات التي يتعامل معها نشاطك، مثلtext/plainأوimage/jpeg. - الفئة
- توفّر طريقة إضافية لتوصيف النشاط الذي يتعامل مع الغرض، وعادةً ما يكون مرتبطًا
بالإجراء التفاعلي من المستخدم أو الموقع الجغرافي الذي بدأ منه. هناك عدة فئات مختلفة يدعمها النظام، ولكن معظمها نادرًا ما يتم استخدامه. ومع ذلك، يتم تحديد جميع الأهداف الضمنية باستخدام
CATEGORY_DEFAULTتلقائيًا.حدِّد ذلك في intent filter باستخدام العنصر
<category>.
في intent filter، يمكنك تحديد المعايير التي يقبلها نشاطك من خلال تحديد كل منها باستخدام عناصر تنسيق 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> و<category> و<data> في كل <intent-filter>.
إذا كان أي زوجين من الإجراءات والبيانات متعارضين في سلوكياتهما، أنشئ intent filters منفصلة لتحديد الإجراءات المقبولة عند إقرانها بأنواع البيانات.
على سبيل المثال، لنفترض أنّ نشاطك يتعامل مع كل من النصوص والصور لكل من الغرضَين ACTION_SEND وACTION_SENDTO. في هذه الحالة، يجب تحديد فلترَي نية منفصلَين للإجراءَين، لأنّ نية ACTION_SENDTO يجب أن تستخدم البيانات Uri لتحديد عنوان المستلِم باستخدام مخطّط URI send أو sendto. يظهر ذلك في المثال التالي:
<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. إذا لم تعلن عنه في intent filter، لن يتم مطابقة أي implicit intent لنشاطك.
لمزيد من المعلومات حول إرسال واستلام ACTION_SEND
النيّات التي تؤدي إلى سلوكيات المشاركة على شبكات التواصل الاجتماعي، يُرجى الاطّلاع على استلام البيانات البسيطة من التطبيقات الأخرى.
يمكنك أيضًا العثور على معلومات مفيدة حول مشاركة البيانات في
مشاركة البيانات البسيطة ومشاركة الملفات.
التعامل مع الطلب في نشاطك
لتحديد الإجراء الذي يجب اتّخاذه في نشاطك، اقرأ
Intent المستخدَم لبدئه.
عند بدء نشاطك، يمكنك استدعاء getIntent() لاسترداد
Intent الذي بدأ النشاط. يمكنك إجراء ذلك في أي وقت خلال دورة حياة النشاط، ولكنك تفعل ذلك بشكل عام أثناء عمليات الاستدعاء المبكرة، مثل onCreate() أو onStart().
يظهر ذلك في المثال التالي:
Kotlin
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 } }
Java
@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() لإغلاق النشاط وإتلافه. يظهر ذلك في المثال التالي:
Kotlin
// 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()
Java
// 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()
وتمرير رمز النتيجة فقط:
Kotlin
setResult(RESULT_COLOR_RED) finish()
Java
setResult(RESULT_COLOR_RED); finish();
في هذه الحالة، قد يكون هناك عدد قليل من النتائج المحتملة، لذا يكون رمز النتيجة عددًا صحيحًا محدّدًا محليًا (أكبر من 0). ويعمل هذا بشكل جيد عند إرجاع نتيجة إلى نشاط في تطبيقك، لأن النشاط الذي يتلقى النتيجة يمكنه الرجوع إلى الثابت العام لتحديد قيمة رمز النتيجة.
ملاحظة: ليس عليك التحقّق مما إذا كان نشاطك قد بدأ باستخدام startActivity() أو startActivityForResult(). ما عليك سوى استدعاء setResult() إذا كان الغرض الذي بدأ نشاطك
قد يتوقع نتيجة. إذا كان النشاط الأصلي قد استدعى startActivityForResult()، سيقدّم النظام له
النتيجة التي تقدّمها إلى setResult()، وإلا سيتم تجاهل النتيجة.