قراءة ملف نصي في Flutter من AssetBundle بترميز UTF-8، وفصل الأسطر باستخدام LineSplitter ومعالجة التحميل والفشل دون تقسيم النص عند حرف n.
ملف مضمّن لا ملف مستخدم
هذه المقالة تقرأ نصًا تشحنه مع التطبيق ضمن assets، مثل تعليمات محلية أو وصف تعليمي. لا تطلب إذن الوصول إلى أي ملف في جهاز المستخدم ولا تقرأ مسارًا من حاسوب المطور على هاتف آخر. إذا احتجت فتح ملف يختاره المستخدم أو تعديله فهذه واجهة مختلفة. حدد مصدر النص وعمره قبل كتابة الكود؛ استبدال asset باسم مسار تنزيل لا يحول loadString إلى قارئ ملفات عام لكل المنصات.
التضمين والترميز
أنشئ assets/data/lesson.txt بترميز UTF-8 وأضف مساره تحت assets في قسم flutter الموجود من pubspec.yaml. طابق الاسم والامتداد وحالة الأحرف، ثم نفذ flutter pub get وأعد البناء عند تغيير تعريف الحزمة إن لزم. لا تكرر قسم flutter أو تفترض أن تعريف مجلد أعلى يضم جميع المجلدات الفرعية بلا مراجعة. الأحرف العربية التي تظهر معطوبة قد تشير إلى مشكلة ترميز المصدر، ولا تُعالج بحذف كل محرف لا يقع ضمن ASCII.
فصل الأسطر الحقيقي
split على الحرف n يقسم كلمات عادية ويترك السطر الجديد في موضعه، لذلك لا يصلح بديلًا عن محرف السطر. LineSplitter من dart:convert يتعامل مع نهايات الأسطر الشائعة مثل LF وCRLF. nonBlankLines في المثال تستبعد الأسطر التي لا تحوي سوى فراغات لكنها تحتفظ بمسافات الأسطر غير الفارغة. هذه سياسة معلنة للعرض، وليست قاعدة لتنظيف كل ملف. إذا كانت الفراغات أو الأسطر الفارغة تحمل معنى في قصيدة أو كود فاحفظها بدل إسقاطها.
اقرأ مرة لكل مصدر
المثال يحصل على DefaultAssetBundle داخل didChangeDependencies وينشئ Future عند تغير الحزمة. FutureBuilder يعرض النتيجة دون إعادة بدء القراءة لكل build، وزر Retry يطلب محاولة جديدة صراحة. عندما تحتاج نصًا ثابتًا صغيرًا لا داعي لنسخه إلى متغير String وقائمة في State ثم مزامنتهما يدويًا بلا سبب. إذا كان المصدر قابلًا للتغيير فحدد كيف تبطل cache ومتى تقرأ النسخة الجديدة، ولا تربط القراءة بكل تغير للثيم أو كل تمرير للقائمة.
العرض والأخطاء
يظهر مؤشر انتظار ثم نص قابل للتحديد وعدد الأسطر غير الفارغة، أو رسالة إعادة محاولة عند الفشل. النص الفارغ نجاح بقيمة فارغة، وليس طلبًا لا ينتهي. لا تعرض exception خامًا في الواجهة العامة ولا تسجل محتوى الملف كاملًا إذا كان لا يلزم للتشخيص. المثال مناسب لنص قصير؛ مستند ضخم يحتاج مراجعة الذاكرة والتخطيط وطريقة العرض بدل وضع آلاف الفقرات في Text واحد وافتراض أن وجود FutureBuilder يكفي لمعالجة الأداء.
فحص النص والحدود
اختبر ملفًا عربيًا وإنجليزيًا ومختلطًا، ونهايات LF وCRLF، ونصًا فارغًا وأسطرًا تحتوي مسافات وحرف n داخل الكلمات. تحقق من عدم فقد محارف Unicode أو تغيير المحتوى المنسوخ عند التحديد. اختبر غياب asset وإعادة المحاولة وحجم الخط والاتجاه والعرض الأفقي. هذا المثال لا يكتب إلى الملف ولا يجعل النص المضمّن قابلًا للتحديث من الخادم؛ إذا كان المنتج يحتاج ذلك فافصل تحميل الشبكة والتخزين والإصدار عن منطق عرض النص المحلي.
ملف التجربة وتعريفه
أنشئ الملف assets/data/lesson.txt بالمحتوى التالي، ثم أضف مساره إلى assets داخل قسم flutter الموجود في pubspec.yaml دون تكرار القسم. شغّل flutter pub get وأعد البناء عند الحاجة.
First line
سطر عربي
Final line
flutter:
assets:
- assets/data/lesson.txt
مثال Dart بعد إعداد الملف
شغّل المثال داخل مشروع Flutter تجريبي. يحتاج ملف assets وتعريفه الموضحين أعلاه، ولا يعتمد أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'dart:convert';
import 'package:flutter/services.dart';
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
List<String> nonBlankLines(String source) => const LineSplitter().convert(source).where((line) => line.trim().isNotEmpty).toList(growable: false);
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
AssetBundle? _bundle;
late Future<String> _future;
Future<String> _load() => _bundle!.loadString('assets/data/lesson.txt');
@override
void didChangeDependencies() {
super.didChangeDependencies();
final bundle = DefaultAssetBundle.of(context);
if (_bundle != bundle) { _bundle = bundle; _future = _load(); }
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Bundled text')),
body: FutureBuilder<String>(future: _future, builder: (_, snapshot) {
if (snapshot.hasError) return Center(child: TextButton(onPressed: () => setState(() { _future = _load(); }), child: const Text('Could not load text. Retry')));
if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());
final text = snapshot.data!;
return ListView(padding: const EdgeInsets.all(16), children: [
Text('Nonblank lines: ${nonBlankLines(text).length}'),
const SizedBox(height: 16),
SelectableText(text.isEmpty ? 'The file is empty' : text),
]);
}),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






