الودجات المخصصة والرسم المخصص

تغليف الودجات كمكتبة مشتركة

16 دقيقة الدرس 12 من 12

تغليف الودجات كمكتبة مشتركة

مع نمو مشاريع Flutter الخاصة بك، ستبني حتماً ودجات قابلة لإعادة الاستخدام تستحق أن تعيش في حزمة مستقلة بدلاً من تكرارها عبر تطبيقات متعددة. تتيح لك حزمة Dart استخراج تلك الودجات إلى وحدة ذات إصدار قابلة للاختبار بشكل مستقل مع واجهة برمجية عامة نظيفة. يمكن لأي تطبيق Flutter بعد ذلك الإعلان عنها كاعتمادية واستيرادها تماماً مثل أي حزمة على pub.dev.

ملاحظة: تحتوي إضافة Flutter على كود خاص بالمنصة (أصلي)، بينما حزمة Flutter هي Dart/Flutter خالصة. عند تغليف ودجات واجهة المستخدم، تقوم دائماً تقريباً بإنشاء حزمة عادية وليس إضافة.

إنشاء هيكل الحزمة

استخدم واجهة سطر أوامر Flutter لتوليد الكود التمهيدي. يُنتج الإعلام --template=package حزمة Dart خالصة؛ بينما --template=plugin يضيف قنوات أصلية بدلاً من ذلك.

إنشاء حزمة جديدة

# إنشاء حزمة باسم "my_ui_kit" في مجلد شقيق
flutter create --template=package my_ui_kit

# الهيكل الناتج:
# my_ui_kit/
#   lib/
#     my_ui_kit.dart   <-- ملف البرميل الرئيسي
#   test/
#   pubspec.yaml
#   README.md
#   CHANGELOG.md
#   LICENSE

إعداد pubspec.yaml

يُعلن ملف pubspec.yaml عن هوية الحزمة، وقيود SDK، والاعتماديات. احتفظ بالإصدار وفق Semantic Versioning (MAJOR.MINOR.PATCH). اضبط publish_to: none إذا كانت الحزمة خاصة وغير مخصصة لـ pub.dev.

نموذج pubspec.yaml لمكتبة ودجات

name: my_ui_kit
description: A shared Flutter widget library for ESB apps.
version: 1.0.0
publish_to: none   # احذف هذا السطر للنشر على pub.dev

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=3.10.0'

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0

flutter:
  uses-material-design: true

تنظيم ملفات مصدر المكتبة

ضع كل ودجت في ملفه الخاص تحت lib/src/. دليل src/ هو اتفاقية تشير إلى تفاصيل التنفيذ الخاصة. الملفات داخل src/ لا يمكن استيرادها مباشرة من قِبل المستهلكين — يجب أن تمر عبر ملف البرميل.

تخطيط المكتبة الموصى به

lib/
  my_ui_kit.dart          <-- البرميل العام (الملف الوحيد الذي يستورده المستهلكون)
  src/
    widgets/
      primary_button.dart
      avatar_badge.dart
      status_chip.dart
    theme/
      app_colors.dart
      app_text_styles.dart
    utils/
      responsive_helper.dart

كتابة ملف برميل نظيف

ملف البرميل (lib/my_ui_kit.dart) هو نقطة الدخول الوحيدة للمستهلكين. يُعيد تصدير كل رمز عام باستخدام توجيهات export. يُفضَّل استخدام جمل show أو hide المُسماة للتحكم الدقيق في المعرِّفات المرئية.

lib/my_ui_kit.dart — ملف البرميل

/// My UI Kit — shared Flutter widget library.
library my_ui_kit;

export 'src/widgets/primary_button.dart';
export 'src/widgets/avatar_badge.dart';
export 'src/widgets/status_chip.dart' show StatusChip, StatusType;
export 'src/theme/app_colors.dart';
export 'src/theme/app_text_styles.dart';
نصيحة: لا تُصدِّر مساعدي src/utils/ ما لم يحتجهم المستهلكون فعلاً. الاحتفاظ بالأدوات الداخلية غير مُصدَّرة يتيح لك إعادة الهيكلة بحرية دون كسر الواجهة البرمجية العامة.

استهلاك الحزمة في تطبيق Flutter

هناك ثلاث طرق للاعتماد على حزمة محلية: اعتمادية مسار (للمستودعات المتجاورة)، واعتمادية git (تشير إلى commit أو فرع محدد)، واعتمادية مستضافة (منشورة على pub.dev أو سجل خاص). اعتماديات المسار هي الأكثر شيوعاً أثناء التطوير.

الإشارة إلى الحزمة في pubspec.yaml للتطبيق المستهلك

dependencies:
  flutter:
    sdk: flutter

  # اعتمادية مسار محلي (مستودع مُدمج / مجلدات متجاورة)
  my_ui_kit:
    path: ../my_ui_kit

  # أو — اعتمادية git (فرع محدد)
  # my_ui_kit:
  #   git:
  #     url: https://github.com/yourorg/my_ui_kit.git
  #     ref: main

بعد تحديث pubspec.yaml، شغِّل flutter pub get. يمكنك الآن استيراد واستخدام أي ودجت مُصدَّر باستيراد واحد فقط:

استخدام الودجات من المكتبة المشتركة

import 'package:my_ui_kit/my_ui_kit.dart';

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          AvatarBadge(
            imageUrl: 'https://example.com/user.jpg',
            isOnline: true,
          ),
          const SizedBox(height: 16),
          StatusChip(status: StatusType.active),
          const SizedBox(height: 24),
          PrimaryButton(
            label: 'Get Started',
            onPressed: () => Navigator.pushNamed(context, '/onboarding'),
          ),
        ],
      ),
    );
  }
}

انضباط الإصدار وسجل التغييرات

في كل مرة تُغيِّر فيها الواجهة البرمجية العامة، ارفع الإصدار في pubspec.yaml وأضف إدخالاً إلى CHANGELOG.md. اتبع Semantic Versioning:

  • PATCH (1.0.0 → 1.0.1) — إصلاح أخطاء، لا تغييرات في الواجهة البرمجية
  • MINOR (1.0.0 → 1.1.0) — واجهة برمجية جديدة متوافقة مع الإصدارات السابقة
  • MAJOR (1.0.0 → 2.0.0) — تغييرات كاسرة (صادرات محذوفة أو مُعادة تسميتها)
تحذير: إزالة رمز كان مُصدَّراً سابقاً أو إعادة تسميته هو تغيير كاسر. سيواجه المستهلكون أخطاء تصريف عند pub get التالي. احرص دائماً على إيصال التغييرات الكاسرة بوضوح في CHANGELOG ورفع الإصدار الرئيسي.

الخلاصة

يتضمن تغليف الودجات في مكتبة Dart مشتركة أربع خطوات رئيسية: الهيكلة بـ flutter create --template=package، والإعداد عبر pubspec.yaml بقيود SDK صحيحة واعتماديات، والتنظيم بوضع الملفات تحت lib/src/ مع ملف برميل نظيف كنقطة دخول عامة وحيدة، والاستهلاك عبر اعتمادية مسار أو git أو مستضافة. يُنتج اتباع هذا النمط مكتبات ودجات قابلة لإعادة الاستخدام والاختبار المستقل وتتوسع بسلاسة عبر تطبيقات Flutter متعددة.

اكتمل الدرس!

تهانينا! لقد أكملت جميع الدروس في هذا البرنامج التعليمي.

الدرس السابق الشرائح والعروض المخصصة للتمرير
العودة للدورة تطوير التطبيقات باستخدام Flutter و Dart
العودة للدورة