قارئ باركود Flutter يحتاج شاشة واضحة لبدء المسح ثم عرض القيمة التي قرأتها الكاميرا. يركز المثال على مسار واحد: ينقر المستخدم الزر، تفتح شاشة الماسح، ثم تعود النتيجة إلى الصفحة. يعرض التطبيق النص فقط ولا يفتح الروابط تلقائيًا، لأن محتوى QR قد يأتي من مصدر غير معروف. هذا درس Flutter وDart، ولذلك مكانه قسم مكتبات Flutter وليس مكتبات Python، مع بقاء رابط المقال المنشور كما هو.
التجهيز والمتطلبات
flutter pub add ai_barcode_scanner:^8.2.0الإصدار وتجهيز المشروع
المثال يستهدف ai_barcode_scanner 8.2.0؛ راجع متطلبات الإصدار عند دمجه في مشروع قديم. تعتمد دالة showAiBarcodeScanner على واجهة حديثة قد لا توجد في إصدار سبق تثبيته، لذا لا تجمع مثالًا جديدًا مع حزمة قديمة دون مراجعة. بعد إضافة الاعتماد شغل flutter pub get ثم ضع الكود في lib/main.dart داخل مشروع تجريبي. افحص flutter –version ومتطلبات Android وiOS في صفحة الحزمة قبل تغيير إعدادات مشروعك الأساسي.
كيف تُحفظ حالة واجهة المستخدم؟
تخزن الصفحة النص المعروض وحالة busy. عند بدء المسح نعطل الزر حتى لا تفتح عدة شاشات فوق بعضها. بعد await نتحقق من mounted لأن المستخدم قد يغادر الصفحة أثناء انتظار النتيجة. ثم نعالج الإلغاء كناتج مستقل ونفك حالة الانتظار داخل finally. هذا تنظيم لحالة واجهة المستخدم يمكن تطبيقه في عمليات غير المسح أيضًا، ويمنع setState بعد التخلص من الصفحة أو بقاء الزر معطلًا بعد فشل العملية.
المثال البرمجي الكامل
import 'package:ai_barcode_scanner/ai_barcode_scanner.dart';
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: ScannerPage()));
class ScannerPage extends StatefulWidget {
const ScannerPage({super.key});
@override
State<ScannerPage> createState() => _ScannerPageState();
}
class _ScannerPageState extends State<ScannerPage> {
String _result = 'لم يتم المسح بعد';
bool _busy = false;
Future<void> _scan() async {
setState(() => _busy = true);
try {
final capture = await showAiBarcodeScanner(context);
if (!mounted) return;
setState(() => _result = capture?.firstRawValue ?? 'تم إلغاء المسح');
} catch (_) {
if (mounted) setState(() => _result = 'تعذر تشغيل الماسح');
} finally {
if (mounted) setState(() => _busy = false);
}
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('قارئ الباركود')),
body: Center(child: Padding(
padding: const EdgeInsets.all(24),
child: Column(mainAxisSize: MainAxisSize.min, children: [
SelectableText(_result, textAlign: TextAlign.center),
const SizedBox(height: 16),
FilledButton(onPressed: _busy ? null : _scan,
child: const Text('مسح QR أو Barcode')),
]),
)),
);
}
الصلاحيات وتجربة الجهاز
على iOS أضف وصف استخدام الكاميرا في NSCameraUsageDescription، ووصف مكتبة الصور عند الإبقاء على زر المعرض الافتراضي، وفق تعليمات الحزمة. تختلف متطلبات Android والبناء حسب إصدار التبعية، لذلك اتبع إعداد الإصدار المحدد بدل نسخ ملف Manifest قديم. اختبر على جهاز حقيقي وبإضاءة جيدة؛ لا تعتمد محاكي iOS لاختبار كاميرا فعلية. على الويب يحتاج الوصول للكاميرا سياقًا آمنًا مثل HTTPS مع قبول المستخدم للإذن.
النتيجة ليست أمرًا موثوقًا
يعرض SelectableText القيمة كي يمكن نسخها ومراجعتها. إذا أردت لاحقًا فتح رابط، افحص المخطط والمضيف واعرض تأكيدًا مناسبًا؛ لا تنفذ النص المقروء كتعليمة. وإذا كانت النتيجة رقم منتج، تحقق من صيغة الرقم قبل الاستعلام في الخادم. قد يفشل المسح بسبب إذن مرفوض أو كود صغير أو انعكاس ضوء، لذلك تعرض الصفحة رسالة فشل عامة وتسمح بالمحاولة مجددًا. أضف تفاصيل تشخيص مناسبة للتطوير دون تسجيل رموز حساسة في سجلات عامة.
قائمة اختبار عملية قبل النشر
جرّب QR واحدًا واضحًا، وباركود منتج، والعودة دون مسح، ورفض إذن الكاميرا ثم تفعيله من إعدادات الجهاز. اختبر تدوير الشاشة وخروج التطبيق إلى الخلفية والعودة، وراقب إغلاق الكاميرا عند مغادرة شاشة المسح. التحليل الساكن يتحقق من أنواع الاستدعاءات ولا يثبت جودة القراءة أو سلوك الإذن على كل هاتف. سجل إصدار الحزمة والنظام الذي اختبرت عليه كي تعيد التجربة عند التحديث.
ماذا أفعل إذا عاد المستخدم دون نتيجة؟
اعتبر الإلغاء خيارًا طبيعيًا في رحلة المستخدم، واسمح بالمحاولة مرة أخرى دون رسالة توحي بأن الجهاز معطل. إذا كانت الصفحة جزءًا من نموذج، احتفظ بالقيمة السابقة حتى يقرر المستخدم استبدالها وفق سلوك منتجك. المثال يعرض حالة الإلغاء بوضوح ليبين الفرق عن استثناء أثناء التشغيل. ويمكن لاحقًا فصل نص الحالة عن القيمة المقبولة بحيث لا تخزن عبارة الإلغاء نفسها في حقل رقم المنتج.
دروس Flutter مرتبطة
يمكن متابعة تحويل الصوت إلى نص في Flutter أو التحقق من وقت الجهاز في Flutter لتوسيع التعامل مع قدرات الجهاز ونتائج العمليات غير المتزامنة.
المراجع
واجهة حزمة ai_barcode_scanner الرسمية
تطبيق ai_barcode_scanner في مشروعك
امنع معالجة النتيجة نفسها عدة مرات، وتحقق من محتوى QR قبل فتحه؛ عالِج رفض الكاميرا ووفّر إدخالًا يدويًا عند تعذر المسح.
عند مراجعة صفحة ai_barcode_scanner كان الإصدار المنشور 8.2.0. أرقام الإصدارات في المثال الأصلي قد تختلف؛ قارِن دليل الهجرة وإعدادات المنصة قبل التحديث، ولا ترفع قيد الاعتماد وحده مع إبقاء استدعاءات واجهة قديمة.
مراجع الموضوع: pub.dev — ai_barcode_scanner






