شارك المقالة
رسم مسار على Google Maps في Flutter باستخدام Routes API

رسم مسار على Google Maps في Flutter باستخدام Routes API

شرح رسم مسار على Google Maps في Flutter من Routes API، وفك encodedPolyline وقراءة المسافة والمدة، مع التحقق من الاستجابة…

شرح رسم مسار على Google Maps في Flutter من Routes API، وفك encodedPolyline وقراءة المسافة والمدة، مع التحقق من الاستجابة وحماية مفتاح الخادم.

المسار يختلف عن خط بين نقطتين

رسم مسار على Google Maps في Flutter يبدأ باختيار نقطتي الانطلاق والوصول ثم طلب طريق من خدمة مسارات. Polyline يرسم قائمة نقاط فقط، ولا يبحث عن شارع أو يحسب مدة رحلة من تلقاء نفسه. وصل نقطتين بخط مباشر يوضح اتجاهًا هندسيًا، لكنه قد يعبر مباني أو نهرًا. حدّد هل تحتاج أثر الحركة المرصود من GPS أم طريقًا مقترحًا لوسيلة انتقال معينة قبل تنفيذ الدرس.

الحصول على البداية والوجهة

يمكن أن تكون البداية موقعًا اختاره المستخدم أو قراءة حديثة من geolocator بعد الإذن. ويمكن أن تأتي الوجهة من تفاصيل مكان اختير بالبحث. تحقق من صلاحية القيم ووضوح دور كل نقطة، ولا تترك متغيرات late تفترض أن المستخدم اختار وجهة قبل فتح الشاشة. إذا تغيرت الوجهة أثناء طلب الطريق، تجاهل الاستجابة القديمة حتى لا تُظهر مسارًا إلى مكان لم يعد مختارًا.

Compute Routes عبر خادم التطبيق

في Routes API يرسل الخادم POST إلى https://routes.googleapis.com/directions/v2:computeRoutes مع origin وdestination وtravelMode. يحتاج الطلب إلى مصادقة الخدمة والإعدادات المناسبة ومفتاح محمي في الخلفية عند استخدام خدمات الويب. مرر للعميل الحقول اللازمة، ولا تنشئ مسارًا خلفيًا مفتوحًا يسمح لأي شخص بإرسال طلبات مكلفة. المثال أدناه يحلل الاستجابة ويرسم الخط، وليس خادمًا كاملًا يتهيأ بمجرد لصق مفتاح داخل Flutter.

اختيار الحقول وبنية الاستجابة

اطلب عبر X-Goog-FieldMask حقول routes.distanceMeters وroutes.duration وroutes.polyline.encodedPolyline. تستقبل الشفرة routes وقد تكون القائمة فارغة إذا لم يوجد طريق مناسب. لا تخلط هذه البنية مع overview_polyline وlegs في أمثلة Directions القديمة؛ تسمية المتغيرات الجديدة لا تكفي لترحيل محلل يستعمل JSON مختلفًا. عالج الأخطاء والحصص وعدم وجود طريق كحالات واجهة، لا كفهرس routes[0] مضمون الوجود.

فك encodedPolyline بأمان

تختصر Google نقاط المسار في نص مشفر يمكن فكّه إلى قائمة LatLng. الدالة decodeRoute تتحقق من اكتمال المجموعات والرموز وحدود الإحداثيات، وتستخدم الدقة المعتادة 1e5 لهذا التنسيق. ترفض النص التالف بدل إنتاج خط بمواقع غير معروفة. لا تفك نص GeoJSON أو تنسيقًا بدقة أخرى بالدالة نفسها. يضع المثال حدًا لحجم النص لتقليل خطر استهلاك موارد غير متوقع من استجابة غير موثوقة.

بناء Polyline وعرض معلومات الرحلة

تحول routeLine النتيجة إلى Polyline بمعرف ثابت وتستطيع تمريرها إلى polylines في GoogleMap. المسافة بالمتر قيمة عددية، بينما duration سلسلة زمنية من واجهة Google مثل 123s؛ نسّقها للمستخدم بعد تحليل صحيح بدل عرض ثوانٍ كنص دقائق. تحديث الكاميرا لاحتواء الطريق خطوة أخرى تُنفذ بعد جاهزية الخريطة ومساحتها، مع padding لا يغطي عناصر الشاشة أو نسب مزود الخريطة.

الطريق ليس ملاحة صوتية كاملة

وجود خط ومدة تقديرية لا يحول تطبيقك تلقائيًا إلى نظام ملاحة يعيد حساب الطريق ويعطي تعليمات خطوة بخطوة. مدة الطريق تتأثر بالخيارات والمعلومات المتاحة ووقت الطلب، ولا ينبغي عرضها كضمان للوصول. إن أردت زرًا يفتح تجربة Google Maps الخارجية فراجع فتح الاتجاهات دون API Key. وإن أردت رسم أثر المستخدم نفسه فراجع التتبع أثناء فتح الشاشة.

اختبار البيانات والأعطال

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

الإعداد أو عقد التكامل المطلوب

طبّق الجزء المناسب على مشروعك بعد مراجعة إصدار الحزمة والمنصة؛ قيم الإعداد هنا توضيحية وليست مفاتيح صالحة أو خدمة خلفية منشورة.

// Server-side Routes API field mask:
// routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline
// Minimal body shape, built by your backend:
{
  "origin": {"location": {"latLng": {"latitude": 30.0444, "longitude": 31.2357}}},
  "destination": {"location": {"latLng": {"latitude": 30.05, "longitude": 31.24}}},
  "travelMode": "DRIVE"
}

مثال الكود المراجع

الكود التالي يوضح نطاق الدرس ولا يغني عن إعداد المنصة أو الخدمات المذكورة أعلاه. اختُبر بتحليل Dart واختبارات المنطق المناسبة؛ تشغيل GPS والخرائط والخدمات الخارجية يحتاج جهازًا وإعداداتك الخاصة.

import 'package:google_maps_flutter/google_maps_flutter.dart';

List<LatLng> decodeRoute(String encoded) {
  if (encoded.length>1000000) throw const FormatException('Route too large');
  var index=0, lat=0, lng=0;
  int readDelta() {
    var result=0, shift=0;
    while (true) {
      if (index>=encoded.length || shift>30) throw const FormatException('Invalid polyline');
      final value=encoded.codeUnitAt(index++)-63;
      if (value<0 || value>63) throw const FormatException('Invalid polyline');
      result |= (value & 31) << shift;
      shift+=5;
      if (value<32) break;
    }
    return (result & 1)==1 ? ~(result >> 1) : result >> 1;
  }
  final points=<LatLng>[];
  while(index<encoded.length) {
    lat+=readDelta(); lng+=readDelta();
    if (lat.abs()>9000000 || lng.abs()>18000000) throw const FormatException('Invalid coordinates');
    points.add(LatLng(lat/1e5,lng/1e5));
  }
  return points;
}
class RouteData {
  const RouteData(this.points,this.distanceMeters,this.duration);
  final List<LatLng> points;
  final num distanceMeters;
  final String duration;
  factory RouteData.fromResponse(Map<String,dynamic> json) {
    final routes=json['routes'];
    if (routes is! List || routes.isEmpty || routes.first is! Map) {
      throw const FormatException('No route');
    }
    final first=routes.first as Map;
    final polyline=first['polyline'];
    if (polyline is! Map || polyline['encodedPolyline'] is! String ||
        first['distanceMeters'] is! num || first['duration'] is! String) {
      throw const FormatException('Incomplete route');
    }
    final points=decodeRoute(polyline['encodedPolyline']);
    if (points.length<2) throw const FormatException('Route has no path');
    return RouteData(points,first['distanceMeters'],first['duration']);
  }
}
Polyline routeLine(RouteData route) => Polyline(
  polylineId: const PolylineId('route'), points: route.points, width: 5,
);

مراجع التنفيذ الرسمية

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

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