شرح تغيير أيقونة Marker في Flutter باستخدام BitmapDescriptor.asset، وضبط حجم الصورة وتحميلها مرة واحدة، مع معالجة أخطاء الأصول والتحديث الآمن للخريطة.
متى تحتاج إلى علامة مخصصة؟
تغيير أيقونة Marker في Flutter يساعدك على التمييز بين موقع العميل والفرع والسائق دون الاعتماد على اللون وحده. العلامة صورة مرتبطة بإحداثيات، وليست عنصر واجهة Flutter عاديًا داخل GoogleMap. ابدأ بخريطة تعمل بالفعل ثم أضف تخصيص الصورة؛ إذا كانت الخريطة فارغة فراجع إعداد Google Maps على Android وiOS قبل البحث عن مشكلة في الأيقونة.
تجهيز ملف الصورة داخل المشروع
أضف صورة PNG واضحة بخلفية شفافة إلى assets/marker.png، ثم سجّل الملف أو المجلد في قسم flutter/assets داخل pubspec.yaml. انتبه إلى حالة الأحرف والامتداد والمسافات، لأن اسمًا يعمل على جهاز التطوير قد يفشل داخل نسخة الإصدار. لا تستخدم صورة ضخمة لمؤشر صغير؛ جهّز الحجم المناسب واختبره على أجهزة ذات كثافات مختلفة بدل تعويض كل اختلاف بتكبير الملف.
تحميل الأيقونة باستخدام BitmapDescriptor.asset
في المثال تُحمّل الصورة عبر BitmapDescriptor.asset ويحدد width العرض المنطقي المطلوب. عملية التحميل غير متزامنة، لذلك نعرض العلامة الافتراضية إلى أن تجهز الصورة. أخذ ImageConfiguration داخل didChangeDependencies يتيح الوصول إلى إعدادات العرض؛ متغير loaded يمنع إعادة التحميل مع كل إعادة بناء. عند اعتماد الحجم على تغيّر كثافة الجهاز أو الثيم، حدّث سياسة التخزين لتعيد التحميل فقط عندما يتغير هذا الإعداد.
تحديث Marker دون أخطاء الحالة
بعد انتهاء التحميل نفحص mounted قبل setState حتى لا نحاول تحديث شاشة أُغلقت. حافظ على MarkerId ثابت للعنصر نفسه وغيّر icon أو position عند الحاجة. استخدام معرّف عشوائي مع كل تحديث يجعل متابعة العلامة أصعب. لاحظ أن تغيير متغير محلي وحده لا يعيد رسم الخريطة؛ يجب أن تصل مجموعة العلامات الجديدة إلى GoogleMap ضمن تحديث الحالة.
متى أستخدم bytes بدل ملف asset؟
إذا كانت الصورة ناتجة عن رسم Canvas أو معالجة صورة ملفتة، يمكن تحويلها إلى PNG bytes ثم بناء BitmapDescriptor.bytes في الإصدارات التي تدعمه. أما الصورة الثابتة الموجودة في التطبيق فمسار asset أبسط ويقلل كود التحويل اليدوي. لا تجعل تحميل صورة شبكة لكل علامة يجري داخل build، ولا تترك طلبات كثيرة تعيد إنشاء الصور نفسها؛ خزّن النتيجة على مستوى الشاشة أو مستودع الأيقونات.
إذا أردت علامة مبنية من Widget مع تأثير نابض بدل صورة Google Maps، راجع تحريك علامات flutter_map وربطها باختيار الموقع. يعتمد هذا المسار على مكتبة مختلفة، لذلك لا تخلط أنواع Marker بين المثالين.
مشكلات شائعة وحلول عملية
عند اختفاء العلامة افحص مسار الأصل وسجل الأخطاء ثم جرّب العلامة الافتراضية. إذا ظهرت الصورة صغيرة أو كبيرة جدًا راجع عرضها المنطقي ومساحتها الشفافة الداخلية؛ أحيانًا تكون المشكلة في هامش الصورة نفسه. لا تستخدم متغير destinationIcon عند إنشاء العلامة من sourceIcon كما في أمثلة غير متسقة. في وضع التحميل الفاشل يبقى المثال على الأيقونة الافتراضية بدل إسقاط الخريطة بالكامل.
اختبار العلامات في سيناريو واقعي
اختبر وجود صورة صحيحة وصورة غير موجودة، ثم افتح الشاشة وأغلقها سريعًا أثناء التحميل. جرّب علامات متعددة للتأكد من عدم تكرار المعرفات، وافحص وضوح الصورة في الوضعين الفاتح والداكن. عند عرض عدة مستخدمين انتقل إلى تنظيم علامات الأشخاص على الخريطة؛ فصل البيانات عن تحميل الأيقونات يجعل تحديث مواضعهم أسرع وأسهل للصيانة.
الإعداد أو عقد التكامل المطلوب
طبّق الجزء المناسب على مشروعك بعد مراجعة إصدار الحزمة والمنصة؛ قيم الإعداد هنا توضيحية وليست مفاتيح صالحة أو خدمة خلفية منشورة.
flutter:
assets:
- assets/marker.pngمثال الكود المراجع
الكود التالي يوضح نطاق الدرس ولا يغني عن إعداد المنصة أو الخدمات المذكورة أعلاه. اختُبر بتحليل Dart واختبارات المنطق المناسبة؛ تشغيل GPS والخرائط والخدمات الخارجية يحتاج جهازًا وإعداداتك الخاصة.
import 'package:flutter/material.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';
class CustomMarkerMap extends StatefulWidget {
const CustomMarkerMap({super.key});
@override
State<CustomMarkerMap> createState() => _CustomMarkerMapState();
}
class _CustomMarkerMapState extends State<CustomMarkerMap> {
BitmapDescriptor icon = BitmapDescriptor.defaultMarker;
bool loaded = false;
@override
void didChangeDependencies() {
super.didChangeDependencies();
if (!loaded) { loaded = true; loadIcon(); }
}
Future<void> loadIcon() async {
final config = createLocalImageConfiguration(context);
try {
final value = await BitmapDescriptor.asset(config, 'assets/marker.png', width: 40);
if (mounted) setState(() => icon = value);
} catch (_) {
// Keep the default marker if the asset cannot be loaded.
}
}
@override
Widget build(BuildContext context) => GoogleMap(
initialCameraPosition: const CameraPosition(target: LatLng(30.0444, 31.2357), zoom: 13),
markers: {Marker(markerId: const MarkerId('destination'),
position: const LatLng(30.0444, 31.2357), icon: icon)},
);
}






