نظرة عامة على الترحيل

يسلط هذا الدليل الضوء على الاختلافات الرئيسية بين خدمة الأماكن القديمة وفئة المكان الجديدة. توفّر الترقية إلى فئة Place مزايا كبيرة، بما في ذلك الأداء المحسّن ونموذج التسعير الجديد. للاستفادة إلى أقصى حد من "الأماكن" وضمان تحديث تطبيقاتك، اطّلِع على التغييرات الموضّحة بالتفصيل في هذا الدليل.

تفعيل Places API

تعتمد فئة Place على خدمة Places API. لاستخدام ميزات فئة "المكان" الجديدة، عليك أولاً تفعيل Places API (الإصدار الجديد) في مشروعك على Google Cloud. لمزيد من المعلومات، يُرجى الاطّلاع على البدء.

التغييرات العامة

يسرد الجدول التالي بعض الاختلافات الرئيسية بين PlacesService وPlace:

PlacesService (قديمة) Place (ميزة جديدة)
تتطلّب الطرق استخدام دالة ردّ اتصال لمعالجة عنصر النتائج google.maps.places.PlacesServiceStatus الاستجابة. يستخدم وعدًا، ويعمل بشكل غير متزامن.
تتطلّب الطرق وضع علامة PlacesServiceStatus. لا يلزم التحقّق من الحالة، ويمكن استخدام معالجة الأخطاء العادية.
يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بترتيب أبجدي معكوس. يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بحرف القاف.
تقتصر على مجموعة ثابتة من أنواع الأماكن وحقول بيانات الأماكن. يوفّر هذا الإصدار مجموعة موسّعة من أنواع الأماكن وحقول بيانات الأماكن التي يتم تعديلها بانتظام.

التغييرات المتعلّقة بواجهة برمجة التطبيقات

توفّر فئة Place واجهة برمجة تطبيقات لاستخدام مكتبة Places، كما تتيح أنماط الاستخدام الحديثة، مثل Promises. تعرض فئة Place حقول بيانات الأماكن وأنواع الأماكن نفسها التي تعرضها خدمة Places Service القديمة، كما تتضمّن العديد من القيم الجديدة لأنواع الأماكن وحقول بياناتها.

يوضِّح هذا الجدول كيفية ربط ميزات خدمة "الأماكن" بميزات فئة "المكان":

خدمة "الأماكن" (الإصدار القديم) فئة المكان (جديد)
حقول بيانات الأماكن حقول بيانات فئة الأماكن
أنواع الأماكن أنواع الأماكن
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
صف Autocomplete صف PlaceAutocompleteElement
صف SearchBox ---

تحميل مكتبة "الأماكن"

تعتمد طريقة تحميل تطبيقك لـ "مكتبة الأماكن" على أداة تحميل التمهيد التي يتم استخدامها. إذا كان تطبيقك يستخدم استيراد المكتبات الديناميكية، يمكنك تحميل المكتبات المطلوبة أثناء التشغيل باستخدام عامل التشغيل await لمحاولة استدعاء importLibrary()، كما هو موضّح هنا:

const { Place } = await google.maps.importLibrary("places");

إذا كان تطبيقك يستخدم علامة تحميل النص البرمجي المباشر، اطلب مكتبة places في نص التحميل:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

مزيد من المعلومات عن تحميل واجهة برمجة التطبيقات JavaScript API في "خرائط Google"

يتضمّن هذا القسم الأدلة التالية لمساعدتك في نقل بيانات تطبيقاتك لاستخدام أحدث إصدار من Places API: