تکمیل خودکار مکان یکی از ویژگیهای کتابخانه Places در Maps JavaScript API است. میتوانید از تکمیل خودکار استفاده کنید تا به برنامههای خود رفتار جستجوی پیشنویس فیلد جستجوی Google Maps را بدهید.
این صفحه تفاوتهای بین ویژگیهای قدیمی و جدید تکمیل خودکار مکان را توضیح میدهد. در هر دو نسخه دو روش کلی برای ادغام تکمیل خودکار وجود دارد:
- رابط برنامه نویسی : برای توسعه دهندگانی که به دنبال سفارشی سازی و کنترل بیشتر بر تجربه تکمیل خودکار هستند.
- ویجت تکمیل خودکار مکان : نوار جستجویی که می تواند روی نقشه یا صفحه وب جاسازی شود.
تکمیل خودکار رابط برنامه ای
جدول زیر برخی از تفاوتهای اصلی در استفاده از تکمیل خودکار مکان برنامهریزی شده بین سرویس تکمیل خودکار مکانها (قدیمی) و تکمیل خودکار دادههای API (جدید) را فهرست میکند:
PlacesService (قدیمی) | Place (جدید) |
---|---|
مرجع خدمات تکمیل خودکار مکان ها | مرجع تکمیل خودکار داده (جدید). |
AutocompletionRequest | AutocompleteRequest |
AutocompleteService.getPlacePredictions | AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction | PlacePrediction |
روشها نیاز به استفاده از یک فراخوان برای رسیدگی به شی نتایج و پاسخ PlacesServiceStatus دارند. | از Promises استفاده می کند و به صورت ناهمزمان کار می کند. |
روشها به بررسی PlacesServiceStatus نیاز دارند. | بدون بررسی وضعیت مورد نیاز، می توان از مدیریت خطای استاندارد استفاده کرد. |
هنگامی که نمونه Autocomplete ایجاد می شود، فیلدهای داده مکان به عنوان گزینه تنظیم می شوند. | فیلدهای داده مکان بعداً با فراخوانی fetchFields() تنظیم می شوند. |
پیشبینیهای پرس و جو پشتیبانی میشوند (فقط SearchBox ). | پیشبینیهای پرس و جو در کلاس Autocomplete در دسترس نیستند. |
محدود به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان . | دسترسی به مجموعه گسترده ای از انواع مکان و فیلدهای داده مکان . |
موارد زیر توسط APIهای قدیمی و جدید تکمیل خودکار استفاده می شود:
مقایسه کد (برنامه ای)
این بخش کدهای تکمیل خودکار را مقایسه میکند تا تفاوتهای بین سرویس Places و کلاس Place را برای رابطهای برنامهنویسی نشان دهد.
بازیابی پیشبینیهای تکمیل خودکار (میراث)
سرویس مکانهای قدیمی به شما امکان میدهد پیشبینیهای تکمیل خودکار را بهصورت برنامهریزی بازیابی کنید، تا کنترل بیشتری بر رابط کاربری نسبت به کلاس 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}`
}
- API تکمیل خودکار داده را قرار دهید
- نمونه پیشبینیهای تکمیل خودکار داده را قرار دهید
- نمونه جلسات داده تکمیل خودکار را قرار دهید
- نشانه های جلسه
- مرجع رابط
AutocompleteRequest
- مرجع کلاس
AutocompleteSuggestion
- مرجع کلاس
PlacePrediction
ویجت تکمیل خودکار را قرار دهید
جدول زیر برخی از تفاوتهای اصلی در استفاده از ویجتهای تکمیل خودکار بین سرویس Places (میراث) و کلاس Place (جدید) را فهرست میکند:
خدمات مکانها (قدمتی) | مکان (جدید) |
---|---|
کلاس Autocomplete برای پیش بینی مکان. | کلاس PlaceAutocompleteElement برای پیش بینی مکان. |
کلاس SearchBox برای پیش بینی پرس و جو | پیشبینیهای پرس و جو در کلاس Autocomplete در دسترس نیستند. |
فقط متن متغیر ورودی پیش فرض بومی سازی شده است. | مکاننمای ورودی متن، نشانواره فهرست پیشبینیها و پیشبینیهای مکان، همگی از محلیسازی منطقهای پشتیبانی میکنند. |
ویجت از setBounds() یا autocomplete.bindTo() برای محدود کردن (بایاس) جستجو به محدوده های مشخص شده و strictBounds برای محدود کردن نتایج به محدوده های مشخص شده استفاده می کند. | ویجت از ویژگی locationBias برای سوگیری نتایج به محدوده های مشخص شده و از ویژگی locationRestriction برای محدود کردن جستجو به محدوده های مشخص شده استفاده می کند. |
ابزارک ها را فقط می توان با استفاده از یک عنصر ورودی استاندارد HTML یکپارچه کرد. | ویجت را می توان با استفاده از یک عنصر ورودی استاندارد HTML یا یک عنصر gmp-place-autocomplete یکپارچه کرد. |
هنگام استفاده از ویجت، این امکان برای کاربران وجود دارد که مواردی را درخواست کنند که ممکن است معتبر نباشند (به عنوان مثال "bisneyland"). این پرونده باید به صراحت رسیدگی شود. | ویجت فقط نتایج را برای پیشنهادات ارائه شده برمی گرداند و نمی تواند درخواست هایی برای مقادیر دلخواه صادر کند. بنابراین نیازی به رسیدگی به درخواست های بالقوه نامعتبر نیست. |
نمونه قدیمی PlaceResult را برمیگرداند. | نمونه Place برمی گرداند. |
فیلدهای داده مکان به عنوان گزینه برای شی Autocomplete تنظیم می شوند. | فیلدهای داده مکان زمانی تنظیم می شوند که کاربر یک انتخاب انجام می دهد و fetchFields() فراخوانی می شود. |
محدود به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان . | دسترسی به مجموعه گسترده ای از انواع مکان و فیلدهای داده مکان . |
مقایسه کد (ویجت ها)
این بخش کدهای تکمیل خودکار را مقایسه میکند تا تفاوتهای بین ویجت تکمیل خودکار مکان قدیمی و عنصر تکمیل خودکار مکان جدید را نشان دهد.
ویجت تکمیل خودکار مکان (قدیمی)
سرویس مکان ها دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید با استفاده از کلاس های Autocomplete
و SearchBox
آنها را اضافه کنید. هر نوع ویجت را می توان به عنوان کنترل نقشه به نقشه اضافه کرد یا مستقیماً در یک صفحه وب جاسازی کرد. مثال کد زیر تعبیه یک ویجت Autocomplete
به عنوان کنترل نقشه نشان می دهد.
- سازنده ویجت
Autocomplete
دو آرگومان می گیرد:- یک عنصر
input
HTML از نوعtext
. این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند. - یک آرگومان اختیاری
AutocompleteOptions
، که در آن می توانید گزینه های بیشتری را برای محدود کردن پرس و جو مشخص کنید.
- یک عنصر
- برای تنظیم کرانه ها، نمونه
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
ویجت تکمیل خودکار مکان (جدید)
کلاس Place PlaceAutocompleteElement
را ارائه می دهد، یک زیر کلاس HTMLElement
که یک مؤلفه UI را ارائه می دهد که می تواند به عنوان کنترل نقشه به نقشه اضافه شود یا مستقیماً در یک صفحه وب جاسازی شود. مثال کد زیر تعبیه یک ویجت PlaceAutocompleteElement
را به عنوان کنترل نقشه نشان می دهد.
ویجت تکمیل خودکار مکان به روش های زیر بهبود یافته است:
- رابط کاربری ویجت تکمیل خودکار از محلیسازی منطقهای (از جمله زبانهای RTL) برای مکانگردان ورودی متن، نشانواره فهرست پیشبینیها و پیشبینیهای مکان پشتیبانی میکند.
- دسترسی پیشرفته، از جمله پشتیبانی از صفحهخوانها و تعامل با صفحهکلید.
- ویجت Autocomplete کلاس
Place
جدید را برمی گرداند تا مدیریت شیء برگشتی را ساده کند. - پشتیبانی بهتر از دستگاه های تلفن همراه و صفحه نمایش های کوچک.
- عملکرد بهتر و ظاهر گرافیکی بهبود یافته.
تفاوت های اصلی پیاده سازی عبارتند از:
- پیشبینیهای پرس و جو در کلاس
Autocomplete
در دسترس نیستند. -
PlaceAutocompleteElement
با استفاده ازPlaceAutocompleteElementOptions
ساخته شده است. - فیلدهای داده مکان در زمان انتخاب مشخص می شوند (زمانی که
fetchFields()
فراخوانی می شود. - با استفاده از گزینه
locationBounds
یاlocationRestriction
محدوده ها را تنظیم کنید. - با استفاده از ویژگی
id
(به ارث رسیده ازHTMLElement
)PlaceAutocompleteElement
با یک عنصر ورودی متن HTML مرتبط کنید.
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-placeselect listener, and display the results on the map.
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
// 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,
});
}