الأدلّة

حزمة تطوير Flutter

ثبّت واستخدم حزمة navvo_maps_flutter الرسمية — عنصر خريطة NavvoMap القابل للتضمين إضافةً إلى عميل NavvoServices بلغة Dart للبحث والترميز الجغرافي والأماكن والتوجيه وحركة المرور والمزيد.

حزمة تطوير Flutter

توفّر حزمة navvo_maps_flutter الرسمية شيئين:

NavvoMap — عنصر خريطة أساس تفاعلي قابل للتضمين (الكاميرا، العلامات، تبديل النمط، طبقات GeoJSON)، موجّه إلى نقطة الدخول GET /tiles/style من Navvo.
NavvoServices — عميل بلغة Dart خالص وبلا واجهة خريطة لخدمة Navvo الويب (البحث، الترميز الجغرافي، الأماكن، التوجيه، حركة المرور، المصفوفة، الأيزوكرون، الطقس، المركبات الكهربائية، النقل…). ولأنه لا يعتمد على واجهة Flutter، فإنه يعمل أيضاً داخل الـ isolates والمهام الخلفية وتطبيقات Dart على الخادم.

كل شيء يحمل علامة Navvo ولا يتصل إلا بـ https://navvo.io/api/v1. الإحداثيات موحّدة بصيغة LatLng(lat, lng) عبر كامل الواجهة — وتتكفّل الحزمة داخلياً بالتحويل إلى ما تتوقّعه كل نقطة نهاية.

المتطلبات: Flutter ≥ 3.19 (Dart ≥ 3.3) · أندرويد 5.0+ (‏minSdk 21) · iOS 13+ · الرابط الأساسي: https://navvo.io/api/v1

التثبيت

flutter pub add navvo_maps_flutter

pubspec.yaml

dependencies:
  navvo_maps_flutter: ^0.1.0

التهيئة

عيّن مفتاح الـ API مرّة واحدة عند بدء التشغيل — تقرأه الخريطة والخدمات معاً:

import 'package:navvo_maps_flutter/navvo_maps_flutter.dart';

void main() {
  NavvoMaps.initialize(apiKey: 'nvvo_YOUR_KEY');
  runApp(const MyApp());
}

عرض خريطة

NavvoMap(
  initialCameraPosition: const CameraPosition(
    target: LatLng(31.9539, 35.9106), // عمّان
    zoom: 12,
  ),
  style: NavvoMapStyle.standard, // standard · light · dark · satellite · terrain · threeD
  markers: {
    NavvoMarker(markerId: const MarkerId('a'), position: const LatLng(31.9539, 35.9106)),
  },
  onMapCreated: (controller) => _controller = controller,
  onTap: (LatLng pos) => debugPrint('tapped $pos'),
);

يتحكّم NavvoMapController القادم من onMapCreated بالخريطة برمجياً:

await _controller.animateCamera(CameraUpdate.newLatLngZoom(const LatLng(31.95, 35.91), 15));
await _controller.setStyle(NavvoMapStyle.dark);

استخدام الخدمات (دون خريطة)

final svc = NavvoServices.instance; // يستخدم المفتاح من NavvoMaps.initialize

// البحث (لغة طبيعية + إكمال تلقائي)
final result = await svc.search('coffee in Abdoun', near: const LatLng(31.95, 35.91), limit: 8);
for (final p in result.places) {
  print('${p.name} @ ${p.location}');
}

// الترميز الجغرافي
final hits = await svc.geocode('Rainbow Street, Amman');

// المسارات — تُعيد رحلة التوجيه (الهندسة + المناورات + الملخّص)
final plan = await svc.plan(const RoutePlanRequest(
  locations: [
    PlanStop(LatLng(31.95, 35.91), name: 'Start'),
    PlanStop(LatLng(31.99, 35.95), name: 'End'),
  ],
  costing: RouteCosting.auto,
));
print('${plan.distanceKm} km · ${plan.durationMin} min');

هل تحتاج مفتاحاً مختلفاً أو عميلاً داخل isolate؟ أنشئ واحداً صراحةً:

final svc = NavvoServices(apiKey: 'nvvo_...', baseUrl: 'https://navvo.io/api/v1');

الأخطاء

يطرح كل استدعاء نوعاً فرعياً مُصنّفاً من NavvoException:

الاستثناء	HTTP	المعنى
`NavvoAuthError`	401	مفتاح مفقود / غير معروف
`NavvoScopeError`	403	مفتاح مُلغى، صلاحية ناقصة، أو تجاوز الحصّة
`NavvoNotFoundError`	404	المورد غير موجود
`NavvoValidationError`	400 / 422	طلب غير صالح
`NavvoRateLimitError`	429	الحصّة — يراعي `Retry-After`
`NavvoServerError`	5xx	خطأ في الخادم
`NavvoTimeoutError` / `NavvoNetworkError`	—	النقل

الدالة place() هي getter بقيمة فارغة لطيفة — تُعيد null (بدل رمي خطأ) عندما لا يوجد المعرّف:

final PlaceDetails? place = await svc.place('some-slug'); // null إن لم يُوجد

إعداد المنصّات

أندرويد — minSdkVersion 21؛ أضِف صلاحية INTERNET (وصلاحيات الموقع فقط إن فعّلت مؤشّر الموقع).
iOS — platform :ios, '13.0' في ملف Podfile؛ أضِف NSLocationWhenInUseUsageDescription فقط إن استخدمت مؤشّر الموقع.
الويب — متصفّح يدعم WebGL2.

يُعرض عنصر NavvoMap عبر محرّك خرائط مفتوح المصدر مضمّن داخلياً — أنت تتعامل فقط مع أصناف Navvo ونقاط نهاية Navvo. لعرض خريطة على الويب دون Flutter، استخدم حزمة Navvo Maps للويب (JS).

مكتبة Java (Java SDK)

ثبّت واستخدم مكتبة Java الرسمية ‎io.navvo:navvo-java‎ لخدمات الترميز الجغرافي والمسارات والأماكن وحركة المرور والمركبات الكهربائية والنقل العام والمزيد من جهة الخادم.

حزمة أندرويد

تثبيت واستخدام io.navvo:maps-android — عرض خرائط NavvoMapView لتطبيقات Kotlin مع عميل NavvoServices كامل للبحث والترميز الجغرافي والأماكن والتوجيه وحركة المرور والمزيد.