شارك المقالة
Debounce للبحث في Flutter ومنع عرض النتائج القديمة

Debounce للبحث في Flutter ومنع عرض النتائج القديمة

شرح Debounce للبحث في Flutter لتأخير الطلب حتى يتوقف المستخدم عن الكتابة، مع إلغاء Timer وتجاهل النتائج القديمة بعد تغيّر…

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

المشكلة ليست عدد الطلبات وحده

إرسال طلب عند كل حرف قد يزيد الحمل ويجعل النتائج تتغير بسرعة. Debounce ينتظر فترة هدوء قصيرة بعد آخر تغيير قبل بدء العملية. مدة مثل 350 مللي ثانية نقطة تجربة وليست معيارًا لكل تطبيق؛ راقب سرعة الكتابة وطبيعة البحث وإتاحة التنفيذ من زر لوحة المفاتيح. لا تعد هذه التقنية علاجًا مضمونًا لتعطل التطبيق، لأن التوقف قد يأتي من حساب ثقيل أو بيانات غير صالحة أو تحديث واجهة بعد مغادرتها.

إلغاء المؤقت لا يلغي الطلب الجاري

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

المدخل الفارغ وحالة التحميل

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

دورة حياة الصفحة

ألغِ المؤقت في dispose وزد رقم الجيل كي تتجاهل أي رد لاحق، وافحص mounted قبل setState بعد await. لا تخزن Timer داخل build أو تنشئ Debouncer جديدًا في كل حرف. في طبقة إدارة حالة أخرى انقل الملكية إلى صاحب الحالة نفسه وتخلص من المورد في close المناسب. لا تستخدم debounce لإسقاط عمليات دفع أو زيادات سلة لا يجوز فقد أي منها؛ تجميع هذه العمليات يحتاج تصميمًا يحدد المعنى والتكرار بوضوح.

اختبار السباق

جرب كتابة a ثم ab بسرعة بحيث يصل رد a متأخرًا، وتأكد أن الواجهة تبقى على نتائج ab. اختبر مسح النص قبل انتهاء المهلة، وإغلاق الصفحة أثناء الطلب، واستجابة فاشلة بعد استجابة أحدث ناجحة. المثال المحلي يؤخر مصدر البيانات لإظهار الفكرة دون اتصال خارجي. في المشروع الحقيقي افصل وظيفة البحث عن Widget لتتمكن من محاكاة الردود وترتيبها، وراقب عدد الطلبات بدل الاعتماد على الانطباع البصري وحده.

مثال كامل للتجربة

ضع المثال في ملف مستقل داخل مشروع تجريبي. في أمثلة Flutter شغّل DemoPage داخل MaterialApp، ولا تدمج أكثر من main في الملف نفسه. البيانات محلية للتعلم ويمكن استبدالها بمصدر بيانات بعد فهم حالات النجاح والخطأ.

import 'dart:async';
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> {
  Timer? _timer;
  int _generation = 0;
  bool _loading = false;
  String? _error;
  List<String> _items = [];
  Future<List<String>> _search(String query) async {
    await Future<void>.delayed(const Duration(milliseconds: 100));
    return ['$query result'];
  }
  void _changed(String value) {
    _timer?.cancel();
    final generation = ++_generation;
    final query = value.trim();
    setState(() { _items = []; _error = null; _loading = query.isNotEmpty; });
    if (query.isEmpty) return;
    _timer = Timer(const Duration(milliseconds: 350), () async {
      try {
        final items = await _search(query);
        if (!mounted || generation != _generation) return;
        setState(() { _items = items; _loading = false; });
      } catch (_) {
        if (!mounted || generation != _generation) return;
        setState(() { _error = 'Search failed'; _loading = false; });
      }
    });
  }
  @override
  void dispose() { ++_generation; _timer?.cancel(); super.dispose(); }
  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('Debounce search')),
    body: Column(children: [
      TextField(onChanged: _changed, decoration: const InputDecoration(labelText: 'Search')),
      if (_loading) const LinearProgressIndicator(),
      if (_error != null) Text(_error!),
      Expanded(child: ListView(children: [for (final item in _items) ListTile(title: Text(item))])),
    ]),
  );
}

مرجع التفاصيل والتوافق

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

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

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