البحث في API باستخدام Flutter يحتاج أكثر من تشغيل الطلب عند كل حرف. قد يصل طلب كلمة قديمة بعد طلب أحدث فيستبدل النتائج الصحيحة، وقد تتراكم اتصالات لا يريدها المستخدم. سنجمع Debounce مع إلغاء الطلب وفحص رقم الجيل، لأن الاعتماد على الإلغاء وحده لا يحسم كل سباقات التنفيذ.
تحديد دورة حياة البحث
المثال يستورد NewsRepository وArticle من api_client.dart في درس Repository. احفظ الملف التالي باسم search.dart، وأنشئ SearchCubit عبر BlocProvider الذي يتولى إغلاقه. يعتمد البحث على نقطة /news في خادمك وتعيد articles؛ غيّر العقد في المستودع إذا اختلفت الخدمة، وليس داخل Widget.
import 'dart:async';
import 'package:dio/dio.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'api_client.dart';
class SearchState {
const SearchState({this.items = const [], this.loading = false, this.error});
final List<Article> items;
final bool loading;
final String? error;
}
class SearchCubit extends Cubit<SearchState> {
SearchCubit(this.repository) : super(const SearchState());
final NewsRepository repository;
Timer? _timer;
CancelToken? _cancel;
int _generation = 0;
void changed(String text) {
final generation = ++_generation;
_timer?.cancel();
_cancel?.cancel();
final query = text.trim();
if (query.isEmpty) {
emit(const SearchState());
return;
}
emit(const SearchState(loading: true));
_timer = Timer(const Duration(milliseconds: 350), () async {
final token = CancelToken();
_cancel = token;
try {
final data = await repository.search(query, cancelToken: token);
if (!isClosed && generation == _generation) {
emit(SearchState(items: List.unmodifiable(data)));
}
} catch (_) {
if (!isClosed && generation == _generation && !token.isCancelled) {
emit(const SearchState(error: 'تعذر البحث؛ أعد المحاولة'));
}
}
});
}
@override
Future<void> close() {
_generation++;
_timer?.cancel();
_cancel?.cancel();
return super.close();
}
}
ربط الحقل بحالة الشاشة
مرر onChanged إلى changed، واعرض state.loading ثم state.error ثم القائمة أو رسالة عدم وجود نتائج. عندما يفرغ الحقل نلغي الطلب ونرجع لحالة محايدة. قائمة فارغة بعد بحث ناجح ليست خطأ اتصال، كما أن المستخدم الذي لم يبدأ البحث لا يحتاج مؤشر انتظار مستمرًا.
المهلة 350 مللي ثانية اختيار قابل للتعديل وليست قاعدة ثابتة لكل لغة. إذا احتجت حدًا أدنى لطول الاستعلام، عرّفه بما يناسب الكلمات العربية ولا تمنع كلمات صحيحة قصيرة عشوائيًا. لا ترسل النص الفارغ إلى الخادم مع كل مسافة.
منع النتائج القديمة
يزداد generation فور تغير النص، قبل بدء المؤقت الجديد. عند وصول الاستجابة لا يحق لها إصدار الحالة إلا إذا بقي رقمها أحدث رقم وكان Cubit مفتوحًا. هذا يحمي حتى عندما يتجاهل مصدر وهمي أو مكتبة أخرى الإلغاء. إغلاق Cubit يلغي Timer والطلب حتى لا تصدر حالة بعد مغادرة الشاشة.
اختبارات يجب ألا تُهمل
اختبر كتابة كلمتين بسرعة، وعودة الطلب الأول متأخرًا، ومسح الحقل أثناء الطلب، وفشل الشبكة، وإغلاق الشاشة. استخدم itemCount من طول النتائج، لا رقمًا ثابتًا مثل 10. احتفظ بمفاتيح مزوّد البحث في الخادم حيث يلزم، وتجنب تسجيل نصوص بحث المستخدمين إذا كانت قد تحتوي بيانات خاصة.
مراجع التنفيذ
لإكمال هذا الجزء، انتقل إلى عرض بيانات API في Flutter: قائمة أخبار وحالات التحميل والخطأ، ثم طبّق الربط الذي يناسب بنية مشروعك.






