تخصيص ErrorWidget في Flutter بواجهة بديلة بسيطة ورسالة عامة، مع إبقاء التشخيص وفهم الفرق بين خطأ البناء وفشل الشبكة والاستثناء غير المتزامن.
واجهة بديلة لا إصلاح للسبب
ErrorWidget.builder يحدد ما يعرضه الإطار عندما يفشل بناء widget في سياق يتعامل معه بهذه الآلية. تغيير شكله لا يصلح الخطأ الأصلي ولا يجعل التطبيق خاليًا من الأعطال. ابدأ بتشخيص stack trace وإصلاح المصدر، ثم صمم بديلًا يساعد المستخدم إذا وقع فشل غير متوقع. المثال يسبب خطأ بناء محليًا عند الضغط لتجربة البديل، ويعلن أنه demo؛ لا يستخدم ذلك لإخفاء مشكلة حقيقية في تطبيق منشور أو ادعاء أن عدم ظهور اللون الأحمر يعني نجاح العملية.
نطاق أنواع الأخطاء
فشل API يمكن تمثيله في حالة بيانات وواجهة إعادة محاولة، ولا يجب تحويل كل رفض طلب إلى ErrorWidget عام. استثناء callback أو عملية async أو خطأ خارج مسار بناء الإطار له معالجة أخرى، فلا تعد أن builder يلتقط كل استثناءات Dart. FlutterError.onError وPlatformDispatcher.onError لهما عقود مختلفة ينبغي فهمها إذا احتجتهما، مع الاحتفاظ بالتشخيص المناسب. لا تستبدل أي handler بدالة فارغة لمجرد أن رسالة الخطأ أزعجتك أثناء التطوير.
اجعل البديل أقل اعتمادًا
الواجهة البديلة ينبغي أن تكون صغيرة وقادرة على العمل عندما يكون جزء من الشجرة غير سليم. لا تجلب صورة شبكة أو تعتمد خدمة غير متاحة أو تقرأ ThemeExtension غير مضمون ثم تفرض ! داخل fallback، وإلا قد يفشل البديل نفسه. SafeErrorPanel في المثال يستخدم Directionality ولونًا ونصًا محليًا بأسلوب واضح. لا يطلب ملفات assets أو أصناف مشروع خاصة. إذا كان مكان الخطأ صغيرًا فراجع القيود؛ لا تعيد Column طويلة بارتفاع غير محدود إلى موضع بطاقة ضيقة.
رسالة عامة للمستخدم
عرض details.exception.toString كاملًا قد يكشف مسارات أو بيانات أو تفاصيل لا تساعد المستخدم. استخدم رسالة مفهومة في الواجهة، مع تشخيص تقني مناسب في بيئة التطوير أو قناة تقارير تراعي الخصوصية. المثال لا يرسل سجلات إلى طرف ثالث ولا يسجل مدخلات شخصية. لا تربط زر إعادة محاولة عام بإعادة تنفيذ معاملة حساسة لمجرد أن fallback ظهر؛ تحتاج معرفة العملية وحالتها وقرارًا يمنع التكرار غير المقصود. البديل العام لا يملك تلك المعرفة تلقائيًا.
مكان التسجيل والتجربة
سجل builder قبل تشغيل التطبيق أو في موضع تهيئة واضح، لا داخل build في كل شاشة حتى لا يتغير الإعداد العام مع التنقل. إذا اختبرت عدة تطبيقات في عملية اختبار واحدة فاحفظ builder السابق وأعده بعد الاختبار كي لا تتسرب الحالة إلى اختبارات أخرى. لا تعطل FlutterError الافتراضي في المثال؛ سيظل خطأ البناء متاحًا للتشخيص. الاختبار المتوقع لخطأ متعمد يجب أن يستهلك الاستثناء المبلَّغ عنه ويؤكد ظهور البديل، لا يتجاهل كل الأخطاء في المجموعة.
المراجعة بعد الإصلاح
اختبر SafeErrorPanel وحده ثم مسار الخطأ المتعمد مع مساحة صغيرة وخط كبير، وتأكد أن الرسالة لا تتضمن تفاصيل الخطأ الخام. أصلح widget المكسورة في المنتج وأعد فحص التدفق الأصلي بدل الاكتفاء بوجود fallback. أضف حالات فشل الشبكة والتحقق من النموذج في أماكنها الطبيعية، فالمستخدم يحتاج معرفة ما يمكنه تصحيحه وما يحتاج إعادة محاولة. المثال لا يضمن تعافي التطبيق من كل انهيار أو عطل منصة، وإنما يشرح إعدادًا محددًا ويحافظ على الفصل بين العرض البديل والتشخيص والإصلاح.
مثال مستقل للتجربة
شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material فقط ولا يحتاج assets أو أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'package:flutter/material.dart';
void main() {
ErrorWidget.builder = (_) => const SafeErrorPanel();
runApp(const MaterialApp(home: DemoPage()));
}
class SafeErrorPanel extends StatelessWidget {
const SafeErrorPanel({super.key});
@override
Widget build(BuildContext context) => const Directionality(
textDirection: TextDirection.ltr,
child: ColoredBox(color: Color(0xFF263238), child: Padding(
padding: EdgeInsets.all(8), child: Text('Unable to display this section.', style: TextStyle(color: Colors.white, fontSize: 14)),
)),
);
}
class BrokenSection extends StatelessWidget {
const BrokenSection({super.key});
@override
Widget build(BuildContext context) => throw StateError('Demo build failure');
}
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
bool _broken = false;
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Fallback demo')),
body: ListView(padding: const EdgeInsets.all(16), children: [
const Text('This demo intentionally reports one build error when triggered.'),
ElevatedButton(onPressed: () => setState(() { _broken = true; }), child: const Text('Trigger demo error')),
const SizedBox(height: 16),
if (_broken) const BrokenSection() else const Text('Section ready'),
]),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






