«تکمیل خودکار جا» یکی از ویژگیهای کتابخانه «جاها» در Maps JavaScript API است. میتوانید از تکمیل خودکار استفاده کنید تا به برنامههایتان رفتار جستجوی پیشتایپ فیلد جستجوی Google Maps را بدهید.
این صفحه تفاوتهای بین ویژگیهای قدیمی و جدید «تکمیل خودکار جا» را توضیح میدهد. در هر دو نسخه، دو روش کلی برای ادغام «تکمیل خودکار» وجود دارد:
- میانای برنامهریزیشده: برای توسعهدهندگانی که بهدنبال شخصیسازی و کنترل بیشتر بر تجربه تکمیل خودکار هستند.
- ابزاره «تکمیل خودکار مکان»: نوار جستجویی که میتواند در نقشه یا صفحه وب جاسازی شود.
میانای برنامهنویسی تکمیل خودکار
جدول زیر برخیاز تفاوتهای اصلی در استفاده از «تکمیل خودکار جا» برنامهای بین سرویس تکمیل خودکار Places (قدیمی) و میانای برنامهسازی کاربردی داده تکمیل خودکار (جدید) را فهرست میکند:
PlacesService (قدیمی) |
Place (جدید) |
|---|---|
| مرجع سرویس تکمیل خودکار مکانها | مرجع دادههای تکمیل خودکار (جدید) |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
روشها برای مدیریت کردن شیء نتایج و
PlacesServiceStatus پاسخ نیاز به استفاده از تماس برگشتی دارند. |
از Promises استفاده میکند و بهصورت ناهمگام کار میکند. |
روشها به بررسی PlacesServiceStatus نیاز دارند. |
بررسی وضعیت الزامی نیست، میتوان از مدیریت خطای استاندارد استفاده کرد. بیشتر بدانید. |
فیلدهای داده مکان هنگام ایجاد نمونه Autocomplete
بهعنوان گزینه تنظیم میشوند. |
فیلدهای داده مکان بعداً وقتی fetchFields() فراخوانی میشود
تنظیم میشود. |
پیشبینیهای پُرسمان پشتیبانی میشود (فقط SearchBox). |
پیشبینیهای پُرسمان در کلاس Autocomplete دردسترس نیست. |
| به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان محدود میشود. | دسترسی به انتخاب گستردهای از انواع مکان و فیلدهای داده مکان. |
موارد زیر هم توسط میاناهای برنامهسازی کاربردی «تکمیل خودکار» قدیمی و هم جدید استفاده میشوند:
مقایسه کد (برنامهریزیشده)
این بخش کد تکمیل خودکار را مقایسه میکند تا تفاوتهای بین «خدمات مکانها» و کلاس «مکان» را برای میاناهای برنامهنویسی نشان دهد.
بازیابی پیشبینیهای تکمیل خودکار (قدیمی)
«سرویس مکانهای» قدیمی به شما امکان میدهد پیشبینیهای تکمیل خودکار را بهصورت برنامهنویسیشده بازیابی کنید تا کنترل بیشتری بر میانای کاربر نسبتبه آنچه کلاس Autocomplete ارائه میدهد داشته باشید. در مثال زیر،
یک درخواست واحد برای «par» با AutocompletionRequest شامل
مقدار ورودی و مجموعهای از محدودهها برای گرایش پیشبینی ساخته میشود. مثال
فهرستی از
AutocompletePrediction
نمونهها را برمیگرداند و شرح هرکدام را نشان میدهد. تابع نمونه همچنین
یک کد جلسه ایجاد میکند و آن را به درخواست اعمال میکند.
function init() {
const placeInfo = document.getElementById("prediction");
const service = new google.maps.places.AutocompleteService();
const placesService = new google.maps.places.PlacesService(placeInfo);
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
bounds: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
}
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const displaySuggestions = function (predictions, status) {
// Check the status of the Places Service.
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
document.getElementById("results").appendChild(li);
});
const placeRequest = {
placeId: predictions[0].place_id,
fields: ["name", "formatted_address"],
};
placesService.getDetails(placeRequest, (place, status) => {
if (status == google.maps.places.PlacesServiceStatus.OK && place) {
placeInfo.textContent = `
First predicted place: ${place.name} at ${place.formatted_address}`
}
});
};
// Show the results of the query.
service.getPlacePredictions(request, displaySuggestions);
}
- واکشی برنامهریزیشده پیشبینیهای «سرویس تکمیل خودکار مکان»
- نمونه «تکمیل خودکار جا»
- کدهای جلسه
- مرجع
AutocompletionRequest - مرجع
AutocompletePrediction
بازیابی پیشبینیهای تکمیل خودکار (جدید)
کلاس جدید Place همچنین به شما امکان میدهد پیشبینیهای تکمیل خودکار را بهصورت برنامهنویسیشده بازیابی کنید تا کنترل بیشتری بر میانای کاربر نسبت به آنچه کلاس PlaceAutocompleteElement ارائه میدهد داشته باشید. در مثال زیر، یک درخواست برای «par» با یک AutocompleteRequest متشکل از مقدار ورودی و مجموعهای از مرزها برای سوگیری پیشبینی انجام میشود. این مثال فهرستی از placePrediction
نمونهها را برمیگرداند و شرح هریک را نشان میدهد. تابع نمونه همچنین
یک کد جلسه ایجاد میکند و آن را به درخواست اعمال میکند.
async function init() {
let sessionToken = new google.maps.places.AutocompleteSessionToken();
// Define request options.
let request = {
input: "par",
sessionToken: sessionToken,
locationBias: {
west: -122.44,
north: 37.8,
east: -122.39,
south: 37.78,
},
};
// Display the query string.
const title = document.getElementById("title");
title.appendChild(
document.createTextNode('Place predictions for "' + request.input + '":'),
);
// Perform the query and display the results.
const { suggestions } =
await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
const resultsElement = document.getElementById("results");
for (let suggestion of suggestions) {
const placePrediction = suggestion.placePrediction;
const listItem = document.createElement("li");
listItem.appendChild(
document.createTextNode(placePrediction.text.text),
);
resultsElement.appendChild(listItem);
}
// Show the first predicted place.
let place = suggestions[0].placePrediction.toPlace();
await place.fetchFields({
fields: ["displayName", "formattedAddress"],
});
const placeInfo = document.getElementById("prediction");
placeInfo.textContent = `
First predicted place: ${place.displayName} at ${place.formattedAddress}`
}
- Place Autocomplete Data API
- نمونه پیشبینیهای دادههای تکمیل خودکار جا
- مثال «جلسههای داده تکمیل خودکار جا»
- نشانهای جلسه
- مرجع میانای
AutocompleteRequest - مرجع کلاس
AutocompleteSuggestion - مرجع کلاس
PlacePrediction
ابزاره تکمیل خودکار مکان
جدول زیر برخیاز تفاوتهای اصلی در استفاده از ابزارههای تکمیل خودکار بین سرویس «مکانها» (قدیمی) و کلاس «مکان» (جدید) را فهرست میکند:
| سرویس مکانها (قدیمی) | مکان (جدید) |
|---|---|
برای پیشبینی مکان، از کلاس Autocomplete
استفاده کنید.
|
کلاس PlaceAutocompleteElement
برای پیشبینی مکان.
|
برای پیشبینیهای پُرسمان، از کلاس SearchBoxاستفاده کنید. |
پیشبینیهای پُرسمان در کلاس Autocomplete دردسترس نیست.
|
| فقط نوشتار جایبان ورودی پیشفرض بومیسازی میشود. | جایبان ورودی نوشتار، نشانواره فهرست پیشبینیها، و پیشبینیهای مکان همگی از بومیسازی منطقهای پشتیبانی میکنند. |
ابزاره از
setBounds() یا autocomplete.bindTo()
برای محدود کردن (سوگیری) جستجو به مرزهای مشخصشده، و
strictBounds برای محدود کردن نتایج به مرزهای
مشخصشده استفاده میکند.
|
ابزارک از دارایی locationBias
برای متمایل کردن نتایج به محدودههای مشخصشده و از دارایی locationRestriction
برای محدود کردن جستجو به محدودههای مشخصشده استفاده میکند.
|
| ابزارکها فقط بااستفاده از عنصر ورودی HTML استاندارد میتوانند ادغام شوند. | ابزارک را میتوان بااستفاده از عنصر ورودی HTML استاندارد یا عنصر
gmp-place-autocomplete ادغام کرد. |
| هنگام استفاده از ابزاره، کاربران میتوانند چیزهایی را درخواست کنند که ممکن است معتبر نباشند (برای نمونه «بیسنیلند»)؛ این مورد باید بهطور صریح مدیریت شود. | ابزاره فقط نتایج مربوط به پیشنهادهای ارائهشده را برمیگرداند و نمیتواند برای مقادیر دلخواه درخواست صادر کند؛ بنابراین نیازی به رسیدگی به درخواستهای احتمالاً نامعتبر نیست. |
نمونه قدیمی
PlaceResult را برمیگرداند. |
Place نمونه برمیگرداند. |
فیلدهای داده مکان بهعنوان گزینههایی برای شیء Autocomplete
تنظیم شدهاند. |
فیلدهای داده مکان زمانی تنظیم میشوند که کاربر انتخابی انجام دهد و
fetchFields() فراخوانی شود. |
| به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان محدود میشود. | دسترسی به انتخاب گستردهای از انواع مکان و فیلدهای داده مکان. |
مقایسه کد (ابزارهها)
این بخش کد تکمیل خودکار را مقایسه میکند تا تفاوتهای بین «ابزاره تکمیل خودکار جا» قدیمی و عنصر جدید «تکمیل خودکار جا» را نشان دهد.
ابزاره تکمیل خودکار جا (قدیمی)
«سرویس مکانها» دو نوع ابزارک تکمیل خودکار ارائه میدهد که میتوانید بااستفاده از کلاسهای Autocomplete و SearchBox آنها را اضافه کنید.
هر نوع ابزاره را میتوان بهعنوان کنترل نقشه به نقشه اضافه کرد یا مستقیماً در صفحه وب جاسازی کرد. نمونه کد زیر جاسازی کردن ابزاره Autocomplete
را بهعنوان کنترل نقشه نشان میدهد.
- سازنده ابزاره
Autocompleteدو آرگومان میگیرد:- عنصر HTML
inputاز نوعtext. این فیلد ورودی است که سرویس تکمیل خودکار آن را پایش میکند و نتایجش را به آن پیوست میکند. - متغیر مستقل اختیاری
AutocompleteOptionsکه در آن میتوانید گزینههای بیشتری برای محدود کردن پُرسمان مشخص کنید.
- عنصر HTML
- برای تنظیم مرزها، نمونه
Autocompleteرا میتوان با فراخوانیautocomplete.bindTo()بهطور صریح به نقشه محدود کرد. - فیلدهای داده مکان را در گزینههای تکمیل خودکار مشخص کنید.
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapTypeControl: false,
});
const card = document.getElementById("pac-card");
const input = document.getElementById("pac-input");
const options = {
fields: ["formatted_address", "geometry", "name"],
strictBounds: false,
};
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
const autocomplete = new google.maps.places.Autocomplete(input, options);
// Bind the map's bounds (viewport) property to the autocomplete object,
// so that the autocomplete requests use the current map bounds for the
// bounds option in the request.
autocomplete.bindTo("bounds", map);
const infowindow = new google.maps.InfoWindow();
const infowindowContent = document.getElementById("infowindow-content");
infowindow.setContent(infowindowContent);
const marker = new google.maps.Marker({
map,
anchorPoint: new google.maps.Point(0, -29),
});
autocomplete.addListener("place_changed", () => {
infowindow.close();
marker.setVisible(false);
const place = autocomplete.getPlace();
if (!place.geometry || !place.geometry.location) {
// User entered the name of a Place that was not suggested and
// pressed the Enter key, or the Place Details request failed.
window.alert("No details available for input: '" + place.name + "'");
return;
}
// If the place has a geometry, then present it on a map.
if (place.geometry.viewport) {
map.fitBounds(place.geometry.viewport);
} else {
map.setCenter(place.geometry.location);
map.setZoom(17);
}
marker.setPosition(place.geometry.location);
marker.setVisible(true);
infowindowContent.children["place-name"].textContent = place.name;
infowindowContent.children["place-address"].textContent =
place.formatted_address;
infowindow.open(map, marker);
});
}
- اسناد «تکمیل خودکار جا»
- نمونه ابزاره «تکمیل خودکار جا»
- نمونه «چارگوش جستجوی جاها»
- مرجع کلاس
Autocomplete
ابزاره تکمیل خودکار جا (جدید)
کلاس «مکان»
PlaceAutocompleteElement،
زیرکلاسی HTMLElement را ارائه میدهد که عنصر میانای کاربری را فراهم میکند که میتواند بهعنوان کنترل نقشه به
نقشه اضافه شود یا مستقیماً در صفحه وب جاسازی شود. نمونه کد زیر
جاسازی ابزاره PlaceAutocompleteElement را بهعنوان کنترل نقشه نشان میدهد.
«ابزاره تکمیل خودکار جا» به روشهای زیر بهبود یافته است:
- رابط کاربری ابزاره «تکمیل خودکار» از بومیسازی منطقهای (ازجمله زبانهای راستبهچپ) برای جایبان ورودی نوشتار، نشانواره فهرست پیشبینیها، و پیشبینیهای مکان پشتیبانی میکند.
- دسترسپذیری بهبودیافته، ازجمله پشتیبانی از صفحهخوانها و تعامل با صفحهکلید.
- ابزاره «تکمیل خودکار» کلاس جدید
Placeرا برمیگرداند تا مدیریت شیء برگرداندهشده را ساده کند. - پشتیبانی بهتر از دستگاههای همراه و صفحهنمایشهای کوچک.
- عملکرد بهتر و ظاهر گرافیکی بهبودیافته.
تفاوتهای اصلی پیادهسازی عبارتاند از:
PlaceAutocompleteElementفیلد ورودی خودش را ارائه میدهد و مستقیماً بااستفاده از HTML یا جاوا اسکریپت در صفحه درج میشود (برخلاف ارائه عنصر ورودی موجود).- پیشبینیهای پُرسمان در کلاس
Autocompleteدردسترس نیست. -
PlaceAutocompleteElementبااستفاده ازPlaceAutocompleteElementOptionsساخته شده است.- فیلدهای داده مکان در زمان انتخاب (هنگام فراخوانی
fetchFields()) مشخص میشوند.
- فیلدهای داده مکان در زمان انتخاب (هنگام فراخوانی
- بااستفاده از گزینه
locationBoundsیاlocationRestriction، محدودیتها را تنظیم کنید.
let map;
let marker;
let infoWindow;
async function initMap() {
// Request needed libraries.
const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
google.maps.importLibrary("marker"),
google.maps.importLibrary("places"),
]);
// Initialize the map.
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapId: "4504f8b37365c3d0",
mapTypeControl: false,
});
const placeAutocomplete =
new google.maps.places.PlaceAutocompleteElement({
locationRestriction: map.getBounds(),
});
placeAutocomplete.id = "place-autocomplete-input";
const card = document.getElementById("place-autocomplete-card");
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
// Create the marker and infowindow.
marker = new google.maps.marker.AdvancedMarkerElement({
map,
});
infoWindow = new google.maps.InfoWindow({});
// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener("gmp-select", async ( event ) => {
const place = event.placePrediction.toPlace();
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location", "viewport"],
});
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content =
'<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' +
place.displayName +
'</span><br />' +
'<span id="place-address">' +
place.formattedAddress +
'</span>' +
'</div>';
updateInfoWindow(content, place.location);
marker.position = place.location;
});
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
infoWindow.setContent(content);
infoWindow.setPosition(center);
infoWindow.open({
map,
anchor: marker,
shouldFocus: false,
});
}
- اسناد «ابزاره تکمیل خودکار جا» (پیشنمایش)
- نمونه ابزاره «تکمیل خودکار جا»
- نمونه «عنصر تکمیل خودکار جا»
- مرجع کلاس
PlaceAutocompleteElement