Places UI Kit: Một thư viện có thể sử dụng ngay, cung cấp không gian tuỳ chỉnh và kiểm soát cho nhà phát triển. Hãy dùng thử và chia sẻ ý kiến của bạn về trải nghiệm dùng Bộ giao diện người dùng.

Trang này được dịch bởi Cloud Translation API.

API Dữ liệu tự động hoàn thành địa điểm

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

Place Autocomplete Data API cho phép bạn tìm nạp các cụm từ gợi ý về địa điểm theo phương thức lập trình để tạo trải nghiệm tự động hoàn thành tuỳ chỉnh với mức độ kiểm soát chi tiết hơn so với mức độ kiểm soát có thể có với tiện ích tự động hoàn thành. Trong hướng dẫn này, bạn sẽ tìm hiểu cách sử dụng Place Autocomplete Data API để đưa ra các yêu cầu tự động hoàn thành dựa trên truy vấn của người dùng.

Ví dụ sau đây minh hoạ một chế độ tích hợp đơn giản cho tính năng nhập liệu dự đoán. Nhập cụm từ tìm kiếm, chẳng hạn như "pizza" hoặc "poke", sau đó nhấp để chọn kết quả bạn muốn.

Yêu cầu tự động hoàn thành

Yêu cầu tự động hoàn thành sẽ lấy một chuỗi đầu vào truy vấn và trả về danh sách các dự đoán về địa điểm. Để thực hiện yêu cầu tự động hoàn thành, hãy gọi fetchAutocompleteSuggestions() và truyền một yêu cầu có các thuộc tính cần thiết. Thuộc tính input chứa chuỗi cần tìm kiếm; trong một ứng dụng thông thường, giá trị này sẽ được cập nhật khi người dùng nhập một cụm từ tìm kiếm. Yêu cầu này phải bao gồm một sessionToken, được dùng cho mục đích thanh toán.

Đoạn mã sau đây cho biết cách tạo một phần nội dung yêu cầu và thêm mã thông báo phiên, sau đó gọi fetchAutocompleteSuggestions() để nhận danh sách PlacePrediction.

// Add an initial request body.
let request = {
    input: 'Tadi',
    locationRestriction: {
        west: -122.44,
        north: 37.8,
        east: -122.39,
        south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ['restaurant'],
    language: 'en-US',
    region: 'us',
};
// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
request.sessionToken = token;index.js

Hạn chế cụm từ gợi ý của tính năng Tự động hoàn thành

Theo mặc định, tính năng Tự động hoàn thành địa điểm sẽ trình bày tất cả các loại địa điểm, thiên về những dự đoán 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. Đặt các lựa chọn Tự động hoàn thành tên địa điểm để đưa ra những dự đoán phù hợp hơn bằng cách hạn chế hoặc thiên vị kết quả.

Việc hạn chế kết quả 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 ranh giới trên bản đồ. Việc điều chỉnh 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 được chỉ định, nhưng một số kết quả trùng khớp có thể nằm ngoài khu vực đó.

Dùng thuộc tính origin để chỉ định điểm xuất phát mà từ đó tính khoảng cách trắc địa đến đích đến. Nếu bạn bỏ qua giá trị này, khoảng cách sẽ không được trả về.

Sử dụng thuộc tính includedPrimaryTypes để chỉ định tối đa 5 loại địa điểm. Nếu bạn không chỉ định loại nào, thì hệ thống sẽ trả về địa điểm thuộc tất cả các loại.

Xem tài liệu tham khảo API

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

Để trả về một đối tượng Place từ kết quả dự đoán địa điểm, trước tiên, hãy gọi toPlace(), sau đó gọi fetchFields() trên đối tượng Place thu được (mã phiên từ kết quả dự đoán địa điểm sẽ tự động được đưa vào). Khi bạn gọi fetchFields(), phiên tự động hoàn thành sẽ kết thúc.

let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});
const placeInfo = document.getElementById('prediction');
placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;index.js

Mã thông báo phiên

Mã thông báo phiên sẽ nhóm các giai đoạn truy vấn và lựa chọn của một cụm từ tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Phiên bắt đầu khi người dùng bắt đầu nhập. Phiên kết thúc khi người dùng chọn một địa điểm và thực hiện lệnh gọi đến Địa điểm chi tiết.

Để tạo mã thông báo phiên mới và thêm mã thông báo đó vào một yêu cầu, hãy tạo một phiên bản của AutocompleteSessionToken, sau đó đặt thuộc tính sessionToken của yêu cầu để sử dụng mã thông báo như trong đoạn mã sau:

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
request.sessionToken = token;index.js

Một phiên sẽ kết thúc khi fetchFields() được gọi. Sau khi tạo thực thể Place, bạn không cần truyền mã thông báo phiên đến fetchFields() vì việc này sẽ được xử lý tự động.

await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});index.js

Tạo mã thông báo phiên cho phiên tiếp theo bằng cách tạo một phiên bản mới của AutocompleteSessionToken.

Đề xuất về mã thông báo phiên:

Sử dụng mã thông báo phiên cho tất cả các lệnh gọi Place Autocomplete.
Tạo một mã thông báo mới cho mỗi phiên.
Truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Việc sử dụng cùng một mã thông báo cho nhiều phiên sẽ khiến mỗi yêu cầu bị tính phí riêng lẻ.

Bạn có thể tuỳ ý bỏ qua mã thông báo phiên tự động hoàn thành trong một yêu cầu. Nếu mã thông báo phiên bị bỏ qua, mỗi yêu cầu sẽ được tính phí riêng, kích hoạt SKU Tự động hoàn thành – Theo yêu cầu. Nếu bạn sử dụng lại mã thông báo phiên, thì phiên đó sẽ được coi là không hợp lệ và các yêu cầu sẽ bị tính phí như thể bạn không cung cấp mã thông báo phiên.

Ví dụ:

Khi người dùng nhập một cụm từ tìm kiếm, yêu cầu tự động hoàn thành sẽ được gọi sau mỗi vài lần nhấn phím (không phải cho mỗi ký tự) và một danh sách kết quả có thể có sẽ được trả về. Khi người dùng chọn một mục trong danh sách kết quả, lựa chọn đó sẽ được tính là một yêu cầu và tất cả các yêu cầu được đưa ra trong quá trình tìm kiếm sẽ được gộp lại và tính là một yêu cầu duy nhất. Nếu người dùng chọn một địa điểm, thì cụm từ tìm kiếm sẽ không mất phí và chỉ yêu cầu Dữ liệu về địa điểm mới mất phí. Nếu người dùng không đưa ra lựa chọn trong vòng vài phút kể từ khi bắt đầu phiên, thì chỉ truy vấn tìm kiếm mới bị tính phí.

Theo quan điểm của một ứng dụng, luồng sự kiện diễn ra như sau:

Người dùng bắt đầu nhập một cụm từ tìm kiếm để tìm "Paris, Pháp".
Khi phát hiện thấy dữ liệu đầu vào của người dùng, ứng dụng sẽ tạo một mã thông báo phiên mới, "Mã thông báo A".
Khi người dùng nhập, cứ vài ký tự, API sẽ đưa ra một yêu cầu tự động hoàn thành, hiển thị một danh sách kết quả tiềm năng mới cho từng yêu cầu:
"P"
"Par"
"Paris"
"Paris, Fr"
Khi người dùng chọn:
- Tất cả các yêu cầu phát sinh từ truy vấn đều được nhóm và thêm vào phiên do "Mã thông báo A" đại diện, dưới dạng một yêu cầu duy nhất.
- Lựa chọn của người dùng được tính là một yêu cầu Chi tiết về địa điểm và được thêm vào phiên do "Mã thông báo A" đại diện.
Phiên kết thúc và ứng dụng loại bỏ "Mã thông báo A".

Tìm hiểu về cách tính phí cho phiên

Mã ví dụ hoàn chỉnh

Phần này chứa các ví dụ hoàn chỉnh minh hoạ cách sử dụng Place Autocomplete Data API .

Cụm từ gợi ý của tính năng tự động hoàn thành địa điểm

Ví dụ sau đây minh hoạ cách gọi fetchAutocompleteSuggestions() cho đầu vào "Tadi", sau đó gọi toPlace() trên kết quả dự đoán đầu tiên, tiếp theo là gọi fetchFields() để lấy thông tin chi tiết về địa điểm.

TypeScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
        (await google.maps.importLibrary(
            'places'
        )) as google.maps.PlacesLibrary;

    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title') as HTMLElement;
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results') as HTMLElement;

    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction!.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    let place = suggestions[0].placePrediction!.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction') as HTMLElement;
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

init();index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };
    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    const title = document.getElementById('title');
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));
    const resultsElement = document.getElementById('results');
    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a new list element.
        const listItem = document.createElement('li');
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }
    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}
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;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Predictions</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>index.html

Dùng thử mẫu

JSFiddle.net

Tính năng tự động hoàn thành địa điểm nhập trước với các phiên

Ví dụ này minh hoạ các khái niệm sau:

Gọi fetchAutocompleteSuggestions() dựa trên cụm từ tìm kiếm của người dùng và hiển thị danh sách những địa điểm được dự đoán để phản hồi.
Sử dụng mã thông báo phiên để nhóm một cụm từ tìm kiếm của người dùng với yêu cầu cuối cùng về Thông tin chi tiết về địa điểm.
Truy xuất thông tin chi tiết về địa điểm cho địa điểm đã chọn và hiển thị một điểm đánh dấu.
Sử dụng tính năng phân bổ vị trí điều khiển để lồng các phần tử giao diện người dùng trong phần tử gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let titleElement = document.querySelector('.title') as HTMLElement;
let resultsContainerElement = document.querySelector('.results') as HTMLElement;
let inputElement = document.querySelector('input') as HTMLInputElement;
let tokenStatusElement = document.querySelector('.token-status') as HTMLElement;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary(
        'marker'
    )) as google.maps.MarkerLibrary;

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

init();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;
// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};
async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });
    inputElement.addEventListener('input', makeAutocompleteRequest);
}
async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;
    const { AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }
    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;
    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId)
        return;
    titleElement.innerText = `Place predictions for "${request.input}"`;
    // Clear the list first.
    resultsContainerElement.replaceChildren();
    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        if (!placePrediction) {
            continue;
        }
        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');
        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}
// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';
    await refreshToken();
    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }
    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });
    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}
// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary('places'));
    // Increment the token counter.
    tokenCount++;
    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}
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-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>index.html

Dùng thử mẫu

JSFiddle.net

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 khai thác 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 hiểu rõ các trường dữ liệu quan trọng của tính năng Tự động hoàn thành (Mới).
Các trường thiên vị 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.
Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn giảm hiệu suất một cách thích hợp nếu API trả về lỗi.
Đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn nào 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ụ Autocomplete (New), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (New) và Autocomplete (New) để chỉ trả về các trường dữ liệu Autocomplete (New) 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 theo chương trình tính năng Tự động hoàn thành (Mới) để 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ì Chi tiết về địa điểm (Mới). Mức giá theo yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với mức giá theo phiên (dựa trên phiên) nếu cả hai điều kiện sau đây đều được đáp ứng:

Nếu bạn chỉ cần 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 ít hơn một lệnh gọi Place Details (New).
Nếu người dùng chọn một cụm từ dự đoán tự động hoàn thành trong trung bình 4 yêu cầu dự đoán Tự động hoàn thành (Mới) hoặc ít hơn, thì mức giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá theo phiên.

Để được trợ giúp chọn 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 kết quả dự đoán đã 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 dựa trên phiên (Mới) với tính năng Chi tiết về địa điểm (Mới).
Vì ứng dụng của bạn yêu cầu có 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ờ hoạt động, 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 tiện ích JavaScript, Android hoặc iOS) cho mỗi phiên, cộng với các SKU Địa điểm hiện hành, tuỳ thuộc vào 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 tiện ích JavaScript, Android hoặc iOS. Điều này bao gồm cả yêu cầu Autocomplete (Mới) và yêu cầu Place Details (Mới) đối với cụm từ dự đoán đã 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 Autocomplete (Mới) mà bạn cần.

Triển khai theo chương 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 Thông tin chi tiết về địa điểm (Mới) cho kết quả dự đoán đã chọn, hãy thêm các tham số sau:

Mã địa điểm trong phản hồi của tính năng Tự động hoàn thành (Mới)
Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
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 Autocomplete (Mới). Mức độ 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 đang nhập, vị trí sử dụng ứng dụng và việc bạn đã triển khai các phương pháp hay nhất để tối ưu hoá hiệu suất hay chưa.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự trung bình mà người dùng nhập trước khi chọn một đề xuất của tính năng 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 tối đa 4 yêu cầu 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 kết quả dự đoán được chọn về địa điểm.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ. 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 ý được chọn cho địa điểm sẽ ít tốn kém hơn so với chi phí Autocomplete (Mới) cho mỗi phiên.¹

Hãy cân nhắ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 thông tin dự đoán mà họ đang tìm kiếm chỉ trong vài ký tự.

Không

Sử dụng tính năng Tự động hoàn thành dựa trên phiên (Mới) với tính năng Chi tiết về địa điểm (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 kết quả dự đoán của tính năng Tự động hoàn thành (Mới) vượt quá chi phí của mức giá theo phiên, nên việc triển khai tính năng Tự động hoàn thành (Mới) của bạn phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Chi tiết về địa điểm (Mới) được liên kết 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 tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm cả yêu cầu Autocomplete (Mới) và yêu cầu Place Details (New) đối với cụm từ dự đoán đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu những trường cần thiết.

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

Cân nhắc trì hoãn các yêu cầu về tính năng 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 về tính năng 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 đưa ra ít yêu cầu hơn. Ví dụ: việc đưa ra 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ừ dự đoán mà bạn đưa ra 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 bạn giảm số yêu cầu trung bình theo chương trình xuống dưới 4, thì bạn có thể làm theo hướng dẫn về việc triển khai Tính năng tự động hoàn thành hiệu suất cao (Mới) bằng Geocoding API. Xin lưu ý rằng người dùng có thể coi việc trì hoãn các yêu cầu là độ trễ. Người dùng có thể mong đợi nhìn thấy các dự đoán với 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 thông tin dự đoán mà họ đang tìm kiếm chỉ bằng ít ký tự hơn.

Để biết chi phí, hãy xem Danh sách giá của Nền tảng Google Maps.

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

Các nguyên tắc sau đây mô tả những 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 quy định hạn chế về quốc gia, ưu tiên vị trí và (đối với các cách triển khai có lập trình) lựa chọn ưu tiên ngôn ngữ vào chế độ triển khai Autocomplete (New) (Tự động hoàn thành (Mới)). Không cần lựa chọn ưu tiên về ngôn ngữ đối với các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ 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ể điều chỉnh vị trí theo khung hiển thị 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 ý của tính năng Tự động hoàn thành (Mới), thường là do 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 nội dung đầ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 chỉ muốn người dùng 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 một lệnh gọi đến Geocoding API.
- Nếu bạn muốn người dùng 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 Chi tiết về địa điểm (Mới). Nếu chỉ muốn nhận kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
Các trường hợp khác mà bạn nên quay lại dùng Geocoding API bao gồm:
- Người dùng nhập địa chỉ của một phần trong cơ sở, chẳng hạn như địa chỉ của các căn hộ hoặc đơn vị cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" của Cộng hoà Séc sẽ trả về một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành (Mới).
- Người dùng nhập địa chỉ có tiền tố đ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 ở Hawaii.

Thiên vị về vị trí

Điều chỉnh kết quả cho một khu vực cụ thể bằng cách truyền tham số location và tham số radius. Thao tác 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ả bên 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ố components để lọc kết quả và chỉ cho thấy những địa điểm trong một quốc gia cụ thể.

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

Kết quả về cơ sở 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 rộng. Nếu muốn các cơ sở xuất hiện trong kết quả hỗn hợp về cơ sở/mã địa lý, bạn có thể chỉ định bán kính nhỏ hơn. Hoặc sử dụng types=establishment để chỉ giới hạn kết quả ở các cơ sở.

Hạn chế về vị trí

Hạn chế kết quả ở một khu vực cụ thể bằng cách truyền tham số locationRestriction.

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

API Dữ liệu tự động hoàn thành địa điểm Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Yêu cầu tự động hoàn thành

Hạn chế cụm từ gợi ý của tính năng Tự động hoàn thành

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

Mã thông báo phiên

Đề xuất về mã thông báo phiên:

Ví dụ:

Mã ví dụ hoàn chỉnh

Cụm từ gợi ý của tính năng tự động hoàn thành địa điểm

TypeScript

JavaScript

CSS

HTML

Dùng thử mẫu

Tính năng tự động hoàn thành địa điểm nhập trước với các phiên

TypeScript

JavaScript

CSS

HTML

Dùng thử mẫu

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

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í nâng cao

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

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

Có

Không

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

Thiên vị về vị trí

Hạn chế về vị trí

API Dữ liệu tự động hoàn thành địa điểm