حفظ موضع ListView باستخدام PageStorage في Flutter مع مفاتيح مستقلة وعمر واضح للـ bucket، وفهم الفرق بين استعادة موضع داخل الجلسة والحفظ الدائم.
ما الذي يحفظه المثال؟
عندما تبدل قائمة بأخرى وتزال الأولى من الشجرة قد تفقد موضعها إذا لم تكن هناك آلية مناسبة. PageStorage يتيح حفظ بعض الحالة في bucket باقٍ، ويمكن للقائمة حفظ offset واستعادته عند إنشائها مجددًا بالمفتاح نفسه. هذا لا يكتب إلى قاعدة بيانات ولا يضمن العودة بعد إغلاق عملية التطبيق. المثال يعرض قائمتين بالتبادل ويحافظ على bucket داخل State الأب الذي يبقى حيًا، حتى يمكن تجربة الفرق بين إزالة widget وإزالة مالك التخزين نفسه.
عمر bucket أهم من اسم المفتاح
إذا أنشأت PageStorageBucket جديدًا داخل build في كل مرة فقد تتخلص من القيم التي تريد الاحتفاظ بها. وإذا وضعت bucket عامًا بلا حدود واضحة فقد تحتفظ بحالة من مستخدم أو تدفق سابق أكثر مما تحتاج. في المثال يملك shell مثيلًا ثابتًا لعمره، وتنتهي مسؤولية الحفظ عند إزالة ذلك shell. اختيار العمر جزء من التصميم، وليس ضرورة أن يكون المتغير عامًا أو أن يستمر إلى الأبد. المسارات قد توفر PageStorage أصلًا، فلا تضف واحدًا آخر دون معرفة النطاق الذي تريد استعماله.
مفاتيح مستقلة ومستقرة
PageStorageKey يساعد على تمييز مواضع القوائم ضمن النطاق. أعطِ قائمة Recent مفتاحًا يختلف عن Saved، وأبقِ القيمة مرتبطة بهوية القائمة بدل عنوان مترجم أو رقم يتغير بعد إعادة ترتيب التبويبات. لا تستعمل المفتاح نفسه لقائمتين تريد حفظهما منفصلتين ثم تعتبر انتقال الموضع بينهما خطأ في Flutter. كذلك لا تستخدم UniqueKey متغيرًا في كل بناء لهذا الغرض؛ هو يغير الهوية بدل تعريف خانة ثابتة لاستعادة الموضع.
علاقة ScrollController
keepScrollOffset في ScrollController يشارك في حفظ موضع التمرير عبر PageStorage ويكون مفعّلًا افتراضيًا. إذا عطلته عمدًا فأنت تختار سياسة أخرى، مثل استعادة قيمة يدويًا كما في المقال المرتبط. initialScrollOffset ليس أمر انتقال يتكرر في كل build، وقد تُفضّل عليه قيمة محفوظة عند توفرها. لا تشارك controller واحدًا بين قائمتين ثم تقرأ position باعتبار أن له موضعًا واحدًا دائمًا. إذا أنشأت controller بنفسك فحدد مالكه وأنهِه في dispose.
البيانات قد تتغير
offset بكسلي يعيد تقريبًا موضعًا بصريًا في القائمة نفسها، لكنه لا يمثل هوية المقال الذي كان المستخدم يقرأه. إذا تغير الفرز أو أضيفت عناصر أو تغير ارتفاع الصفوف بسبب اللغة والخط، فقد يشير الرقم إلى محتوى مختلف. في منتج قراءة مهم قد تحتاج معرّف عنصر مع إزاحة داخلية أو آلية استعادة أوسع. اختبر قائمة أقصر بعد تحديث البيانات ولا تربط نجاح مثال ثابت بوعد حفظ مضمون لكل محتوى ديناميكي أو pagination غير مكتمل التحميل.
اختبار نطاق الحفظ
مرر القائمة الأولى إلى منتصفها، وبدل إلى الثانية ومررها إلى مكان آخر، ثم عد إلى كل واحدة وتأكد من استقلال الموضعين. بعد إزالة الصفحة المالكة للـ bucket لا تتوقع استمرار القيم كما لو كانت على القرص. اختبر النص الكبير وتغيير حجم النافذة وحالة القائمة الفارغة. المثال لا يحتاج اتصالًا أو بيانات شخصية، ويعرض عناصر ثابتة بارتفاع محدد لتبقى المقارنة واضحة. اختر تخزينًا دائمًا أو restoration عند وجود متطلبات مختلفة، مع تحديد ما يحدث لموضع قديم لم يعد صالحًا للبيانات الجديدة.
مثال مستقل للتجربة
شغّل المثال داخل مشروع 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 _bucket = PageStorageBucket();
int _index = 0;
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('PageStorage positions')),
body: Column(children: [
Padding(padding: const EdgeInsets.all(8), child: Wrap(spacing: 8, children: [
TextButton(onPressed: () => setState(() { _index = 0; }), child: const Text('Recent')),
TextButton(onPressed: () => setState(() { _index = 1; }), child: const Text('Saved')),
])),
Expanded(child: PageStorage(bucket: _bucket, child: ListView.builder(
key: PageStorageKey<String>(_index == 0 ? 'recent-lessons' : 'saved-lessons'),
itemExtent: 72, itemCount: 80,
itemBuilder: (_, index) => ListTile(title: Text('${_index == 0 ? 'Recent' : 'Saved'} item ${index + 1}')),
))),
]),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.







