تتيح لك مكتبة JavaScript Fleet Tracking Library عرض مواقع المركبات في أساطيلك في الوقت الفعلي تقريبًا. تستخدم المكتبة واجهة برمجة التطبيقات للرحلات والتسليمات
عند الطلب للسماح بعرض المركبات والرحلات. تحتوي مكتبة تتبُّع مجموعة JavaScript على مكوّن خريطة JavaScript يمكن استخدامه كبديل عن كيان google.maps.Map
عادي ومكوّنات بيانات يمكن ربطها بـ Fleet Engine.
المكوّنات
توفر مكتبة JavaScript Fleet Tracking Library مكونات لعرض المركبات ونقاط طريق الرحلة، بالإضافة إلى خلاصات البيانات الأولية للوقت المقدر للوصول أو المسافة المتبقية قبل الرحلة.
عرض خريطة تتبُّع الأسطول
يعمل مكون عرض خريطة تتبع الأسطول على تصور موقع المركبات ونقاط طريق الرحلة. إذا كان مسار مركبة معروفًا، فسيحرّك مكوِّن عرض الخريطة تلك المركبة أثناء تحركها على مسارها المتوقع.
موفِّرو المواقع الجغرافية
يعمل مقدّمو المواقع الجغرافية مع المعلومات المخزّنة في Fleet Engine لإرسال معلومات الموقع الجغرافي الخاصة بالعناصر التي يتم تتبّعها إلى خريطة مشاركة الرحلة.
مقدّم خدمة الموقع الجغرافي للمركبة
يعرض مقدّم الموقع الجغرافي للمركبة معلومات عن الموقع الجغرافي لمركبة واحدة. وتحتوي على معلومات عن الموقع الجغرافي للمركبة والرحلة الحالية المخصّصة لها.
مزوِّد الموقع الجغرافي لمجموعة المركبات
يعرض مقدّم خدمة أسطول المركبات معلومات الموقع الجغرافي لمركبات متعددة. يمكنك الفلترة لعرض مركبة معيّنة وموقعها الجغرافي، أو يمكنك عرض المواقع الجغرافية للمركبات لكل مجموعة المركبات.
التحكم في مستوى رؤية المواقع التي يتم تتبعها
تحدِّد قواعد الرؤية متى يكون عنصر الموقع الجغرافي الذي تم تتبّعه مرئيًا على "خرائط Google" لموفّر الموقع الجغرافي في Fleet Engine. ملاحظة - قد يؤدي استخدام موفِّر موقع مخصص أو مشتق إلى تغيير قواعد الرؤية.
مركبات
تكون المركبة مرئية فور إنشائها في Fleet Engine، وتكون مرئية عندما تكون حالة السيارة هي Online
. هذا يعني أنه يمكن أن تكون المركبة مرئية حتى
في حالة عدم وجود رحلة حالية مخصصة للمركبة.
علامات الموقع الجغرافي لنقطة الطريق
تشير علامة موقع نقطة الطريق إلى النقاط على طول رحلة المركبة بدءًا من نقطة الانطلاق وتنتهي بالوجهة النهائية. ويمكن تعريف علامات موقع النقطة الطريق على النحو التالي:
- نقطة الانطلاق - تشير إلى موقع بدء رحلة المركبة
- متوسط - يشير إلى محطات التوقف لرحلة المركبة
- الوجهة - للإشارة إلى الموقع النهائي لرحلة المركبة
يتم عرض نقاط طريق المركبة المخطط لها على الخريطة كعلامات أصل ووسيط ووجهة.
بدء استخدام مكتبة JavaScript Fleet Tracking Library
قبل استخدام مكتبة JavaScript Fleet Tracking Library، تأكَّد من أنّك على دراية بخدمة Fleet Engine ومن خلال الحصول على مفتاح واجهة برمجة تطبيقات. بعد ذلك، أنشِئ مطالبة بمعرّف الرحلة ومعرّف المركبة.
إنشاء مطالبة بمعرّف الرحلة ومعرّف المركبة
لتتبُّع المركبات من خلال موفِّر الموقع الجغرافي للمركبة، يمكنك إنشاء رمز JSON المميّز للويب (JWT) مع المطالبة بمعرّف الرحلة ومعرّف المركبة.
لإنشاء حمولة JWT، أضِف مطالبة إضافية في قسم التفويض باستخدام المفتاحَين tripid
وvehicleid
واضبط السمة value
لكل مفتاح على *.
يجب إنشاء الرمز المميّز باستخدام دور المستخدم المميّز لخدمة Fleet Engine في Cloud
IAM. يُرجى العِلم أنّ هذا الإجراء يتيح إمكانية الوصول الواسع النطاق لإنشاء كيانات Fleet Engine وقراءتها وتعديلها، ويجب مشاركته مع المستخدمين الموثوق بهم فقط.
يوضح المثال التالي كيفية إنشاء رمز مميز للتتبع حسب المركبة والمهمة:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
"sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"scope": "https://www.googleapis.com/auth/xapi",
"authorization": {
"tripid": "*",
"vehicleid": "*",
}
}
إنشاء برنامج لاسترجاع الرمز المميّز للمصادقة
تطلب مكتبة JavaScript Fleet Tracking Library رمزًا مميزًا يستخدم أداة جلب الرمز المميز للمصادقة عندما يكون أي مما يلي صحيحًا:
- وهو لا يملك رمزًا مميزًا صالحًا، كأن يتم استدعاءه عند تحميل صفحة جديدة أو عدم عرض برنامج الجلب مع رمز مميز.
- انتهت صلاحية الرمز المميّز الذي تم جلبه في السابق.
- إنّ الرمز المميّز الذي حصل عليه سابقًا هو في غضون دقيقة واحدة من انتهاء صلاحيته.
بخلاف ذلك، تستخدم المكتبة الرمز المميز الذي تم إصداره سابقًا ولكنه لا يزال صالحًا ولا تستدعي برنامج الجلب.
يمكنك إنشاء أداة استرجاع الرموز المميّزة للمصادقة لاسترداد الرمز المميّز الذي تم إنشاؤه باستخدام المطالبات المناسبة على خوادمك باستخدام شهادة حساب خدمة لمشروعك. من المهم إنشاء رموز مميزة على الخوادم فقط وعدم مشاركة شهاداتك على أي عملاء. وإلا فقد تتعرض أمان نظامك للخطر.
يجب أن يعرض برنامج الجلب بنية بيانات مع حقلين، ملفين في وعد:
- سلسلة
token
. - رقم
expiresInSeconds
وتنتهي صلاحية الرمز المميز في هذه المدة الزمنية بعد جلبه.
يوضّح المثال التالي كيفية إنشاء برنامج لاسترجاع الرموز المميّزة للمصادقة:
JavaScript
function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
TypeScript
function authTokenFetcher(options: {
serviceType: google.maps.journeySharing.FleetEngineServiceType,
context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
// The developer should generate the correct
// SERVER_TOKEN_URL based on options.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.token,
expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
};
}
عند تنفيذ نقطة النهاية من جانب الخادم لاستخراج الرموز المميزة، ضع ما يلي في الاعتبار:
- يجب أن تعرض نقطة النهاية وقت انتهاء صلاحية الرمز المميّز، في المثال أعلاه، يتم تحديدها على النحو التالي:
data.ExpiresInSeconds
. - يجب أن يمرر استرجاع الرمز المميز للمصادقة وقت انتهاء الصلاحية (بالثواني، من وقت الجلب) إلى المكتبة، كما هو موضح في المثال.
- يعتمد SERVER_TOKEN_URL على عملية تنفيذ الواجهة الخلفية، وفي ما يلي أمثلة على عناوين URL:
- https://
SERVER_URL
/token/driver/VEHICLE_ID
- https://
SERVER_URL
/token/consumer/TRIP_ID
- https://
SERVER_URL
/token/fleet_reader
- https://
تحميل خريطة من HTML
يوضّح المثال التالي كيفية تحميل مكتبة "مشاركة رحلة JavaScript" من عنوان URL محدّد. تنفِّذ المعلمة callback الدالة initMap
بعد تحميل واجهة برمجة التطبيقات. تتيح السمة defer للمتصفّح مواصلة
عرض بقية محتوى صفحتك أثناء تحميل واجهة برمجة التطبيقات.
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing&v=beta" defer></script>
متابعة مركبة
يوضح هذا القسم كيفية استخدام مكتبة JavaScript Fleet Tracking Library لمتابعة مركبة. تأكّد من تحميل المكتبة من دالة الاستدعاء المحدّدة في علامة النص البرمجي قبل تشغيل الرمز.
إنشاء نسخة من موفّر الموقع الجغرافي للمركبة
تحدّد مكتبة JavaScript Fleet Tracking Library مسبقًا موفّر الموقع الجغرافي لواجهة برمجة التطبيقات عند الطلب "الجولات والتسليمات". استخدم معرف مشروعك ومرجعًا لمصنع الرمز المميز لإنشاء مثيل له.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineVehicleLocationProvider({
projectId,
authTokenFetcher,
// Optionally, you may specify
// vehicleId to immediately start
// tracking.
vehicleId: 'your-vehicle-id',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineVehicleLocationProvider({
projectId,
authTokenFetcher,
// Optionally, you may specify
// vehicleId to immediately start
// tracking.
vehicleId: 'your-vehicle-id',
});
إعداد عرض الخريطة
بعد تحميل مكتبة "مشاركة رحلة JavaScript"، يمكنك إعداد عرض الخريطة وإضافته إلى صفحة HTML. يجب أن تحتوي صفحتك على عنصر <div> يحمل عرض الخريطة. تتم تسمية عنصر <div> باسم map_canvas في المثال أدناه.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
= 'your-vehicle-id';
// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId = 'your-vehicle-id';
// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);
الاستماع إلى تغييرات الأحداث
يمكنك استرداد معلومات وصفية عن مركبة من عنصر vehicle
باستخدام موفِّر الموقع الجغرافي. وتشمل معلومات التعريف الوقت المقدر للوصول والمسافة المتبقية قبل موعد الانطلاق أو النزول للمركبة في المرة التالية. تؤدي التغييرات على المعلومات الوصفية إلى تشغيل حدث update. يوضح المثال التالي كيفية الاستماع
إلى أحداث التغيير هذه.
JavaScript
locationProvider.addListener('update', e => {
// e.vehicle contains data that may be
// useful to the rest of the UI.
if (e.vehicle) {
console.log(e.vehicle.vehicleState);
}
});
TypeScript
locationProvider.addListener('update',
(e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
// e.vehicle contains data that may be useful to the rest of the UI.
if (e.vehicle) {
console.log(e.vehicle.vehicleState);
}
});
الاستماع إلى الأخطاء
تؤدي الأخطاء التي تنشأ بشكل غير متزامن من طلب معلومات المركبة إلى تشغيل أحداث الخطأ. يوضح المثال التالي كيفية الاستماع إلى هذه الأحداث للتعامل مع الأخطاء.
JavaScript
locationProvider.addListener('error', e => {
// e.error is the error that triggered the event.
console.error(e.error);
});
TypeScript
locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
// e.error is the error that triggered the event.
console.error(e.error);
});
إيقاف التتبُّع
لمنع موفِّر الموقع الجغرافي من تتبُّع المركبة، عليك إزالة رقم تعريف المركبة من موفِّر الموقع الجغرافي.
JavaScript
locationProvider.vehicleId = '';
TypeScript
locationProvider.vehicleId = '';
إزالة موفر الموقع من عرض الخريطة
يوضح المثال التالي كيفية إزالة مزوّد موقع جغرافي من عرض الخريطة.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
عرض مجموعة مركبات
يعرض هذا القسم كيفية استخدام مكتبة JavaScript Journey "مشاركة رحلة" مع JavaScript لعرض مجموعة المركبات. تأكّد من تحميل المكتبة من دالة رد الاتصال المحددة في علامة النص البرمجي قبل تشغيل الرمز.
إنشاء مثيل لموقع أسطول المركبات
تحدد مكتبة JavaScript Fleet Tracking Library مسبقًا موفّر موقع جغرافي يجلب مركبات متعددة من واجهة برمجة التطبيقات On Demand Rides and Deliveries API. استخدِم معرّف المشروع بالإضافة إلى مرجع إلى أداة جلب الرموز المميّزة لإنشاء مثيل لها.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineFleetLocationProvider({
projectId,
authTokenFetcher,
// Optionally, specify location bounds to
// limit which vehicles are
// retrieved and immediately start tracking.
locationRestriction: {
north: 37.3,
east: -121.8,
south: 37.1,
west: -122,
},
// Optionally, specify a filter to limit
// which vehicles are retrieved.
vehicleFilter:
'attributes.foo = "bar" AND attributes.baz = "qux"',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineFleetLocationProvider({
projectId,
authTokenFetcher,
// Optionally, specify location bounds to
// limit which vehicles are
// retrieved and immediately start tracking.
locationRestriction: {
north: 37.3,
east: -121.8,
south: 37.1,
west: -122,
},
// Optionally, specify a filter to limit
// which vehicles are retrieved.
vehicleFilter:
'attributes.foo = "bar" AND attributes.baz = "qux"',
});
تحدّد السمة vehicleFilter
طلب بحث يتم استخدامه لفلترة المركبات المعروضة على الخريطة.
يتم تمرير هذا الفلتر مباشرةً إلى Fleet Engine. راجِع ListVehiclesRequest للاطّلاع على التنسيقات المتوافقة.
تحدّد ميزة locationRestriction
المنطقة التي يمكن فيها عرض المركبات على الخريطة.
وتتحكّم أيضًا في ما إذا كان تتبُّع الموقع الجغرافي نشطًا أم لا. لن تبدأ عملية تتبّع الموقع الجغرافي
حتى يتم ضبط هذا الإعداد
بعد إنشاء موفِّر الموقع الجغرافي، عليك إعداد عرض الخريطة.
ضبط تقييد الموقع الجغرافي باستخدام إطار عرض الخريطة
يمكن ضبط حدود locationRestriction
لمطابقة المنطقة المرئية في عرض الخريطة.
JavaScript
google.maps.event.addListenerOnce(
mapView.map, 'bounds_changed', () => {
const bounds = mapView.map.getBounds();
if (bounds) {
// If you did not specify a location restriction in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.locationRestriction = bounds;
}
});
TypeScript
google.maps.event.addListenerOnce(
mapView.map, 'bounds_changed', () => {
const bounds = mapView.map.getBounds();
if (bounds) {
// If you did not specify a location restriction in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.locationRestriction = bounds;
}
});
الاستماع إلى تغييرات الأحداث
يمكنك استرداد معلومات وصفية عن مجموعة الأجهزة من الكائن vehicles
باستخدام موفِّر الموقع الجغرافي. وتشمل المعلومات الوصفية خصائص المركبة، مثل حالة التنقل والمسافة إلى نقطة الطريق التالية والسمات المخصّصة. يمكنك الاطّلاع على المستندات المرجعية لمزيد من التفاصيل. يؤدي تغيير المعلومات الوصفية إلى تشغيل حدث تحديث. يوضح المثال التالي كيفية الاستماع إلى أحداث التغيير هذه.
JavaScript
locationProvider.addListener('update', e => {
// e.vehicles contains data that may be
// useful to the rest of the UI.
if (e.vehicles) {
for (vehicle of e.vehicles) {
console.log(vehicle.navigationStatus);
}
}
});
TypeScript
locationProvider.addListener('update',
(e: google.maps.journeySharing.FleetEngineFleetLocationProviderUpdateEvent) => {
// e.vehicles contains data that may be useful to the rest of the UI.
if (e.vehicles) {
for (vehicle of e.vehicles) {
console.log(vehicle.navigationStatus);
}
}
});
الاستماع إلى الأخطاء
تؤدي الأخطاء التي تنشأ بشكل غير متزامن من طلب معلومات مجموعة المركبات إلى ظهور أحداث الخطأ. للحصول على أمثلة توضح كيفية الاستماع إلى هذه الأحداث، راجِع مقالة الاستماع إلى الأخطاء.
إيقاف التتبُّع
لمنع مقدم خدمة الموقع من تتبع الأسطول، اضبط حدود موفّر الموقع على "خالٍ".
JavaScript
locationProvider.locationRestriction = null;
TypeScript
locationProvider.locationRestriction = null;
إزالة موفر الموقع من عرض الخريطة
يوضح المثال التالي كيفية إزالة مزوّد موقع جغرافي من عرض الخريطة.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
تخصيص شكل ومظهر الخريطة الأساسية
لتخصيص شكل ومظهر مكوِّن الخرائط، يمكنك تصميم خريطتك باستخدام أدوات مستنِدة إلى السحابة الإلكترونية أو من خلال ضبط الخيارات مباشرةً في الرمز.
استخدام تصميم الخرائط المستند إلى السحابة الإلكترونية
يتيح لك تصميم الخرائط المستند إلى السحابة الإلكترونية
إنشاء أنماط خرائط وتعديلها لأي من تطبيقاتك التي تستخدم "خرائط Google"
من وحدة التحكّم في Google Cloud بدون الحاجة إلى إجراء أي تغييرات على الرمز. يتم حفظ
أنماط الخريطة كمعرّفات خرائط في مشروعك على Google Cloud. لتطبيق نمط على
خريطة تتبُّع عدد العناصر في JavaScript، حدِّد
mapId
عند إنشاء JourneySharingMapView
. ولا يمكن تغيير الحقل mapId
أو إضافته بعد إنشاء مثيل لـ JourneySharingMapView
. يوضح المثال التالي كيفية تمكين نمط خريطة تم إنشاؤه مسبقًا بمعرف خريطة.
JavaScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
mapId: 'YOUR_MAP_ID'
}
});
TypeScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
mapId: 'YOUR_MAP_ID'
}
});
استخدام تصميم الخرائط المستند إلى رموز برمجية
هناك طريقة أخرى لتخصيص تصميم الخريطة، وهي ضبط
mapOptions
عند إنشاء JourneySharingMapView
.
JavaScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
styles: [
{
"featureType": "road.arterial",
"elementType": "geometry",
"stylers": [
{ "color": "#CCFFFF" }
]
}
]
}
});
TypeScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
styles: [
{
"featureType": "road.arterial",
"elementType": "geometry",
"stylers": [
{ "color": "#CCFFFF" }
]
}
]
}
});
استخدام عمليات تخصيص العلامات
باستخدام مكتبة JavaScript Fleet Tracking Library، يمكنك تخصيص شكل ومظهر العلامات التي تمت إضافتها إلى الخريطة. يمكنك القيام بذلك عن طريق تحديد تخصيصات العلامات، التي تطبقها مكتبة Fleet Tracking Library قبل إضافة علامات إلى الخريطة ومع كل تحديث للعلامة.
يمكنك إنشاء عملية تخصيص بسيطة من خلال تحديد كائن
MarkerOptions
لتطبيقه على كل العلامات من النوع نفسه. يتم تطبيق التغييرات المحددة في الكائن بعد إنشاء كل علامة، مما يؤدي إلى استبدال أي خيارات افتراضية.
كخيار أكثر تقدمًا، يمكنك تحديد وظيفة تخصيص. تتيح وظائف التخصيص نمط العلامات استنادًا إلى البيانات، بالإضافة إلى إضافة التفاعل إلى العلامات، مثل معالجة النقر. وعلى وجه التحديد، يعمل تتبع الأسطول على تمرير البيانات إلى وظيفة التخصيص المتعلقة بنوع الكائن الذي تمثله العلامة: مركبة، أو توقف، أو مهمة. يسمح هذا بعد ذلك بتغيير نمط العلامة بناءً على الحالة الحالية لعنصر العلامة نفسه، على سبيل المثال، عدد المحطات المتبقية أو نوع المهمة. يمكنك حتى الانضمام إلى البيانات من مصادر خارج Fleet Engine وتصميم العلامة بناءً على تلك المعلومات.
بالإضافة إلى ذلك، يمكنك استخدام وظائف التخصيص لفلترة إذن الوصول إلى العلامات.
لإجراء ذلك، عليك استدعاء
setVisible(false)
في محدّد الموقع.
ومع ذلك، لأسباب تتعلق بالأداء، ننصحك بالفلترة باستخدام الفلتر
المدمج في موفّر الموقع الجغرافي، مثل
FleetEngineFleetLocationProvider.vehicleFilter
.
ومع ذلك، عندما تحتاج إلى وظيفة فلترة إضافية، يمكنك تطبيق الفلترة باستخدام دالة التخصيص.
توفِّر مكتبة "تتبُّع الأسطول" مَعلمات التخصيص التالية:
تغيير نمط العلامات باستخدام MarkerOptions
يوضّح المثال التالي كيفية ضبط تصميم علامة المركبة باستخدام عنصر MarkerOptions
. اتبع هذا النمط لتخصيص نمط أي علامة باستخدام أي من معلمات تخصيص العلامة المذكورة أعلاه.
JavaScript
vehicleMarkerCustomization = {
cursor: 'grab'
};
TypeScript
vehicleMarkerCustomization = {
cursor: 'grab'
};
تغيير تصميم العلامات باستخدام وظائف التخصيص
يوضّح المثال التالي كيفية ضبط تصميم علامة المركبة. اتبع هذا النمط لتخصيص نمط أي علامة باستخدام أي من معلمات تخصيص العلامة المذكورة أعلاه.
JavaScript
vehicleMarkerCustomization =
(params) => {
var remainingWaypoints = params.vehicle.waypoints.length;
params.marker.setLabel(`${remainingWaypoints}`);
};
TypeScript
vehicleMarkerCustomization =
(params: VehicleMarkerCustomizationFunctionParams) => {
var remainingWaypoints = params.vehicle.waypoints.length;
params.marker.setLabel(`${remainingWaypoints}`);
};
إضافة معالجة النقر إلى العلامات
يوضّح المثال التالي كيفية إضافة طريقة التعامل مع النقرات إلى علامة المركبة. اتبع هذا النمط لإضافة معالجة النقر إلى أي علامة باستخدام أي من معلمات تخصيص العلامة المذكورة أعلاه.
JavaScript
vehicleMarkerCustomization =
(params) => {
if (params.isNew) {
params.marker.addListener('click', () => {
// Perform desired action.
});
}
};
TypeScript
vehicleMarkerCustomization =
(params: VehicleMarkerCustomizationFunctionParams) => {
if (params.isNew) {
params.marker.addListener('click', () => {
// Perform desired action.
});
}
};
فلترة العلامات المرئية
يوضّح المثال التالي كيفية فلترة علامات المركبات الظاهرة. اتبع هذا النمط لتصفية أي علامات باستخدام أي من معلمات تخصيص العلامة المذكورة أعلاه.
JavaScript
vehicleMarkerCustomization =
(params) => {
var remainingWaypoints = params.vehicle.remainingWaypoints.length;
if (remainingWaypoints > 10) {
params.marker.setVisible(false);
}
};
TypeScript
vehicleMarkerCustomization =
(params: VehicleMarkerCustomizationFunctionParams) => {
var remainingWaypoints = params.vehicle.remainingWaypoints.length;
if (remainingWaypoints > 10) {
params.marker.setVisible(false);
}
};
استخدام تخصيص الخطوط المتعددة عند متابعة مركبة
باستخدام مكتبة تتبع الأسطول، يمكنك أيضًا تخصيص شكل ومظهر
مسار المركبة الذي تتبعه على الخريطة. وتُنشئ المكتبة كائن google.maps.Polyline
لكل زوج من الإحداثيات في المسار النشط أو المتبقي للمركبة.
يمكنك تصميم عناصر Polyline
من خلال تحديد تخصيصات الخطوط المتعددة. تطبّق المكتبة هذه التخصيصات في حالتَين: قبل إضافة العناصر إلى الخريطة وعندما تتغيّر البيانات المستخدَمة للكائنات.
كما هو الحال في تخصيص العلامة، يمكنك تحديد مجموعة من
PolylineOptions
لتطبيقها على كل كائنات Polyline
المطابِقة عند
إنشائها أو تعديلها.
وبالمثل، يمكنك تحديد دالة تخصيص. تسمح وظائف التخصيص
بالتصميم الفردي للكائنات بناءً على البيانات المرسلة بواسطة Fleet Engine.
ويمكن أن تغيّر هذه الوظيفة تصميم كل عنصر استنادًا إلى الحالة الحالية للمركبة، مثل تلوين عنصر Polyline
بلون أغمق أو جعله أكثر سمكًا عندما تتحرك السيارة بشكل أبطأ. يمكنك أيضًا الانضمام إلى ضد مصادر خارج Fleet Engine وتصميم العنصر Polyline
بناءً على تلك المعلومات.
يمكنك تحديد عمليات التخصيص باستخدام المَعلمات الواردة في
FleetEngineVehicleLocationProviderOptions
.
ويمكنك ضبط عمليات تخصيص لحالات المسارات المختلفة في رحلة المركبة، سواء سبق أن سافرت أو لم تسافر بعد. وتكون المَعلمات على النحو التالي:
takenPolylineCustomization
، لمسار سبق أن تم نقلهactivePolylineCustomization
، لمسارات السفر النشطة؛remainingPolylineCustomization
، لمسار لم يتم الانتقال إليه بعد.
تغيير نمط عناصر Polyline
باستخدام PolylineOptions
يوضح المثال التالي كيفية ضبط نمط عنصر Polyline
باستخدام
PolylineOptions
.
اتّبِع هذا النمط لتخصيص تصميم أي عنصر Polyline
باستخدام أي من تخصيصات الخطوط المتعددة التي سبق أن تم إدراجها.
JavaScript
activePolylineCustomization = {
strokeWidth: 5,
strokeColor: 'black',
};
TypeScript
activePolylineCustomization = {
strokeWidth: 5,
strokeColor: 'black',
};
تغيير نمط عناصر Polyline
باستخدام وظائف التخصيص
يوضّح المثال التالي كيفية ضبط نمط عنصر Polyline
نشط. اتّبِع هذا النمط لتخصيص نمط أي عنصر Polyline
باستخدام أي من معلمات تخصيص الخطوط المتعددة المذكورة سابقًا.
JavaScript
// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
(params) => {
const distance = params.vehicle.waypoints[0].distanceMeters;
if (distance < 1000) {
// params.polylines contains an ordered list of Polyline objects for
// the path.
for (const polylineObject of params.polylines) {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
TypeScript
// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
(params: VehiclePolylineCustomizationFunctionParams) => {
const distance = params.vehicle.waypoints[0].distanceMeters;
if (distance < 1000) {
// params.polylines contains an ordered list of Polyline objects for
// the path.
for (const polylineObject of params.polylines) {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
التحكّم في مستوى رؤية عناصر Polyline
تكون جميع عناصر Polyline
مرئية تلقائيًا. لجعل كائن Polyline
غير مرئي، اضبط خاصية visible
الخاصة به:
JavaScript
remainingPolylineCustomization = {visible: false};
TypeScript
remainingPolylineCustomization = {visible: false};
عرض عناصر "Polyline
" المتوافقة مع حركة المرور
يعرض Fleet Engine بيانات سرعة حركة المرور للمسارات النشطة والباقية للمركبة التي تتم متابعتها. يمكنك استخدام هذه المعلومات لتحديد نمط كائنات Polyline
حسب سرعات حركة المرور الخاصة بها:
JavaScript
// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
FleetEngineVehicleLocationProvider.
TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;
// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
(params) => {
FleetEngineVehicleLocationProvider.
TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
for (const polylineObject of params.polylines) {
if (polylineObject.get('strokeColor') === '#05f') {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
TypeScript
// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
FleetEngineVehicleLocationProvider.
TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;
// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
(params: VehiclePolylineCustomizationFunctionParams) => {
FleetEngineVehicleLocationProvider.
TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
for (const polylineObject of params.polylines) {
if (polylineObject.get('strokeColor') === '#05f') {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
عرض InfoWindow
لمركبة أو علامة موقع جغرافي
يمكنك استخدام
InfoWindow
لعرض معلومات إضافية عن مركبة أو علامة موقع جغرافي.
يوضح المثال التالي كيفية إنشاء InfoWindow
وإرفاقها بعلامة
المركبة.
JavaScript
// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
{disableAutoPan: true});
// (Assumes a vehicle location provider.)
locationProvider.addListener('update', e => {
if (e.vehicle) {
const distance =
e.vehicle.remainingDistanceMeters;
infoWindow.setContent(
`Your vehicle is ${distance}m away from the next drop-off point.`);
// 2. Attach the info window to a vehicle marker.
// This property can return multiple markers.
const marker = mapView.vehicleMarkers[0];
infoWindow.open(mapView.map, marker);
}
});
// 3. Close the info window.
infoWindow.close();
TypeScript
// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
{disableAutoPan: true});
// (Assumes a vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
if (e.vehicle) {
const distance =
e.vehicle.remainingDistanceMeters;
infoWindow.setContent(
`Your vehicle is ${distance}m away from the next drop-off.`);
// 2. Attach the info window to a vehicle marker.
// This property can return multiple markers.
const marker = mapView.vehicleMarkers[0];
infoWindow.open(mapView.map, marker);
}
});
// 3. Close the info window.
infoWindow.close();
إيقاف الاحتواء التلقائي
يمكنك منع احتواء الخريطة تلقائيًا على إطار العرض في المركبة والمسار المتوقع من خلال تعطيل التوافق التلقائي. يوضح المثال التالي كيفية إيقاف الملاءمة التلقائية عند ضبط عرض الخريطة لمشاركة الرحلة.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
automaticViewportMode:
google.maps.journeySharing
.AutomaticViewportMode.NONE,
...
});
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
automaticViewportMode:
google.maps.journeySharing
.AutomaticViewportMode.NONE,
...
});
استبدال خريطة حالية
يمكنك استبدال خريطة حالية تحتوي على محددات أو تخصيصات أخرى دون فقدان تلك التخصيصات.
على سبيل المثال، لنفترض أنّ لديك صفحة ويب تتضمّن كيان google.maps.Map
عاديًا تظهر عليه علامة:
<!DOCTYPE html>
<html>
<head>
<style>
/* Set the size of the div element that contains the map */
#map {
height: 400px; /* The height is 400 pixels */
width: 100%; /* The width is the width of the web page */
}
</style>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<script>
// Initialize and add the map
function initMap() {
// The location of Oracle Park Stadium
var oraclePark = { lat: 37.780087547237365, lng: -122.38948437884427 };,
// The map, initially centered at Mountain View, CA.
var map = new google.maps.Map(document.getElementById("map"));
map.setOptions({ center: { lat: 37.424069, lng: -122.0916944 }, zoom: 14 });
// The marker, now positioned at Oracle Park
var marker = new google.maps.Marker({ position: oraclePark, map: map });
}
</script>
<!-- Load the API from the specified URL.
* The async attribute allows the browser to render the page while the API loads.
* The key parameter will contain your own API key (which is not needed for this tutorial).
* The callback parameter executes the initMap() function.
-->
<script
defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
></script>
</body>
</html>
لإضافة مكتبة JavaScript Journey Share، والتي تتضمّن ميزة "تتبُّع الأسطول":
- أضف رمزًا لمصنع الرموز المميزة للمصادقة.
- إعداد موفّر موقع جغرافي في الدالة
initMap()
. - إعداد عرض الخريطة في الدالة
initMap()
. تحتوي طريقة العرض على الخريطة. - انقل التخصيص إلى دالة الاستدعاء لإعداد عرض الخريطة.
- أضِف مكتبة المواقع الجغرافية إلى أداة تحميل واجهة برمجة التطبيقات.
يوضح المثال التالي التغييرات التي سيتم إجراؤها:
<!DOCTYPE html>
<html>
<head>
<style>
/* Set the size of the div element that contains the map */
#map {
height: 400px; /* The height is 400 pixels */
width: 100%; /* The width is the width of the web page */
}
</style>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<script>
let locationProvider;
// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
// Initialize and add the map
function initMap() {
// (2) Initialize location provider. Use FleetEngineVehicleLocationProvider
// as appropriate.
locationProvider = new google.maps.journeySharing.FleetEngineVehicleLocationProvider({
YOUR_PROVIDER_ID,
authTokenFetcher,
});
// (3) Initialize map view (which contains the map).
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map'),
locationProviders: [locationProvider],
// any styling options
});
mapView.addListener('ready', () => {
locationProvider.vehicleId = VEHICLE_ID;
// (4) Add customizations like before.
// The location of Oracle Park
var oraclePark = {lat: 37.77995187146094, lng: -122.38957020952795};
// The map, initially centered at Mountain View, CA.
var map = mapView.map;
map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
// The marker, now positioned at Oracle Park
var marker = new google.maps.Marker({position: oraclePark, map: map});
};
}
</script>
<!-- Load the API from the specified URL
* The async attribute allows the browser to render the page while the API loads
* The key parameter will contain your own API key (which is not needed for this tutorial)
* The callback parameter executes the initMap() function
*
* (5) Add the journey sharing library to the API loader, which includes Fleet Tracking functionality.
-->
<script
defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing&v=beta"
></script>
</body>
</html>
إذا كنت تقود مركبة تحمل المعرّف المحدّد بالقرب من Oracle Park، سيتم عرضها على الخريطة.