توليد رموز QR في Node.js: مكتبة qrcode وأمثلة

توليد رموز QR على Node.js باستخدام مكتبة qrcode

أصبحت رموز QR جزءًا لا يتجزأ من الويب الحديث: من روابط Wi-Fi إلى تأكيد المدفوعات. إذا كنت تطور الواجهة الخلفية على Node.js وتريد إنشاء رموز QR برمجيًا، فإن مكتبة qrcode هي الأداة الأكثر شيوعًا وسهولة. لا تتطلب تثبيت حزم رسومية إضافية ويمكنها إخراج النتيجة بتنسيقات مختلفة: PNG، SVG، قماش HTML وحتى في شكل نصي للطرفية.

التثبيت

قم بتثبيت الحزمة عبر npm:

npm install qrcode

بعد التثبيت، قم بتضمين الوحدة في مشروعك:

const QRCode = require('qrcode');

الطرق الأساسية

توفر المكتبة ثلاث طرق رئيسية للتوليد:

• QRCode.toDataURL(text, options) — تُرجع عنوان URL للبيانات (سلسلة base64 مع صورة PNG).
• QRCode.toBuffer(text, options) — تُرجع مخزنًا مؤقتًا (Buffer) مع صورة PNG (مناسب للحفظ في ملف أو الإرسال عبر HTTP).
• QRCode.toString(text, options) — تُرجع سلسلة نصية بتنسيق SVG أو رموز طرفية (يتم تحديد نوع الإخراج في options.type).
• QRCode.toCanvas(canvasElement, text, options) — للبيئة المتصفحية (canvas).

مثال بسيط: إنشاء رمز QR بتنسيق PNG (مخزن مؤقت)

السيناريو الأكثر شيوعًا هو توليد صورة وحفظها في ملف أو تقديمها للمستخدم. إليك كيفية القيام بذلك:

const QRCode = require('qrcode');const fs = require('fs');

QRCode.toBuffer('https://pythonlib.ru', {  width: 400,  margin: 2,  color: {    dark: '#000000',    light: '#ffffff'  }}).then(buffer => {  fs.writeFileSync('qrcode.png', buffer);  console.log('تم حفظ رمز QR في qrcode.png');}).catch(err => console.error(err));

في هذا المثال، نحدد حجم 400 بكسل، وهامشًا بمقدار وحدتين، ونظام ألوان أبيض وأسود. الطريقة toBuffer تُرجع وعدًا (Promise)، لذلك نستخدم .then() أو async/await.

توليد رمز QR بتنسيق SVG

لتطبيقات الويب، غالبًا ما يكون استخدام تنسيق المتجهات SVG أكثر ملاءمة - فهو قابل للتوسع دون فقدان الجودة ويشغل مساحة أقل. حدد type: 'svg' في الخيارات:

const QRCode = require('qrcode');

QRCode.toString('https://pythonlib.ru', {  type: 'svg',  width: 300,  color: {    dark: '#1a73e8',    light: '#ffffff'  }}).then(svgString => {  console.log(svgString);  // يمكنك الآن حفظ svgString في ملف أو إدراجه في HTML}).catch(err => console.error(err));

عرض رمز QR مباشرة في الطرفية

أحيانًا تحتاج إلى التحقق بسرعة من رابط دون فتح المتصفح. يمكن للمكتبة رسم رمز QR باستخدام رموز Unicode في وحدة التحكم:

const QRCode = require('qrcode');

QRCode.toString('Hello, PythonLib!', {  type: 'terminal',  small: true}).then(qr => {  console.log(qr);}).catch(err => console.error(err));

المعامل small: true يجعل رمز QR أكثر إحكامًا (يستخدم كتلًا نصفية). إذا قمت بإزالته، ستكون الصورة أكبر حجمًا ولكنها أكثر تفصيلاً.

الإعدادات والمعاملات

يسمح كائن options بالتحكم المرن في التوليد. الحقول الرئيسية:

• width — عرض الصورة بالبكسل (الافتراضي 256).
• margin — الهامش من الحافة (بوحدات رمز QR، الافتراضي 4).
• color.dark — لون الوحدات الداكنة (hex، rgb أو اسم اللون).
• color.light — لون الخلفية (الافتراضي أبيض).
• errorCorrectionLevel — مستوى تصحيح الأخطاء: 'L' (7%)، 'M' (15%)، 'Q' (25%)، 'H' (30%). كلما ارتفع المستوى، زادت البيانات التي يمكن استعادتها، ولكن يصبح رمز QR نفسه أكثر كثافة.