Autocomplete Data

فئة AutocompleteSuggestion

class google.maps.places.AutocompleteSuggestion
library "places"

نتيجة اقتراح للإكمال التلقائي

const {AutocompleteSuggestion} = await google.maps.importLibrary("places");
fetchAutocompleteSuggestions
fetchAutocompleteSuggestions(autocompleteRequest)
المَعلمات:
القيمة المعروضة: Promise<{suggestions:Array<AutocompleteSuggestion>}>
لجلب قائمة بـ AutocompleteSuggestions

إذا تم توفير AutocompleteRequest.sessionToken في الطلب، سيتم تضمين الرمز المميز للجلسة تلقائيًا عند طلب Place.fetchFields لأول مرة، في كل Place يتم عرضه من خلال PlacePrediction.toPlace في PlacePredictions الناتجة.
placePrediction
readonly
النوع: PlacePrediction optional
تحتوي على الاسم الذي يمكن لشخص عادي قراءته للنتيجة المعروضة. بالنسبة إلى نتائج المؤسسات، يكون هذا عادةً اسم النشاط التجاري وعنوانه.

إذا تم تقديم AutocompleteRequest.sessionToken في AutocompleteRequest المستخدَم لجلب AutocompleteSuggestion هذا، سيتم تلقائيًا تضمين الرمز المميّز نفسه عند طلب Place.fetchFields لأول مرة على Place الذي تم عرضه من خلال طلب إلى PlacePrediction.toPlace.

واجهة AutocompleteRequest

واجهة google.maps.places.AutocompleteRequest

واجهة الطلب لـ "AutocompleteSuggestion.fetchAutocompleteSuggestions"
input
النوع: string
سلسلة النص المطلوب البحث عنها
futureOpeningBusinessesIncluded
اختياري
النوع: boolean optional
تضمين توقعات الأماكن للمؤسسات التي لم يتم افتتاحها بعد ولكن من المتوقع افتتاحها في المستقبل
includedPrimaryTypes
اختياري
النوع: Array<string> optional
نوع المكان الأساسي المضمّن (على سبيل المثال، "restaurant" أو "gas_station").

لا يتم عرض مكان إلا إذا كان نوعه الأساسي مضمّنًا في هذه القائمة. يمكن تحديد ما يصل إلى 5 قيم. في حال عدم تحديد أي أنواع، يتم عرض جميع أنواع الأماكن.
includedRegionCodes
اختياري
النوع: Array<string> optional
تضمين النتائج في المناطق المحدّدة فقط، والتي يتم تحديدها بما يصل إلى 15 رمز منطقة مكوّن من حرفين وفقًا لمعيار CLDR. لن تؤدي المجموعة الفارغة إلى تقييد النتائج. إذا تم ضبط كل من locationRestriction وincludedRegionCodes، ستكون النتائج في منطقة التقاطع.
inputOffset
اختياري
النوع: number optional
يشير هذا المصطلح إلى إزاحة حرف Unicode المستندة إلى الصفر في input، والتي توضّح موضع المؤشر في input. قد يؤثر موضع المؤشر في التوقعات التي يتم عرضها. في حال عدم تحديدها، يتم ضبط القيمة التلقائية على طول input.
internalUsageAttributionIds
اختياري
النوع: Iterable<string> optional
المعرّفات المستخدَمة لتحديد مصدر الطلبات من حِزم معيّنة أو مكتبات برامج مفتوحة المصدر
language
اختياري
النوع: string optional
اللغة التي سيتم عرض النتائج بها سيتم ضبط اللغة تلقائيًا على اللغة المفضّلة في المتصفّح. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في input مختلفة عن language، أو إذا لم يتوفّر في "المكان" الذي تم عرضه ترجمة من اللغة المحلية إلى language.
locationBias
اختياري
النوع: LocationBias optional
توجيه النتائج إلى موقع جغرافي محدّد

يجب ضبط سمة واحدة على الأكثر من locationBias أو locationRestriction. في حال عدم ضبط أيّ منهما، ستتأثر النتائج بعنوان IP، ما يعني أنّه سيتم ربط عنوان IP بموقع جغرافي غير دقيق واستخدامه كإشارة تحيّز.
locationRestriction
اختياري
النوع: LocationRestriction optional
لحصر النتائج بموقع جغرافي محدّد

يجب ضبط سمة واحدة على الأكثر من locationBias أو locationRestriction. في حال عدم ضبط أيّ منهما، ستتأثر النتائج بعنوان IP، ما يعني أنّه سيتم ربط عنوان IP بموقع جغرافي غير دقيق واستخدامه كإشارة تحيّز.
origin
اختياري
النوع: LatLng|LatLngLiteral optional
نقطة المصدر التي يتم احتساب المسافة الجيوديسية منها إلى الوجهة (يتم عرضها على شكل PlacePrediction.distanceMeters). في حال حذف هذه القيمة، لن يتم عرض المسافة الجيوديسية.
pureServiceAreaBusinessesIncluded
اختياري
النوع: boolean optional
يتم تضمين المؤسسات التي تقدّم خدماتها ضمن منطقة الخدمة فقط إذا تم ضبط الحقل على "صحيح". المؤسسة ضمن منطقة الخدمة فقط هي مؤسسة تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تقدّم خدماتها لهم في عنوانها. على سبيل المثال، قد لا يكون للأنشطة التجارية، مثل خدمات التنظيف أو السباكة، عنوان أو موقع جغرافي على "خرائط Google".
region
اختياري
النوع: string optional
رمز المنطقة، المحدّد كرمز منطقة CLDR مكوّن من حرفين. يؤثر ذلك في تنسيق العناوين وترتيب النتائج، وقد يؤثر في النتائج التي يتم عرضها. لا يؤدي ذلك إلى حصر النتائج بالمنطقة المحدّدة.
sessionToken
اختياري
النوع: AutocompleteSessionToken optional
رمز مميّز يحدّد جلسة "إكمال تلقائي" لأغراض الفوترة. أنشِئ رمزًا مميزًا جديدًا للجلسة من خلال AutocompleteSessionToken.

تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا ويطلب Place.fetchFields. يمكن أن تتضمّن كل جلسة طلبات بحث متعددة، تليها مكالمة واحدة من خلال fetchFields. يجب أن تكون بيانات الاعتماد المستخدَمة لكل طلب ضمن جلسة معيّنة تابعة لمشروع Google Cloud Console نفسه. بعد انتهاء الجلسة، لن يعود الرمز المميّز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. في حال حذف المَعلمة sessionToken أو إعادة استخدام رمز مميّز للجلسة، يتم تحصيل رسوم الجلسة كما لو لم يتم تقديم رمز مميّز للجلسة (تتم فوترة كل طلب بشكل منفصل).

عندما يتم تقديم رمز مميز للجلسة في الطلب إلى AutocompleteSuggestion.fetchAutocompleteSuggestions، سيتم تلقائيًا تضمين الرمز المميز نفسه في الطلب الأول إلى fetchFields على Place يتم عرضه من خلال طلب PlacePrediction.toPlace على أحد عناصر AutocompleteSuggestion الناتجة.

ننصحك باتّباع الإرشادات التالية:
  • استخدِم الرموز المميّزة للجلسات في جميع طلبات "الإكمال التلقائي للأماكن".
  • أنشِئ رمزًا مميزًا جديدًا لكل جلسة.
  • تأكَّد من تمرير رمز مميّز فريد لكل جلسة جديدة. سيؤدي استخدام الرمز المميّز نفسه لأكثر من جلسة واحدة إلى فوترة كل طلب بشكل فردي.

فئة AutocompleteSessionToken

class google.maps.places.AutocompleteSessionToken
library "places"

يمثّل الرمز المميّز للجلسة المستخدَم لتتبُّع جلسة إكمال تلقائي.

const {AutocompleteSessionToken} = await google.maps.importLibrary("places");
AutocompleteSessionToken
AutocompleteSessionToken()
المَعلمات: لا تتوفّر أي مَعلمات
يتم إنشاء مثيل جديد من AutocompleteSessionToken.

فئة PlacePrediction

class google.maps.places.PlacePrediction
library "places"

نتائج عبارات البحث المقترَحة من خلال ميزة "الإكمال التلقائي للأماكن"

const {PlacePrediction} = await google.maps.importLibrary("places");
distanceMeters
readonly
النوع: number optional
طول الخط الجيوديسي بالأمتار من origin في حال تحديد origin
mainText
readonly
النوع: FormattableText optional
تمثّل اسم المكان.
placeId
readonly
النوع: string
المعرّف الفريد للمكان المقترَح ويمكن استخدام هذا المعرّف في واجهات برمجة التطبيقات الأخرى التي تقبل أرقام تعريف الأماكن.
secondaryText
readonly
النوع: FormattableText optional
تمثّل ميزات إضافية لإزالة الغموض (مثل مدينة أو منطقة) لتحديد المكان بشكل أكبر.
text
readonly
النوع: FormattableText
تحتوي على الاسم الذي يمكن لشخص عادي قراءته للنتيجة المعروضة. بالنسبة إلى نتائج المؤسسات، يكون هذا عادةً اسم النشاط التجاري وعنوانه.

يُنصح باستخدام text للمطوّرين الذين يريدون عرض عنصر واحد في واجهة المستخدم. قد يرغب المطوّرون الذين يريدون عرض عنصرَين منفصلَين في واجهة المستخدم، ولكن مرتبطَين، في استخدام PlacePrediction.mainText وPlacePrediction.secondaryText بدلاً من ذلك.
types
readonly
النوع: Array<string>
قائمة بالأنواع التي تنطبق على هذا المكان من الجدول (أ) أو الجدول (ب) في https://developers.google.com/maps/documentation/places/web-service/place-types.
BetafetchAddressValidation
fetchAddressValidation(request)
المَعلمات:
القيمة المعروضة: Promise<AddressValidation>
يتم إرسال طلب Address Validation مرتبط بجلسة الإكمال التلقائي هذه (يتم ملء الطلب داخليًا باستخدام الرمز المميّز لجلسة الإكمال التلقائي). لا يتم تضمين أي معلومات عن المكان من PlacePrediction تلقائيًا، فهذه طريقة ملائمة للمساعدة في إدارة جلسات الإكمال التلقائي.
toPlace
toPlace()
المَعلمات: لا تتوفّر أي مَعلمات
القيمة المعروضة: Place
تعرض تمثيل Place لـ PlacePrediction. يجب إجراء طلب لاحق إلى Place.fetchFields للحصول على تفاصيل المكان الكاملة.

إذا تم توفير AutocompleteRequest.sessionToken في AutocompleteRequest المستخدَم لجلب PlacePrediction هذا، سيتم تضمين الرمز المميّز نفسه تلقائيًا عند استدعاء fetchFields.

بدلاً من ذلك، عند استخدام PlaceAutocompleteElement، سيتم تلقائيًا تضمين الرمز المميز للجلسة في الطلب الأول إلى Place.fetchFields على Place الذي يعرضه PlacePrediction.toPlace.

فئة StringRange

class google.maps.places.StringRange
library "places"

تحدّد سلسلة فرعية ضمن نص معيّن.

const {StringRange} = await google.maps.importLibrary("places");
endOffset
readonly
النوع: number
تمثّل هذه السمة الإزاحة المستندة إلى الصفر لآخر حرف Unicode في السلسلة الفرعية (غير شاملة).
startOffset
readonly
النوع: number
تمثّل هذه السمة الإزاحة المستندة إلى الصفر لأول حرف يونيكود في السلسلة الفرعية (شاملة).

فئة FormattableText

class google.maps.places.FormattableText
library "places"

نص يمثّل توقّعًا لمكان معيّن يمكن استخدام النص كما هو أو تنسيقه.

const {FormattableText} = await google.maps.importLibrary("places");
matches
readonly
النوع: Array<StringRange>
قائمة بنطاقات السلاسل التي تحدّد مكان مطابقة طلب الإدخال في FormattableText.text يمكن استخدام النطاقات لتنسيق أجزاء معيّنة من text. قد لا تكون السلاسل الفرعية مطابقة تمامًا لـ AutocompleteRequest.input إذا تم تحديد المطابقة وفقًا لمعايير أخرى غير مطابقة السلسلة (على سبيل المثال، تصحيحات الأخطاء الإملائية أو التحويلات الصوتية). هذه القيم هي إزاحات أحرف Unicode لـ FormattableText.text. يتم ضمان ترتيب النطاقات بقيم إزاحة متزايدة.
text
readonly
النوع: string
النص الذي يمكن استخدامه كما هو أو تنسيقه باستخدام FormattableText.matches.
toString
toString()
المَعلمات: لا تتوفّر أي مَعلمات
القيمة المعروضة: string
تعرض FormattableText.text.