بناء Reusable Widget في Flutter باستخدام معاملات مكتوبة النوع وVoidCallback، مع تنفيذ الضغط وحالات التحميل والتعطيل واتباع الثيم دون فرض قيم null.
إعادة الاستخدام بعقد معلوم
المكوّن المشترك يجمع عرضًا وسلوكًا متكررًا بمعاملات واضحة، مثل زر بعنوان وأيقونة وcallback. الهدف أن تغير تصميمه في مكان واحد وأن يعرف كل مستدعٍ ما الذي يحتاج تمريره. هذا لا يعني وضع كل دوال التطبيق في ملف components ضخم أو تحويل كل سطر إلى widget عام. اختر جزءًا له معنى ثابت وحدود مفهومة، واترك جلب البيانات والتنقل وحفظ الحالة لمالكها ما لم يكن ذلك جزءًا صريحًا من عقد المكوّن.
أنواع المعاملات أهم من عددها
label نص مطلوب، وonPressed من نوع VoidCallback? في المثال، فتدل null على تعطيل الفعل وفق سلوك الزر. لا تجعل كل قيمة اختيارية ثم تستعمل ! دون ضمان؛ هذا يؤجل الخطأ إلى التشغيل. ولا تستخدم Function عامة إذا كنت تعرف التوقيع المطلوب، لأن القارئ والمحلل يفقدان معلومة مهمة. إذا احتاج المكوّن نتيجة غير متزامنة فحدد من يدير التحميل والخطأ ومتى تكتمل العملية بدل إرجاع نوع مبهم يتجاهله كل مستدعٍ بطريقة مختلفة.
الضغط يجب أن يصل إلى callback
المثال القديم كان يستقبل function ثم يرسم Container فقط دون استدعائه، فيبدو زرًا بلا تنفيذ. هنا نستخدم FilledButton حقيقيًا بحدود تفاعل وتركيز وحالات معطلة، ونمرر callback في onPressed. لا تعوض ذلك بـ GestureDetector فوق رسم يشبه الزر دون مراجعة semantics والكيبورد ومساحة الضغط. يمكن بناء مكوّن مخصص عند الحاجة، لكن المظهر وحده لا يجعل العنصر زرًا كامل التجربة على الهاتف وسطح المكتب.
تحميل يملكه صاحب العملية
busy يجعل الزر غير متاح ويعرض مؤشرًا صغيرًا، لكنه لا ينشئ طلب شبكة ولا يلغي عملية. State الصفحة في المثال تضبط busy قبل انتظار تأخير محلي وتحرس الضغط المتكرر ثم تتحقق من mounted. لا تضع Future مجهولة داخل المكوّن وتعلن نجاحًا لأي استدعاء؛ الخدمة الحقيقية قد تفشل وتحتاج رسالة وإعادة محاولة. اجعل الاسم والرسالة يصفان demo لا معاملة فعلية، ولا تسجل بيانات حساسة داخل زر عام لأنه يستعمل في شاشات كثيرة.
الثيم والقيود والنص
المكوّن يتبع FilledButton وثيم التطبيق بدل فرض لون أسود أو أبيض لا يناسب بعض الشاشات. الصف الداخلي يسمح للنص بالمرونة داخل عرض محدود، ونراجع التسمية الطويلة وتكبير الخط. إذا استعملته داخل تمرير أفقي أو Row مفتوحة فحدد قيوده في الأب؛ المكوّن لا يعرف عرض الشاشة تلقائيًا. لا تجعل toUpperCase إجباريًا لكل لغة، فالعربية لا تستخدم حالة الأحرف نفسها، والتحويل قد يغير اسمًا أو تسمية مقصودة. افصل محتوى النص عن زخرفته.
اختبار المكوّن والصفحة
اختبر أن callback ينفذ مرة عند الضغط، وأن null وbusy يمنعانه، وأن النص يظل قابلًا للقراءة داخل عرض ضيق. اختبر بقاء الزر معطلًا طوال العملية ثم عودته بعد اكتمالها، ومغادرة الصفحة قبل اكتمال الانتظار. إعادة الاستخدام تسهل الاختبار والصيانة لكنها لا تضمن سرعة تلقائية أو عدد builds صفريًا؛ قياس الأداء موضوع آخر. هذا المثال يستعمل تأخيرًا محليًا فقط ويزيد عدادًا للتوضيح، ويمكن ربط callback بخدمة حقيقية بعد تصميم عقد الفشل والتحميل المناسب لها.
مثال مستقل للتجربة
شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material فقط ولا يحتاج assets أو أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class LessonActionButton extends StatelessWidget {
const LessonActionButton({super.key, required this.label, required this.onPressed, this.busy = false, this.icon = Icons.menu_book});
final String label;
final VoidCallback? onPressed;
final bool busy;
final IconData icon;
@override
Widget build(BuildContext context) => FilledButton(
onPressed: busy ? null : onPressed,
child: Padding(padding: const EdgeInsets.symmetric(vertical: 12), child: Row(mainAxisSize: MainAxisSize.min, children: [
if (busy) const SizedBox(width: 18, height: 18, child: CircularProgressIndicator(strokeWidth: 2)) else Icon(icon),
const SizedBox(width: 8), Flexible(child: Text(label)),
])),
);
}
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
bool _busy = false;
int _completed = 0;
Future<void> _runDemo() async {
if (_busy) return;
setState(() { _busy = true; });
try {
await Future<void>.delayed(const Duration(milliseconds: 200));
if (mounted) setState(() { _completed++; });
} finally {
if (mounted) setState(() { _busy = false; });
}
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Reusable action button')),
body: ListView(padding: const EdgeInsets.all(16), children: [
LessonActionButton(label: 'Run local demo', onPressed: _runDemo, busy: _busy),
const SizedBox(height: 16),
const LessonActionButton(label: 'Unavailable action', onPressed: null),
Text('Completed demos: $_completed'),
]),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






