Đặt tiện ích Tự động hoàn thành

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Nếu địa chỉ thanh toán của bạn ở Khu vực kinh tế Châu Âu, thì kể từ ngày 8 tháng 7 năm 2025, Điều khoản dịch vụ của Google Maps Platform ở EEA sẽ áp dụng cho việc bạn sử dụng Dịch vụ. Chức năng sẽ khác nhau tuỳ theo khu vực. Tìm hiểu thêm.

Tiện ích Place Autocomplete tạo ra một trường nhập dữ liệu văn bản, cung cấp các cụm từ gợi ý về địa điểm trong danh sách chọn trên giao diện người dùng và trả về Place Details theo lựa chọn của người dùng. Hãy sử dụng Place Autocomplete Widget để nhúng một giao diện người dùng tự động hoàn thành hoàn chỉnh và độc lập trên trang web của bạn. Để xem tài liệu tham khảo API hoàn chỉnh, hãy xem PlaceAutocompleteElement.

Điều kiện tiên quyết

Để sử dụng Place Autocomplete, bạn phải bật Places API (Mới) trên dự án Google Cloud của mình. Hãy xem phần Bắt đầu để biết thông tin chi tiết.

Tính năng mới

Tính năng Place Autocomplete đã được cải thiện theo những cách sau:

• Giao diện người dùng của tiện ích Tự động hoàn thành hỗ trợ bản địa hoá theo khu vực (bao gồm cả ngôn ngữ RTL) cho phần giữ chỗ nhập văn bản, biểu trưng danh sách cụm từ gợi ý và cụm từ gợi ý về địa điểm.
• Cải thiện khả năng hỗ trợ tiếp cận, bao gồm cả tính năng hỗ trợ cho trình đọc màn hình và tương tác bằng bàn phím.
• Tiện ích Tự động hoàn thành trả về Lớp địa điểm mới (Place tài liệu tham khảo) để đơn giản hoá việc xử lý đối tượng được trả về.
• Hỗ trợ tốt hơn cho thiết bị di động và màn hình nhỏ.
• Hiệu suất tốt hơn và giao diện đồ hoạ được cải thiện.

Thêm tiện ích Tự động hoàn thành

Tiện ích Tự động hoàn thành tạo ra một trường nhập dữ liệu, cung cấp các cụm từ gợi ý về địa điểm trong danh sách chọn trên giao diện người dùng và trả về Place Details theo lượt nhấp của người dùng bằng trình nghe gmp-select. Phần này hướng dẫn cách thêm tiện ích tự động hoàn thành vào trang web hoặc bản đồ Google.

Thêm tiện ích Tự động hoàn thành vào trang web

Để thêm tiện ích Tự động hoàn thành vào trang web, hãy tạo một google.maps.places.PlaceAutocompleteElement, rồi thêm tiện ích đó vào trang như trong ví dụ sau:

TypeScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);
index.js

Xem ví dụ về đoạn mã hoàn chỉnh

Thêm tiện ích Tự động hoàn thành vào bản đồ

Nếu địa chỉ thanh toán của bạn ở bên ngoài Khu vực kinh tế Châu Âu (EEA), bạn cũng có thể sử dụng tiện ích Tự động hoàn thành với Bản đồ Google.

Để thêm tiện ích Tự động hoàn thành vào bản đồ, trước tiên, hãy yêu cầu các thư viện cần thiết như minh hoạ sau:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

Sau đó, trong HTML, hãy lồng một phần tử gmp-place-autocomplete mới vào trong một div và lồng div đó vào trong một gmp-map như trong ví dụ sau:

<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
    <div
        class="place-autocomplete-card"
        slot="control-inline-start-block-start">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>
index.html

Để thêm tiện ích Tự động hoàn thành vào bản đồ theo phương thức lập trình, hãy tạo một thực thể google.maps.places.PlaceAutocompleteElement mới, thêm PlaceAutocompleteElement vào div và áp dụng thuộc tính slot cho div như trong ví dụ sau:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

Xem ví dụ về đoạn mã hoàn chỉnh

Thêm văn bản phần giữ chỗ

Sử dụng thuộc tính placeholder để thêm văn bản phần giữ chỗ. Ví dụ sau đây cho thấy cách thiết lập văn bản phần giữ chỗ trong HTML:

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

Bạn cũng có thể thiết lập văn bản phần giữ chỗ theo phương thức lập trình:

placeAutocomplete.placeholder = 'Search for a place...';

Giới hạn cụm từ gợi ý của tính năng tự động hoàn thành

Theo mặc định, Place Autocomplete sẽ đưa ra tất cả các loại địa điểm, ưu tiên các cụm từ gợi ý gần vị trí của người dùng và tìm nạp tất cả các trường dữ liệu có sẵn cho địa điểm mà người dùng chọn. Hãy thiết lập PlaceAutocompleteElementOptions để đưa ra các cụm từ gợi ý phù hợp hơn bằng cách hạn chế hoặc ưu tiên kết quả.

Việc hạn chế kết quả sẽ khiến tiện ích Tự động hoàn thành bỏ qua mọi kết quả nằm ngoài khu vực hạn chế. Một phương pháp thường dùng là hạn chế kết quả trong phạm vi bản đồ. Việc ưu tiên kết quả sẽ khiến tiện ích Tự động hoàn thành hiển thị kết quả trong khu vực đã chỉ định, nhưng một số kết quả phù hợp có thể nằm ngoài khu vực đó.

Nếu bạn không cung cấp bất kỳ phạm vi hoặc khung nhìn bản đồ nào, API sẽ cố gắng phát hiện vị trí của người dùng từ địa chỉ IP của họ và sẽ ưu tiên kết quả cho vị trí đó. Hãy thiết lập phạm vi bất cứ khi nào có thể. Nếu không, những người dùng khác nhau có thể nhận được các cụm từ gợi ý khác nhau. Ngoài ra, để cải thiện cụm từ gợi ý nói chung, bạn cần cung cấp một khung nhìn hợp lý, chẳng hạn như khung nhìn mà bạn thiết lập bằng cách di chuyển hoặc thu phóng trên bản đồ, hoặc khung nhìn do nhà phát triển thiết lập dựa trên vị trí và bán kính của thiết bị. Khi không có bán kính, 5 km được coi là giá trị mặc định hợp lý cho tính năng Place Autocomplete. Đừng thiết lập a khung nhìn có bán kính bằng 0 (một điểm duy nhất), khung nhìn chỉ rộng vài mét (dưới 100 mét) hoặc khung nhìn bao phủ toàn cầu.

Hạn chế tìm kiếm địa điểm theo quốc gia

Để hạn chế tìm kiếm địa điểm ở một hoặc nhiều quốc gia cụ thể, hãy sử dụng thuộc tính includedRegionCodes để chỉ định(các) mã quốc gia như trong đoạn mã sau (đoạn mã này giả định rằng bạn đã tạo một thực thể có tên là placeAutocomplete):

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

Hạn chế tìm kiếm địa điểm trong phạm vi bản đồ

Để hạn chế tìm kiếm địa điểm trong phạm vi bản đồ, hãy sử dụng thuộc tính locationRestriction. Đoạn mã sau đây cho biết cách thêm trình nghe để cập nhật phạm vi khi phạm vi thay đổi:

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});

Để xoá locationRestriction, hãy đặt thành null.

Ưu tiên kết quả tìm kiếm địa điểm

Ưu tiên kết quả tìm kiếm địa điểm cho một khu vực hình tròn bằng cách sử dụng thuộc tính locationBias như minh hoạ sau:

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

Để xoá locationBias, hãy đặt thành null.

Hạn chế kết quả tìm kiếm địa điểm theo một số loại

Hạn chế kết quả tìm kiếm địa điểm theo một số loại địa điểm bằng cách sử dụng thuộc tính includedPrimaryTypes và chỉ định một hoặc nhiều loại như minh hoạ sau:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Để xem danh sách đầy đủ các loại được hỗ trợ, hãy xem Bảng A và B về loại địa điểm.

Xem thông tin chi tiết về địa điểm

Để xem Place Details cho địa điểm đã chọn, hãy thêm gmp-select trình nghe vào PlaceAutocompleteElement, như trong ví dụ sau:

TypeScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({
        placePrediction,
    }: google.maps.places.PlacePredictionSelectEvent) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);
index.js

Xem ví dụ về đoạn mã hoàn chỉnh

Trong ví dụ trước, trình nghe sự kiện nhận được PlacePredictionSelectEvent và gọi placePrediction.toPlace() để nhận thực thể Lớp địa điểm (Place tham chiếu). Hãy gọi place.fetchFields() để nhận các trường dữ liệu Place Details cần thiết cho ứng dụng của bạn.

Trình nghe trong ví dụ tiếp theo yêu cầu thông tin về địa điểm và hiển thị thông tin đó trên bản đồ.

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = 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) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location!);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = 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) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);
index.js

Xem ví dụ về đoạn mã hoàn chỉnh

Bản đồ mẫu

Phần này chứa đoạn mã hoàn chỉnh cho các bản đồ mẫu có trên trang này.

Phần tử tự động hoàn thành

Ví dụ này thêm tiện ích Tự động hoàn thành vào trang web và hiển thị kết quả cho từng địa điểm đã chọn.

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>
index.html

Bản đồ tự động hoàn thành

Ví dụ này hướng dẫn cách thêm tiện ích Tự động hoàn thành vào bản đồ Google.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = 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) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location!);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();
index.ts

Lưu ý: Hãy đọc hướng dẫn về cách sử dụng TypeScript và Google Maps.

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = 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) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            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: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

.place-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: small;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Tối ưu hoá tính năng Tự động hoàn thành (Mới)

Phần này mô tả các phương pháp hay nhất giúp bạn tận dụng tối đa dịch vụ Tự động hoàn thành (Mới).

Dưới đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển giao diện người dùng hoạt động là sử dụng tiện ích Tự động hoàn thành (Mới) của Maps JavaScript API, tiện ích Tự động hoàn thành (Mới) của Places SDK cho Android hoặc tiện ích Tự động hoàn thành (Mới) của Places SDK cho iOS.
• Ngay từ đầu, hãy tìm hiểu các trường dữ liệu Tự động hoàn thành (Mới) cần thiết.
• Các trường ưu tiên vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất của tính năng tự động hoàn thành.
• Hãy sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn hoạt động bình thường nếu API trả về lỗi.
• Hãy đảm bảo ứng dụng của bạn xử lý trường hợp không có lựa chọn và cung cấp cho người dùng cách tiếp tục.

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành (Mới) , hãy sử dụng mặt nạ trường trong tiện ích Place Details (Mới) và Tự động hoàn thành (Mới) để chỉ trả về các trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình để truy cập vào SKU: Giá yêu cầu tự động hoàn thành và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Place Details (Mới). Giá theo mỗi yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với giá theo mỗi phiên (dựa trên phiên) nếu cả hai điều kiện sau đều được đáp ứng:

• Nếu bạn chỉ cần vĩ độ và kinh độ hoặc địa chỉ của địa điểm mà người dùng chọn, thì Geocoding API sẽ cung cấp thông tin này với chi phí thấp hơn so với lệnh gọi Place Details (Mới).
• Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong trung bình 4 yêu cầu tự động hoàn thành (Mới) trở xuống, thì giá theo mỗi yêu cầu có thể tiết kiệm chi phí hơn so với giá theo mỗi phiên.

Để được trợ giúp chọn cách triển khai tính năng Tự động hoàn thành (Mới) phù hợp với nhu cầu của bạn, hãy chọn thẻ tương ứng với câu trả lời của bạn cho câu hỏi sau.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của cụm từ gợi ý đã chọn không?

Có, cần thêm thông tin chi tiết

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì ứng dụng của bạn yêu cầu Thông tin chi tiết về địa điểm (Mới), chẳng hạn như tên địa điểm, trạng thái kinh doanh, hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên (theo phương thức lập trình hoặc được tích hợp vào các JavaScript, Android, hoặc iOS tiện ích) cho mỗi phiên cộng với các SKU Địa điểm áp dụng, tuỳ thuộc vào các trường dữ liệu địa điểm mà bạn yêu cầu.¹

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các JavaScript, Android, hoặc iOS. Tính năng này bao gồm cả các yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) trên cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường dữ liệu Tự động hoàn thành (Mới) data fields mà bạn cần.

Triển khai theo phương thức lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm từ phản hồi Tự động hoàn thành (Mới)
2. Mã thông báo phiên được sử dụng trong yêu cầu Tự động hoàn thành (Mới)
3. Tham số fields chỉ định các trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần

Không, chỉ cần địa chỉ và vị trí

Geocoding API có thể là một lựa chọn tiết kiệm chi phí hơn so với Place Details (Mới) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng tính năng Tự động hoàn thành (Mới). Hiệu quả của tính năng Tự động hoàn thành (Mới) của mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung mà người dùng nhập, vị trí sử dụng ứng dụng và việc các phương pháp hay nhất để tối ưu hoá hiệu suất đã được triển khai hay chưa.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự mà người dùng nhập trung bình trước khi chọn một cụm từ gợi ý Tự động hoàn thành (Mới) trong ứng dụng của bạn.

Trung bình, người dùng của bạn có chọn một cụm từ gợi ý Tự động hoàn thành (Mới) trong 4 yêu cầu trở xuống không?

Có

Triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình mà không cần mã thông báo phiên và gọi Geocoding API trên cụm từ gợi ý về địa điểm đã chọn.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ. Việc thực hiện 4 yêu cầu Tự động hoàn thành cộng với một lệnh gọi Geocoding API về cụm từ gợi ý về địa điểm đã chọn sẽ có chi phí thấp hơn so với chi phí Tự động hoàn thành (Mới) theo mỗi phiên.¹

Hãy cân nhắc việc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm chỉ với ít ký tự hơn.

Không

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì số lượng yêu cầu trung bình mà bạn dự kiến thực hiện trước khi người dùng chọn một cụm từ gợi ý Tự động hoàn thành (Mới) vượt quá chi phí của giá theo mỗi phiên, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên cho cả các yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) liên quan cho mỗi phiên. ¹

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các JavaScript, Android, hoặc iOS. Tính năng này bao gồm cả các yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) yêu cầu trên cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường mà bạn cần.

Triển khai theo phương thức lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm từ phản hồi Tự động hoàn thành (Mới)
2. Mã thông báo phiên được sử dụng trong yêu cầu Tự động hoàn thành (Mới)
3. Tham số fields chỉ định các trường như địa chỉ và hình học

Cân nhắc việc trì hoãn các yêu cầu Tự động hoàn thành (Mới)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành (Mới) cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng của bạn thực hiện ít yêu cầu hơn. Ví dụ: việc thực hiện các yêu cầu Tự động hoàn thành (Mới) cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự rồi chọn một cụm từ gợi ý mà bạn thực hiện một yêu cầu Geocoding API, thì tổng chi phí sẽ là 4 yêu cầu Tự động hoàn thành (Mới) + Geocoding.¹

Nếu việc trì hoãn các yêu cầu có thể giúp yêu cầu trung bình theo phương thức lập trình của bạn xuống dưới 4, thì bạn có thể làm theo hướng dẫn về cách triển khai tính năng Tự động hoàn thành (Mới) hiệu suất cao với Geocoding API. Xin lưu ý rằng việc trì hoãn các yêu cầu có thể bị người dùng coi là độ trễ. Người dùng có thể mong đợi thấy các cụm từ gợi ý sau mỗi lần nhấn phím mới.

Hãy cân nhắc việc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm chỉ với ít ký tự hơn.

---

1. Để biết chi phí, hãy xem danh sách giá của Google Maps Platform.

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả cách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành (Mới):

• Thêm các hạn chế theo quốc gia, ưu tiên vị trí, và (đối với việc triển khai theo phương thức lập trình) ngôn ngữ ưu tiên vào việc triển khai tính năng Tự động hoàn thành (Mới) . Bạn không cần lựa chọn ưu tiên về ngôn ngữ với các tiện ích vì các tiện ích này sẽ chọn ngôn ngữ ưu tiên từ trình duyệt hoặc thiết bị di động của người dùng.
• Nếu tính năng Tự động hoàn thành (Mới) đi kèm với bản đồ, bạn có thể ưu tiên vị trí theo khung nhìn bản đồ.
• Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý Tự động hoàn thành (Mới), thường là vì không có cụm từ gợi ý nào là địa chỉ kết quả mà họ muốn, bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
  • Nếu bạn dự kiến người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến Geocoding API.
  • Nếu bạn dự kiến người dùng sẽ nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Thông tin chi tiết về địa điểm (Mới). Nếu bạn chỉ dự kiến kết quả ở một khu vực cụ thể, hãy sử dụng tính năng ưu tiên vị trí.
  Các trường hợp khác mà bạn nên quay lại sử dụng Geocoding API bao gồm:
  • Người dùng nhập địa chỉ phụ, chẳng hạn như địa chỉ cho các đơn vị hoặc căn hộ cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" sẽ cho ra một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành (Mới).
  • Người dùng nhập địa chỉ có tiền tố phân đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawai'i.

Ưu tiên vị trí

Ưu tiên kết quả cho một khu vực đã chỉ định bằng cách truyền tham số location và tham số radius. Điều này hướng dẫn tính năng Tự động hoàn thành (Mới) ưu tiên hiển thị kết quả trong khu vực đã xác định. Kết quả nằm ngoài khu vực đã xác định vẫn có thể xuất hiện. Bạn có thể sử dụng tham số includedRegionCodes để lọc kết quả chỉ cho thấy những địa điểm trong một quốc gia đã chỉ định.

Cảnh báo: Nếu bạn không cung cấp radius, tham số location sẽ bị bỏ qua.

Kết quả về cơ sở kinh doanh thường không xếp hạng đủ cao để xuất hiện trong kết quả khi khu vực tìm kiếm lớn. Nếu bạn muốn các cơ sở kinh doanh xuất hiện trong kết quả hỗn hợp về cơ sở kinh doanh/mã địa lý, bạn có thể chỉ định bán kính nhỏ hơn. Ngoài ra, hãy sử dụng types=establishment để chỉ hạn chế kết quả cho các cơ sở kinh doanh.

Hạn chế vị trí

Hạn chế kết quả cho một khu vực đã chỉ định bằng cách truyền tham số locationRestriction.

Bạn cũng có thể hạn chế kết quả cho khu vực được xác định bằng location và tham số radius bằng cách thêm tham số locationRestriction. Điều này hướng dẫn tính năng Tự động hoàn thành (Mới) chỉ trả về kết quả trong khu vực đó.

Lưu ý: Các hạn chế về vị trí chỉ được áp dụng cho toàn bộ tuyến đường. Kết quả tổng hợp nằm ngoài hạn chế về vị trí có thể được trả về dựa trên tuyến đường trùng với hạn chế về vị trí.