شارك المقالة
إنشاء Stepper في Flutter مع تحقق الخطوة ومنع تجاوز الحدود

إنشاء Stepper في Flutter مع تحقق الخطوة ومنع تجاوز الحدود

إنشاء Stepper في Flutter مع Form Validation قبل الانتقال، وحدود currentStep وأزرار السابق والإنهاء، وفصل اكتمال الواجهة عن نجاح حفظ…

إنشاء Stepper في Flutter مع Form Validation قبل الانتقال، وحدود currentStep وأزرار السابق والإنهاء، وفصل اكتمال الواجهة عن نجاح حفظ البيانات.

مؤشر تقدم لا محرك أعمال

Stepper يرتب مهمة متعددة المراحل ويعرض الخطوة الحالية، لكنه لا ينفذ شراء أو يسجل حسابًا أو يمنح صلاحيات نظام بمجرد الوصول إلى آخر عنصر. حدد بيانات كل مرحلة ومعنى إكمالها وما الذي يمكن الرجوع لتعديله. المثال يجمع اسم درس ثم يعرض مراجعة محلية ويعلن اكتمال العرض فقط. لا توجد خدمة شبكة أو دفع أو مصادقة، ولذلك لا ينبغي نقل رسالة Complete منه إلى تأكيد معاملة في منتج حقيقي.

اضبط حدود currentStep

الفهرس يبدأ من صفر ويجب أن يظل داخل عدد steps. لا تزده بعد آخر خطوة ولا تنقصه قبل الأولى، واستخدم مصدرًا واضحًا لعدد المراحل بدل أرقام مبعثرة يصعب تعديلها. المثال يملك مرحلتين، فينتقل من الإدخال إلى المراجعة ثم يغيّر حالة finished بدل جعل الفهرس يساوي عدد العناصر. إذا تغيرت المراحل بحسب البيانات فراجع الفهرس والمفاتيح وسياسة العودة حتى لا يشير اختيار محفوظ إلى مرحلة لم تعد موجودة.

التحقق قبل التقدم

onStepContinue لا يتحقق من الحقول تلقائيًا، لذلك نطلب validate في المرحلة الأولى ونبقى فيها إذا كان الاسم فارغًا. أما onStepTapped فقد يسمح بالقفز إلى مرحلة لاحقة إذا ربطته بتعيين الفهرس مباشرة دون شرط. المثال يسمح بالرجوع إلى الإدخال، ويطلب التحقق قبل فتح المراجعة عند النقر على عنوانها أيضًا. هذا تحقق محلي لتحسين التفاعل، وتظل قواعد الخادم والصلاحيات مطلوبة في تطبيق متصل. لا تعتبر StepState.complete دليلًا أمنيًا على أن المستخدم أكمل إجراءً موثوقًا.

أزرار لها أسماء دقيقة

controlsBuilder يتيح عرض Next وBack وFinish حسب الموضع. onStepCancel ليس إلغاءً عامًا بالضرورة؛ هنا نستخدمه للرجوع خطوة، لذلك نسمي الزر Back. إذا أردت إلغاء العملية كلها فقدم إجراءً منفصلًا يشرح فقد المسودة أو حفظها. بعد الإنهاء التجريبي نعطل إعادة التنفيذ حتى لا يكرر المستخدم العملية نفسها. في إرسال حقيقي تحتاج حالة submitting ومنع ضغط متكرر ومعالجة فشل وإعادة محاولة وفق عقد الخدمة، لا مجرد زيادة فهرس بسرعة.

موارد الإدخال والتخطيط

TextEditingController مملوك لـ State ويغلق في dispose، ويبقى النص عند الرجوع من المراجعة إلى الإدخال. لا تنشئ controller جديدًا داخل كل Step أو build فتفقد المسودة. Stepper عمودي مناسب لعرض ضيق في هذا المثال، بينما الأفقي يحتاج مساحة وعناوين مختبرة وقد يتزاحم مع اللغة أو النص الكبير. لا تضعه داخل تمرير آخر بقيود مفتوحة دون مراجعة بنيته، ولا تقلص الخط إلى حجم غير مقروء لتناسب كلمة طويلة.

اختبارات مهمة للعملية

جرّب Next والعنوان الثاني مع حقل فارغ؛ يجب أن تظهر الرسالة دون تجاوز التحقق. أدخل نصًا ثم افتح المراجعة وارجع وعدله، وتحقق أن الملخص يعكس القيمة الجديدة. أكمل واضغط مرة أخرى لتتأكد من عدم تجاوز حدود الفهرس. اختبر لوحة المفاتيح والرجوع وحجم الخط والاتجاه العربي. إذا كان المستخدم قد يغادر ويعود فحدد حفظ المسودة وانتهاء صلاحيتها بوضوح؛ وجود Stepper على الشاشة لا يوفر ذلك وحده. وأي عملية حساسة تحتاج تحققًا من نتيجة الخدمة بدل افتراض أن انتهاء الأنيميشن يعني نجاحها.

مثال مستقل للتجربة

شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material فقط ولا يحتاج assets أو أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.

import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class DemoPage extends StatefulWidget {
  const DemoPage({super.key});
  @override
  State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
  final _form = GlobalKey<FormState>();
  final _title = TextEditingController();
  int _step = 0;
  bool _finished = false;
  @override
  void dispose() { _title.dispose(); super.dispose(); }
  void _next() {
    if (_finished) return;
    if (_step == 0) {
      if (!(_form.currentState?.validate() ?? false)) return;
      setState(() { _step = 1; });
    } else {
      setState(() { _finished = true; });
    }
  }
  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('Local stepper')),
    body: Stepper(
      currentStep: _step,
      onStepContinue: _finished ? null : _next,
      onStepCancel: _step == 0 || _finished ? null : () => setState(() { _step = 0; }),
      onStepTapped: (index) {
        if (_finished) return;
        if (index == 0) { setState(() { _step = 0; }); }
        else if (_step == 0) { _next(); }
      },
      controlsBuilder: (_, details) => Wrap(spacing: 8, children: [
        ElevatedButton(onPressed: _finished ? null : details.onStepContinue,
          child: Text(_finished ? 'Demo complete' : _step == 0 ? 'Next' : 'Finish')),
        if (_step > 0 && !_finished) TextButton(onPressed: details.onStepCancel, child: const Text('Back')),
      ]),
      steps: [
        Step(title: const Text('Lesson'), isActive: _step == 0,
          state: _step > 0 ? StepState.complete : StepState.indexed,
          content: Form(key: _form, child: TextFormField(
            controller: _title, decoration: const InputDecoration(labelText: 'Lesson title'),
            validator: (value) => (value ?? '').trim().isEmpty ? 'Enter a title' : null,
          ))),
        Step(title: const Text('Review'), isActive: _step == 1,
          state: _finished ? StepState.complete : StepState.indexed,
          content: Text(_finished ? 'Local demo completed; no data was sent' : 'Review: ${_title.text.trim()}')),
      ],
    ),
  );
}

مرجع الواجهة البرمجية

راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.

الصور والفيديو من الشرح السابق

الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.

شاهد أيضًا
مقالات ذات صلة
🚫 مانع الإعلانات مفعل

يجب إيقاف مانع الإعلانات لاستكمال تصفح الموقع