الحزم في Flutter: pub.dev وملف pubspec.yaml

تريد أن يفتح تطبيقك الكاميرا، أو يعرض خريطة، أو يرسم مخططاً بيانياً، أو يتصل بالإنترنت. هل تكتب كل ذلك من الصفر؟ بالطبع لا. آلاف المبرمجين كتبوا هذه الأشياء من قبل ونشروها مجاناً على شكل حزم (Packages). في هذا الدرس ستتعلم كيف تجد الحزمة المناسبة، وتضيفها إلى مشروعك، وتستخدمها.

ما هي الحزمة؟

الحزمة كود جاهز كتبه غيرك لحل مشكلة محددة، تضيفه إلى مشروعك بسطر واحد.

تخيّل أنك تبني بيتاً: لن تصنع الأبواب والنوافذ والمفاتيح الكهربائية بيدك، بل تشتريها جاهزة وتركّبها. الحزم هي هذه القطع الجاهزة، والموقع pub.dev هو السوق الذي تجدها فيه كلها.

حزم ستقابلها كثيراً:

الحزمة	وظيفتها
http	الاتصال بالإنترنت وجلب البيانات
shared_preferences	حفظ إعدادات بسيطة على الجهاز
provider	إدارة حالة التطبيق
intl	تنسيق التواريخ والأرقام والعملات
url_launcher	فتح الروابط والاتصال برقم هاتف
image_picker	اختيار صورة من المعرض أو الكاميرا
google_fonts	استخدام خطوط Google بسهولة

ملف pubspec.yaml

كل مشروع Flutter فيه هذا الملف في جذره. إنه بطاقة تعريف المشروع: اسمه، وإصداره، والحزم التي يعتمد عليها، وملفاته من صور وخطوط.

pubspec.yaml

name: my_app
description: "تطبيقي الأول."
version: 1.0.0+1

environment:
  sdk: ^3.13.7

dependencies:
  flutter:
    sdk: flutter
  intl: ^0.20.3

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true

القسم	معناه
name	اسم المشروع، بحروف إنجليزية صغيرة وشرطة سفلية
version	الإصدار. ما قبل + يراه المستخدم، وما بعده رقم البناء
environment	إصدار Dart المطلوب
dependencies	الحزم التي يحتاجها التطبيق ليعمل
dev_dependencies	حزم تحتاجها أنت أثناء التطوير فقط، مثل أدوات الاختبار، ولا تدخل في التطبيق النهائي
flutter	إعدادات Flutter: الصور والخطوط

المسافات جزء من المعنى

في ملفات YAML تحدد الإزاحة من يتبع مَن. كل مستوى يُزاح بمسافتين، ولا تستخدم مفتاح Tab أبداً. سطر مزاح بمسافة زائدة يكفي لفشل قراءة الملف كله.

إضافة حزمة

أسهل وأضمن طريقة هي الأمر التالي في الطرفية من داخل مجلد المشروع:

flutter pub add intl

هذا الأمر يفعل شيئين: يكتب السطر في pubspec.yaml بأحدث إصدار مناسب، ثم ينزّل الحزمة. والطريقة الثانية أن تكتب السطر بيدك تحت dependencies ثم تنفّذ:

flutter pub get

الأمر	وظيفته
flutter pub add <الاسم>	يضيف حزمة وينزّلها
flutter pub remove <الاسم>	يحذف حزمة
flutter pub get	ينزّل كل الحزم المكتوبة في الملف
flutter pub upgrade	يحدّث الحزم إلى أحدث إصدار مسموح
flutter pub outdated	يعرض الحزم التي لها إصدارات أحدث

ما معنى ^0.20.3؟

الإصدار ثلاثة أرقام: رئيسي.فرعي.تصحيح. والعلامة ^ تعني: «اقبل أي إصدار أحدث متوافق مع هذا». فالقيد ^1.6.0 يقبل 1.6.1 و 1.9.0، لكنه يرفض 2.0.0، لأن تغيّر الرقم الرئيسي يعني تغييرات قد تكسر كودك.

وستلاحظ ملفاً اسمه pubspec.lock يتولد تلقائياً. فيه الإصدار الدقيق الذي نُزّل فعلاً من كل حزمة، حتى يحصل كل من يعمل على المشروع على نفس الإصدارات بالضبط. لا تعدّله بيدك.

كيف تختار حزمة جيدة؟

ليست كل الحزم بنفس الجودة. قبل أن تضيف حزمة، افتح صفحتها في pub.dev وانظر إلى:

1. الإعجابات (Likes) وعدد التنزيلات: كم مبرمجاً يثق بها ويستخدمها؟
2. نقاط الجودة (Pub Points): تقييم آلي من 160 للتوثيق وجودة الكود ودعم المنصات.
3. تاريخ آخر تحديث: حزمة لم تُحدَّث منذ ثلاث سنوات قد لا تعمل مع Flutter الحالي.
4. المنصات المدعومة: هل تعمل على أندرويد و iOS والويب، أم على بعضها فقط؟
5. الناشر الموثَّق: علامة بجانب اسم الناشر، مثل dart.dev و flutter.dev، تعني أن الحزمة من جهة معروفة.

أقل حزم ممكنة

كل حزمة تضيفها تكبّر حجم التطبيق، وتضيف كوداً لا تتحكم فيه، وقد تتوقف صيانتها يوماً ما. لا تضف حزمة من أجل شيء تكتبه أنت في عشرة أسطر.

استخدام الحزمة

بعد الإضافة، استورد الحزمة في أعلى الملف:

import 'package:intl/intl.dart';

لنجرب حزمة intl في تنسيق التواريخ والأرقام. بدونها ستكتب كوداً طويلاً لتحويل 1250000 إلى 1,250,000:

import 'package:intl/intl.dart';

void main() {
  final date = DateTime(2026, 11, 11, 14, 5);

  print(DateFormat('yyyy/MM/dd').format(date));
  print(DateFormat('hh:mm a').format(date));
  print(NumberFormat.decimalPattern().format(1250000));
  print(NumberFormat('#,##0.00').format(1250.5));
  print(NumberFormat.compact().format(1250000));
}

الناتج

2026/11/11
02:05 PM
1,250,000
1,250.50
1.25M

• DateFormat('yyyy/MM/dd'): نمط التاريخ. yyyy السنة، و MM الشهر، و dd اليوم، و hh:mm a الوقت بنظام 12 ساعة.
• NumberFormat.decimalPattern(): فواصل الآلاف.
• NumberFormat('#,##0.00'): فواصل الآلاف مع خانتين عشريتين دائماً، وهو مناسب للأسعار.
• NumberFormat.compact(): الصيغة المختصرة للأرقام الكبيرة، كما تراها في عدد المشاهدات.

المشروع: فاتورة منسقة

lib/invoice_card.dart

import 'package:flutter/material.dart';
import 'package:intl/intl.dart';

class InvoiceCard extends StatelessWidget {
  const InvoiceCard({super.key});

  @override
  Widget build(BuildContext context) {
    final date = DateTime(2026, 11, 11);
    const amount = 1250000.5;
    const views = 48200;

    final dateText = DateFormat('yyyy/MM/dd').format(date);
    final amountText = NumberFormat('#,##0.00').format(amount);
    final viewsText = NumberFormat.compact().format(views);

    return Scaffold(
      appBar: AppBar(title: const Text('الفاتورة')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Card(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              ListTile(
                leading: const Icon(Icons.calendar_today),
                title: const Text('التاريخ'),
                trailing: Text(dateText),
              ),
              ListTile(
                leading: const Icon(Icons.payments_outlined),
                title: const Text('المبلغ'),
                trailing: Text('$amountText جنيهاً'),
              ),
              ListTile(
                leading: const Icon(Icons.visibility_outlined),
                title: const Text('المشاهدات'),
                trailing: Text(viewsText),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

البطاقة تعرض التاريخ 2026/11/11، والمبلغ 1,250,000.50 جنيهاً، والمشاهدات 48.2K. ثلاثة أسطر من حزمة جاهزة أغنتك عن عشرات الأسطر.

جرّب بنفسك

1. أضف حزمة intl إلى مشروعك وشغّل بطاقة الفاتورة.
2. غيّر نمط التاريخ إلى 'dd-MM-yyyy'.
3. افتح pub.dev وابحث عن url_launcher، واقرأ نقاطها وتاريخ آخر تحديث لها والمنصات التي تدعمها.
4. تحدٍّ: أضف حزمة google_fonts واستخدم منها خطاً عربياً لعنوان الشاشة، مستعيناً بالمثال في صفحة الحزمة.

أخطاء شائعة

• استخدام الحزمة دون pub get: يظهر الخطأ «Target of URI doesn’t exist». نفّذ flutter pub get، وأحياناً تحتاج إلى إعادة تشغيل التطبيق كاملاً.
• إزاحة خاطئة في pubspec.yaml: الحزمة يجب أن تكون تحت dependencies بمسافتين بالضبط.
• إضافة الحزمة تحت dev_dependencies بالخطأ: تعمل أثناء التطوير، ثم يفشل بناء النسخة النهائية.

اختبر نفسك

سؤال

ما الأمر الذي يضيف حزمة إلى المشروع وينزّلها في خطوة واحدة؟

flutter pub addflutter installdart create

سؤال

القيد ^1.6.0 في pubspec.yaml يقبل أي الإصدارات التالية؟

0.9.01.8.22.0.0

الخلاصة

• الحزم كود جاهز تجده في pub.dev، وتضيفه بـ flutter pub add.
• pubspec.yaml بطاقة تعريف المشروع، وهو حساس للمسافات.
• dependencies لحزم التطبيق، و dev_dependencies لأدوات التطوير.
• العلامة ^ تقبل التحديثات المتوافقة فقط، و pubspec.lock يثبّت الإصدارات الدقيقة.
• قيّم الحزمة قبل إضافتها: الإعجابات والنقاط وتاريخ التحديث والمنصات.