هل تريد إنشاء QR Code باستخدام بايثون لرابط موقع أو نص عربي، ثم حفظه كصورة PNG قابلة للمشاركة أو الطباعة؟ في هذا الدرس من سلسلة بايثون بالمثال 27 سنبدأ بأربعة أسطر من الكود، ثم نتعلم التحكم بحجم الرمز وألوانه وإنشاء عدة رموز دفعة واحدة من ملف CSV.
سنستخدم مكتبة qrcode، وسنوفر مشروعًا صغيرًا قابلًا للتشغيل على جهازك. لا تحتاج إلى خدمة ويب ولا إلى API خارجي لتوليد الرموز بعد تثبيت المكتبة.
{alertInfo}المتطلبات: Python 3.9 أو أحدث، ومكتبةqrcodeمع دعمPillow. الصور الناتجة بصيغة PNG.
حمّل أكواد الدرس وملف CSV التجريبي والاختبارات، ثم تابع الشرح لتوليد رموز QR خطوة بخطوة.
تحميل ملفات الدرس ZIP{getToc} $title={محتوى المقال}
ما هو QR Code وماذا يخزن؟
رمز QR Code هو رمز ثنائي الأبعاد يمكن لكاميرا الهاتف أو تطبيق قارئ الرموز قراءته. يمكن أن يخزن رابط موقع أو نصًا أو بيانات أخرى. في مثالنا سنضع رابط بايثون العرب داخل الرمز، ثم سنقرأه بالكاميرا للتأكد من أن النتيجة صحيحة.
معلومة مهمة: إنشاء QR لا يعني اختصار الرابط؛ فإذا أدخلت رابطًا طويلًا، فسيحتوي الرمز على الرابط نفسه. كما أن قراءة QR لا تجعل الرابط آمنًا تلقائيًا، لذا افحص وجهته قبل فتحها.
تثبيت مكتبة qrcode في بايثون
افتح الطرفية داخل مجلد مشروعك ونفّذ الأمر التالي:
python -m pip install "qrcode[pil]"تقوم الإضافة [pil] بتثبيت دعم Pillow لإنتاج صور PNG والتحكم بالألوان. وللتأكد من أن التثبيت تم في بيئة بايثون التي تستخدمها، نفّذ:
python -m pip show qrcode{alertWarning}إذا ظهرت رسالة ModuleNotFoundError: No module named qrcode، تأكد أنك نفّذت التثبيت بواسطة مفسّر بايثون نفسه المستخدم لتشغيل الملف.أبسط كود لإنشاء QR Code لرابط موقع
أنشئ ملفًا باسم first_qr.py واكتب الكود التالي:
import qrcode
url = "https://www.arabpython.com/"
image = qrcode.make(url)
image.save("arabpython-qr.png")
print("تم إنشاء رمز QR بنجاح")
شغّل الملف:
python first_qr.pyستجد الصورة arabpython-qr.png في المجلد نفسه. افتح الصورة ووجّه إليها كاميرا هاتفك؛ ينبغي أن يظهر رابط الموقع داخلها.
كيف يعمل هذا الكود؟
| السطر | وظيفته |
|---|---|
import qrcode | استيراد مكتبة توليد الرموز |
url = ... | تحديد الرابط الذي سيُخزَّن داخل QR |
qrcode.make(url) | بناء صورة الرمز من الرابط |
image.save(...) | حفظ الصورة على جهازك |
إنشاء QR Code لنص عربي بدل الرابط
يمكن إدخال أي نص، وليس بالضرورة رابطًا. غيّر المتغير فقط كما يلي:
import qrcode
message = "أهلًا بك في بايثون العرب"
qrcode.make(message).save("arabic-message.png")
عند قراءة الرمز ستظهر الجملة العربية. تأكد من حفظ ملف Python بترميز UTF-8، وهو الترميز الافتراضي المعتاد في المحررات الحديثة.
تغيير حجم الرمز وألوانه باستخدام QRCode
لخيارات أكثر من qrcode.make()، استخدم الصنف QRCode. المثال التالي ينشئ رمزًا أزرق على خلفية بيضاء ويحدد حجم كل مربع:
import qrcode
qr = qrcode.QRCode(
version=None,
error_correction=qrcode.constants.ERROR_CORRECT_M,
box_size=12,
border=4,
)
qr.add_data("https://www.arabpython.com/")
qr.make(fit=True)
image = qr.make_image(fill_color="#164a8c", back_color="white")
image.save("blue-qr.png")
| الخيار | ماذا يغيّر؟ |
|---|---|
version=None مع fit=True | يسمح بتحديد حجم مصفوفة QR وفق كمية البيانات |
box_size=12 | حجم المربع الواحد في الصورة بوحدة البكسل |
border=4 | الهامش الفارغ المحيط بالرمز بوحدة المربعات |
ERROR_CORRECT_M | مستوى متوسط لتصحيح الأخطاء، بنحو 15% تقريبًا |
fill_color | لون مربعات الرمز |
back_color | لون الخلفية |
{alertWarning}قابلية المسح أهم من الشكل. استخدم ألوانًا ذات تباين قوي، وحافظ على هامش فارغ حول الرمز، ولا تضع نصوصًا أو العلامة المائية فوق مربعات QR. اختبر الصورة بكاميرا الهاتف، خصوصًا قبل الطباعة.
مشروع عملي: دالة لإنشاء QR Code وحفظه في مجلد
بدل تكرار كود توليد الصورة في كل مرة، ننشئ ملفًا باسم qr_core.py يحتوي دالة قابلة لإعادة الاستخدام، وتتحقق من النص والمدخلات قبل الحفظ. هذا هو الكود نفسه الموجود في حزمة المشروع:
"""إنشاء رموز QR بصيغة PNG باستخدام مكتبة qrcode."""
from pathlib import Path
import qrcode
from PIL import ImageColor
def make_qr(data, output_path, fill="black", background="white", box_size=10):
"""إنشاء صورة QR من نص أو رابط وإرجاع مسار الصورة."""
if not isinstance(data, str) or not data.strip():
raise ValueError("يجب إدخال رابط أو نص غير فارغ.")
if not 1 <= box_size <= 40:
raise ValueError("حجم المربعات يجب أن يكون من 1 إلى 40.")
foreground = ImageColor.getrgb(fill)
backdrop = ImageColor.getrgb(background)
if foreground == backdrop:
raise ValueError("يجب أن يختلف لون المربعات عن لون الخلفية.")
output = Path(output_path)
if output.suffix.lower() != ".png":
raise ValueError("يجب أن ينتهي اسم الصورة بالامتداد .png")
output.parent.mkdir(parents=True, exist_ok=True)
qr = qrcode.QRCode(
version=None,
error_correction=qrcode.constants.ERROR_CORRECT_M,
box_size=box_size,
border=4,
)
qr.add_data(data)
qr.make(fit=True)
image = qr.make_image(fill_color=foreground, back_color=backdrop)
image.save(output)
return output
لاحظ أن الدالة تتعامل مع المسار بواسطة Path، وتنشئ مجلد الحفظ عند الحاجة. كما ترفض النص الفارغ أو استخدام اللون نفسه للمربعات والخلفية.
تشغيل المشروع من سطر الأوامر
ملف make_qr.py في الحزمة يستخدم الدالة السابقة مع argparse لتحديد النص ومسار الصورة والألوان. لتشغيله استخدم:
python make_qr.py --text "https://www.arabpython.com/" --output output/website.pngولإنشاء رمز لنص عربي:
python make_qr.py --text "مرحبا بك في بايثون العرب" --output output/arabic.pngوللتخصيص:
python make_qr.py --text "https://www.arabpython.com/" --output output/blue.png --fill "#164a8c" --background white --box-size 12يمكنك الاطلاع على الكود الكامل لملف make_qr.py ضمن الحزمة. هذا الأسلوب مفيد عندما ترغب في توليد رموز جديدة من الطرفية دون تعديل الكود في كل مرة.
إنشاء عدة رموز QR من ملف CSV دفعة واحدة
إذا أردت إنشاء رمز لكل رابط أو نص من مجموعة كبيرة، استخدم ملف CSV بعمودين هما filename لاسم الصورة وdata للمحتوى الذي سيُخزَّن داخل الرمز. أنشئ ملف examples/links.csv بالمحتوى التالي:
filename,data
arabpython,https://www.arabpython.com/
docs,https://docs.python.org/3/
welcome,مرحبا بك في بايثون العربوفي ملف batch_qr.py سنقرأ الصفوف بواسطة مكتبة csv المدمجة، ونولّد صورة لكل صف. الكود الكامل كما في الحزمة:
"""إنشاء عدة رموز QR من CSV بأعمدة filename,data."""
import argparse
import csv
import re
from pathlib import Path
from qrcode.exceptions import DataOverflowError
from qr_core import make_qr
def clean_filename(value):
"""توليد اسم ملف آمن من عنوان الصف."""
name = re.sub(r"[^A-Za-z0-9_-]+", "_", value.strip()).strip("_")
if not name:
raise ValueError("اسم الملف غير صالح")
return name[:80] + ".png"
def main():
parser = argparse.ArgumentParser(description="إنشاء رموز QR من CSV")
parser.add_argument("csv_file", help="ملف CSV يحتوي filename,data")
parser.add_argument("--output", default="output/batch", help="مجلد النتائج")
args = parser.parse_args()
success = 0
failed = 0
used = set()
try:
with Path(args.csv_file).open("r", encoding="utf-8-sig", newline="") as file:
reader = csv.DictReader(file)
if not reader.fieldnames or not {"filename", "data"}.issubset(reader.fieldnames):
raise ValueError("يجب أن يحتوي CSV على العمودين filename,data")
for row_number, row in enumerate(reader, start=2):
try:
filename = clean_filename(row.get("filename") or "")
data = row.get("data") or ""
if filename in used:
raise ValueError("اسم ملف مكرر داخل CSV")
used.add(filename)
output = Path(args.output) / filename
make_qr(data, output)
success += 1
print(f"نجاح: {output}")
except (ValueError, OSError, DataOverflowError) as error:
failed += 1
print(f"تخطي السطر {row_number}: {error}")
except (OSError, ValueError) as error:
parser.exit(1, f"خطأ: {error}\n")
print(f"اكتمل التنفيذ: نجح {success}، تعذر {failed}")
if failed:
parser.exit(1)
if __name__ == "__main__":
main()
شغّل الأمر:
python batch_qr.py examples/links.csv --output output/batchستحصل على الصور arabpython.png وdocs.png وwelcome.png داخل المجلد output/batch. إذا كان صف غير صالح، سيعرض السكربت سبب تخطيه بدل إيقاف معالجة كل الصفوف.
ملفات المشروع وطريقة تشغيلها
حزمة المشروع قابلة للتجربة مباشرة، وبداخلها ملفات الشرح والاختبارات وأمثلة جاهزة:
qr-code-python-example-27/
├── qr_core.py
├── make_qr.py
├── batch_qr.py
├── requirements.txt
├── README.md
├── examples/
│ └── links.csv
├── tests/
│ └── test_qr_core.py
└── output/
├── website.png
├── arabic.png
└── batch/بعد فك الضغط، افتح الطرفية داخل مجلد المشروع وثبّت التبعيات ثم شغّل الاختبارات:
python -m pip install -r requirements.txt
python -m unittest discover -s tests -vالاختبارات تغطي إنشاء صورة PNG، والتعامل مع نص عربي، ورفض البيانات الفارغة، والألوان المتطابقة، وتنظيف أسماء الصور.
الأخطاء الشائعة عند إنشاء QR Code ببايثون
| المشكلة | السبب المحتمل والحل |
|---|---|
No module named qrcode | شغّل python -m pip install "qrcode[pil]" بالمفسّر الصحيح |
| الصورة لا تظهر | تحقق من مجلد التشغيل ومسار الحفظ، واستخدم مجلد output |
| الهاتف لا يقرأ الرمز | ارفع التباين، لا تقص الهامش الأبيض، وجرّب زيادة box_size |
| النص العربي غير صحيح | احفظ ملفات Python وCSV بترميز UTF-8 |
| الرمز كبير أو مزدحم | قلّل طول النص أو الرابط، ولا ترفع مستوى تصحيح الأخطاء دون حاجة |
DataOverflowError | البيانات تتجاوز سعة رمز QR؛ اختصر المحتوى |
إذا أردت التوسع في كتابة برامج قصيرة قابلة للتجربة، راجع أوامر بايثون الأساسية للمبتدئين. وللتفاصيل التقنية عن مكتبة توليد الرموز يمكنك الاطلاع على توثيق مكتبة qrcode على GitHub.
الأسئلة الشائعة عن QR Code في بايثون
هل يمكن إنشاء QR Code باستخدام بايثون دون إنترنت؟
نعم، بعد تثبيت مكتبة qrcode وPillow، يمكن توليد الرمز محليًا دون إرسال الرابط أو النص إلى خادم خارجي.
هل يدعم QR Code النص العربي؟
نعم، يمكنك استخدام نص عربي مباشرة، كما في المثال السابق. اختبر النتيجة باستخدام قارئ QR على الهاتف للتأكد من عرض النص كما تريد.
هل يمكن حفظ QR بصيغة PNG؟
نعم. جميع الأمثلة في هذا الدرس تحفظ الصور بصيغة PNG باستخدام save().
هل يمكن وضع شعار داخل رمز QR؟
يمكن ذلك باستخدام أدوات تنسيق متقدمة، لكنه قد يؤثر في إمكانية قراءة الرمز. لهذا لم نضف شعارًا داخل QR في هذا الدرس؛ ضَع العلامة المائية خارج مساحة الرمز عند تصميم صور المقال.
هل يمكن تغيير الرابط بعد إنشاء صورة QR؟
إذا خزّنت رابطًا مباشرًا داخل QR ثابت، فلن يتغير الرابط داخل الصورة إلا بإعادة إنشاء الرمز. الروابط القابلة للتغيير لاحقًا تحتاج وسيط إعادة توجيه تتحكم به، وليست ميزة تلقائية في مكتبة qrcode.