ZXing مع Kotlin: دليل شامل لمسح رموز QR والباركود

في عالم تطبيقات الهواتف الذكية وأتمتة العمليات، أصبحت القدرة على قراءة المعلومات بسرعة من رموز QR والباركود معيارًا أساسيًا. مكتبة ZXing (تُنطق "zebra crossing") هي أداة قوية مفتوحة المصدر تتيح للمطورين دمج وظائف التعرف على الرموز أحادية البعد (مثل EAN وUPC وCode 128) وثنائية البعد (مثل QR وData Matrix وAztec) وتوليدها بسهولة في تطبيقاتهم.

هذا الدليل موجه لمطوري لغة Kotlin الذين يرغبون في إتقان ZXing بدءًا من التثبيت الأساسي وصولاً إلى كتابة ماسحات ضوئية متقدمة مع تحسين الأداء. سنستعرض ليس فقط السيناريوهات القياسية، بل أيضًا النقاط الدقيقة التي غالبًا ما تسبب أخطاء للمبتدئين.

1. ما هي مكتبة ZXing ولماذا تحتاجها؟

ZXing هي مكتبة لمعالجة الصور متخصصة في فك تشفير وترميز الباركود. تم تطويرها بواسطة Google وتدعمها مجتمعات المطورين. ميزتها الرئيسية هي تعدد المنصات (Java/Kotlin وC++ وJavaScript وPython) ودعمها لعدد كبير من التنسيقات: من رموز QR الكلاسيكية إلى الرموز الصناعية المتخصصة مثل PDF417.

لماذا تستخدم ZXing مع Kotlin؟ أولاً، إنه المعيار الذهبي لتطوير تطبيقات Android. ثانيًا، توفر المكتبة فئات جاهزة للعمل مع الكاميرا (عبر CameraX أو Camera2)، مما يغنيك عن كتابة كود منخفض المستوى لالتقاط الفيديو. ثالثًا، يمكن لـ ZXing العمل ليس فقط مع الفيديو المباشر، بل أيضًا مع الصور الجاهزة (ملفات من المعرض)، مما يوسع حالات الاستخدام: من مسح الفواتير إلى التعرف على الرموز على عبوات المنتجات في مجال اللوجستيات.

2. التثبيت

بالنسبة لـ Kotlin (Android)، يتم التثبيت عبر نظام بناء Gradle. أضف التبعيات التالية إلى ملف build.gradle (Module: app):

dependencies {
    // المكتبة الأساسية لـ ZXing
    implementation("com.google.zxing:core:3.5.3")
    // وحدة إضافية للعمل مع الكاميرا (موصى بها)
    implementation("com.journeyapps:zxing-android-embedded:4.3.0")
}

إذا كنت تستخدم Kotlin Multiplatform أو Kotlin من جانب الخادم (Ktor)، فستحتاج فقط إلى الوحدة الأساسية:

implementation("com.google.zxing:core:3.5.3")

لتطبيقات سطح المكتب (JVM)، أضف التبعية في Maven أو Gradle بنفس الطريقة. بعد مزامنة المشروع، تصبح المكتبة جاهزة للاستخدام.

3. البداية السريعة — مثال عملي بسيط

أسهل طريقة لاختبار ZXing هي تشغيل Activity مدمجة للمسح الضوئي. للقيام بذلك، يكفي استدعاء Intent. فيما يلي كود بسيط لـ Android Activity بلغة Kotlin:

import android.app.Activity
import android.content.Intent
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.journeyapps.barcodescanner.ScanContract
import com.journeyapps.barcodescanner.ScanOptions

class MainActivity : AppCompatActivity() {

    // تسجيل عقد لتشغيل الماسح الضوئي
    private val barcodeLauncher = registerForActivityResult(ScanContract()) { result ->
        if (result.contents == null) {
            Toast.makeText(this, "تم إلغاء المسح", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this, "النتيجة: ${result.contents}", Toast.LENGTH_LONG).show()
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // إعداد خيارات المسح
        val options = ScanOptions()
        options.setDesiredBarcodeFormats(ScanOptions.QR_CODE) // QR فقط
        op