في Android، حين يحتاج تطبيق إلى صورة فهو غالبًا لا يبني كاميرا. يُطلق intent اسمه IMAGE_CAPTURE عبر startActivityForResult، وتطبيق الكاميرا الذي يختاره المستخدم يلتقط الصورة ويعيدها إليه. ونفس الفكرة تشمل الفيديو (VIDEO_CAPTURE) والمنبّهات (SET_ALARM) والمؤقتات (SET_TIMER).
إذا كتبت تطبيق كاميرا أو تطبيق ساعة بـ Flutter، فأنت تريد أن تكون الطرف الذي يستقبل هذه الـ intents. وهذا يحتاج أكثر من intent filter. عليك قراءة الـ extras الموجودة في الطلب، وهي تأتي من تطبيق آخر ولا يمكن الوثوق بها. وعليك كتابة الصورة في الـ URI الذي أعطاك إياه المستدعي، أو إرجاع صورة مصغّرة إن لم يعطِ شيئًا. وعليك إنهاء الـ activity برمز النتيجة الصحيح.
system_intents إضافة (plugin) لـ Flutter لهذه المهمة. تعطيك طلبات لها أنواع (typed) في Dart، وردودًا آمنة على من يستدعي بـ startActivityForResult. وهي لـ Android فقط: تطبيقات iOS لا تستطيع تسجيل نفسها ككاميرا النظام أو ساعته، فلا يوجد مقابل يمكن دعمه.
ماذا تقدّم
قراءة الـ intent. SystemIntents.initialIntent() تُرجع الـ intent الذي شغّل الـ activity. وSystemIntents.intents هو stream للـ intents التي تصل لاحقًا عبر onNewIntent.
طلبات لها أنواع. تصل الطلبات كنوع sealed اسمه SystemIntent، فعبارة switch في Dart تغطي كل الحالات:
-
ImageCaptureRequest: فيهoutputUriوreturnThumbnail. -
VideoCaptureRequest: فيهoutputUriوdurationLimitوsizeLimitوquality. -
SetAlarmRequest: فيهhourوminutesوdaysوmessageوskipUiوvibrateوringtone. والحقلdaysيحمل أرقام أيام الأسبوع بصيغةDateTimeمحوَّلة من ثوابتCalendarفي Android. -
SetTimerRequest: فيهlengthSecondsوmessageوskipUi. -
ShowAlarmsRequestوShowTimersRequestوDismissAlarmRequestوSnoozeAlarmRequest. -
UnknownIntent: الـ action والـ data والـ extras البسيطة فقط.
الرد على طلبات التصوير. respondWithImage(path) تنسخ ملفك إلى EXTRA_OUTPUT الخاص بالمستدعي. وإن لم يوجد EXTRA_OUTPUT، تُرجع صورة مصغّرة (thumbnail) في data. وrespondWithVideo(path) تنسخ الملف إلى EXTRA_OUTPUT، وإن لم يوجد تُرجع URI من نوع content:// من الـ FileProvider الخاص بالإضافة، مع ضبط FLAG_GRANT_READ_URI_PERMISSION وتمرير الإذن عبر ClipData. وcancel() تُرجع RESULT_CANCELED. كل واحدة من هذه تضبط النتيجة ثم تنهي الـ activity.
المدخلات غير الموثوقة تبقى غير موثوقة. يُفحص EXTRA_OUTPUT قبل كتابة أي شيء فيه. والـ extras المشوّهة أو الخارجة عن المجال لا تُمرَّر كما هي: hour: 25 تصبح null. والـ parcelables المجهولة في الـ extras تُحذف ولا تُفكّ أبدًا نحو Dart، والـ bundle المشوَّه يُلتقط خطؤه ولا يُسقط الـ activity.
طريقة الاستعمال
أضِفها من GitHub:
dependencies:
system_intents:
git: https://github.com/AbdeldjalilChougui/system_intents
تحتاج minSdk 21.
الإضافة لا تضيف أي intent filter إلى تطبيقك. أنت من يختار الطلبات التي يجيب عنها الـ activity. والـ manifest الخاص بها يضيف فقط FileProvider يشارك المجلد cache/system_intents/.
للتصوير، أضِف الـ filters داخل عنصر MainActivity الموجود عندك، بجانب filter الـ MAIN/LAUNCHER. الفئة DEFAULT ضرورية، لأن الـ implicit intents لا تطابق إلا الـ activities التي تصرّح بها:
<intent-filter>
<action android:name="android.media.action.IMAGE_CAPTURE" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<intent-filter>
<action android:name="android.media.action.VIDEO_CAPTURE" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
للمنبّهات والمؤقتات، توثيق Android يقول إن من يعالج SET_ALARM وSET_TIMER ينبغي أن يشترط الإذن com.android.alarm.permission.SET_ALARM. لو وضعت هذا الإذن على MainActivity نفسه، لن يستطيع الـ launcher فتح تطبيقك. وحل الـ README هو activity-alias يشير إلى MainActivity ويحمل الإذن، وفي الـ filter الخاص به actions المنبّه والمؤقت. الـ XML الكامل في الـ README، وتطبيق المثال فيه manifest كامل.
أبقِ وضع التشغيل الافتراضي في Flutter أي singleTop. من يطلب التصوير يستعمل startActivityForResult دون FLAG_ACTIVITY_NEW_TASK، فينشئ Android نسخة جديدة من الـ activity داخل task المستدعي، وهذه النسخة هي التي تعيد النتيجة. تجنّب singleTask وsingleInstance عند معالجة التصوير.
تستطيع تجربة الـ filter من سطر الأوامر:
adb shell am start -a android.media.action.IMAGE_CAPTURE
ثم في Dart:
import 'package:system_intents/system_intents.dart';
Future<void> handleLaunch() async {
final intent = await SystemIntents.initialIntent();
if (intent != null) await handle(intent);
SystemIntents.intents.listen(handle); // later intents via onNewIntent
}
Future<void> handle(SystemIntent intent) async {
switch (intent) {
case ImageCaptureRequest():
final path = await takePhotoSomehow(); // your camera UI
if (path == null) {
await SystemIntents.cancel();
} else {
await SystemIntents.respondWithImage(path); // finishes the activity
}
case SetAlarmRequest(:final hour, :final minutes, :final days):
if (hour != null) {
scheduleAlarm(hour, minutes ?? 0, days, silent: intent.isSilent);
}
if (!intent.skipUi) openAlarmEditor();
case SetTimerRequest(:final length):
if (length != null) startTimer(length);
default:
break;
}
}
الدوال takePhotoSomehow وscheduleAlarm وopenAlarmEditor وstartTimer هي كود تطبيقك أنت. ونسخة الـ README تسرد كل حالات النوع الـ sealed بدل استعمال default.
عندما يفشل الرد، يُرمى PlatformException قيمة code فيه واحدة من SystemIntentsErrorCodes: no_capture_request (الـ intent الحالي ليس طلب التصوير المطابق، أو سبق الرد عليه)، وinvalid_output_uri (فشل فحص EXTRA_OUTPUT؛ الـ activity تبقى مفتوحة فاستدعِ cancel())، وfile_not_found، وwrite_failed، وno_activity.
الأمان
EXTRA_OUTPUT يأتي من تطبيق آخر. قبل الكتابة، تفحصه الإضافة بهذه القواعد:
- URI من نوع
content://يُقبل فقط إذا كان الـ provider صاحب الـ authority تابعًا للحزمة المستدعية، ويُحدَّد ذلك بـPackageManager.resolveContentProvider. - عناوين
content://التي يقدّمها تطبيقك أنت تُرفض دائمًا. لولا ذلك لاستطاع مستدعٍ أن يجعلك تكتب فوق قواعد بياناتك أو إعداداتك عبر الـ providers الخاصة بك. -
file://يُقبل فقط تحت API 24. وحتى هناك، المسار الذي ينتهي بعد التبسيط داخل التخزين الخاص بتطبيقك يُرفض، ومنه التنقل بـ... - كل scheme آخر يُرفض.
ولأن طلبات التصوير تستعمل startActivityForResult، تعطيك Activity.getCallingPackage() اسم التطبيق الطالب، والإضافة تكشفه في SystemIntent.callingPackage. تستطيع عرضه على المستخدم أو مقارنته بقائمة مسموح بها قبل الرد. وقيمته null إذا استعمل المستدعي startActivity العادية، وهذا المستدعي لا يستطيع استقبال نتيجة أصلًا.
أشياء يجب معرفتها
- أن تكون التطبيق الافتراضي قرار المستخدم. التصريح بالـ filters يضيف تطبيقك إلى قائمة الاختيار فقط. Android يترك المستخدم يختار المعالج أو يحدد الافتراضي، ولا يجوز للتطبيقات أن تحاول فرض هذا الاختيار أو التحايل عليه. وكثير من المستدعين يستهدفون حزمة كاميرا محددة مباشرة، فلن يصلوا إلى تطبيقك أبدًا.
- الإضافة لا تصوّر شيئًا بنفسها. استعمل واجهة الكاميرا الخاصة بك ومرّر مسار الملف الناتج.
- أنواع المنبّه والمؤقت تحلّل الطلبات فقط. جدولة المنبّهات مسؤولية تطبيقك.
- الصور المصغّرة حدّها 320 px في الضلع الأطول، ولا يُطبَّق عليها اتجاه EXIF.
-
عناوين الإخراج من طرف ثالث تُرفض. المستدعي الذي يمرّر URI من provider ثالث، مثل صف أدرجه في MediaStore، يُرفض طلبه، ولا يبقى لتطبيقك إلا
cancel(). -
callingPackageيُقرأ من الـ activity. في الـ intents التي تصل عبرonNewIntent، يعكس المستدعي الأصلي للـ activity. -
الطلبات المرسلة بـ
adb shell am startليس لها calling package، فالرد عليها معEXTRA_OUTPUTيُرفض. -
ما الذي اختُبر. اختبارات Kotlin تغطي المنطق الصرف: استخراج القيم، تحويل أيام الأسبوع، قواعد الـ URI وحجم الصورة المصغّرة. وفي تطبيق المثال integration test على المحاكي، فيه تطبيق ثانٍ صغير يستدعي
startActivityForResultمثل عميل حقيقي. يتحقق من الطلبات ذات الأنواع، والرد المكتوب فيEXTRA_OUTPUTالخاص بالمستدعي، والصورة المصغّرة، و URI الفيديو من الـ FileProvider مع إذن القراءة، ورفضEXTRA_OUTPUTمن MediaStore، وSET_ALARMعبر الـ alias المحمي بالإذن. اختُبرت على محاكي Android (صورة نظام Pixel 10، API 37) مع تطبيق مستدعٍ تجريبي. ولم تُختبر بعد على هاتف حقيقي ولا مع تطبيقات كاميرا من أطراف أخرى.
لماذا بنيتها
المشكلة في الـ README هي المسافة بين "أضِف intent filter" ومعالج يتصرف بشكل صحيح. الـ filter أربعة أسطر XML. والباقي هو الجزء الذي يقع فيه الخطأ: extras قد تكون ناقصة أو خارج المجال، URI إخراج اختاره طرف مجهول، الرجوع إلى الصورة المصغّرة، إذن قراءة الـ URI للفيديو، وإذن المنبّه الذي يجب ألّا يوضع على activity الـ launcher.
أردت أن يرى جانب Dart طلبات نظيفة لها أنواع فقط، وأن يرفض جانب Kotlin كل ما هو غير آمن افتراضيًا. تطبيق الكاميرا الذي يكتب حيثما يطلب منه المستدعي يفتح بابًا نحو ملفاته الخاصة، ولهذا قواعد الـ URI جزء من الإضافة وليست متروكة للمطوّر.
احصل على الكود
المصدر، ودليل الـ manifest الكامل، وتطبيق المثال، والاختبارات، كلها على GitHub: https://github.com/AbdeldjalilChougui/system_intents. الرخصة MIT. الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.
نُشر في الأصل على abdeldjalilchougui.biz.
Top comments (0)