Sử dụng Bộ công cụ giao diện người dùng của Places cho người dùng hiện tại của Places API

Mục tiêu: Thay thế phương thức triển khai Places API hoặc Place Class bằng Places UI Kit.

Ai nên đọc hướng dẫn này?

Nhà phát triển:

  • Gửi yêu cầu HTTP đến các điểm cuối của Places API (Mới hoặc Cũ).
  • Sử dụng Lớp địa điểm trong Maps JavaScript API.
  • Xử lý phản hồi API để hiển thị thông tin về địa điểm trong giao diện người dùng của ứng dụng web.

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

Bật Places UI Kit trên Dự án Google Cloud của bạn. Bạn có thể tiếp tục sử dụng khoá API hiện có hoặc tạo một khoá mới cho Places UI Kit. Hãy xem phần Sử dụng khoá API để biết thêm thông tin, bao gồm cả cách hạn chế một khoá.

Cập nhật cách tải Maps JavaScript API

Places UI Kit yêu cầu phương thức Nhập thư viện động để tải Maps JavaScript API. Nếu bạn đang sử dụng thẻ tải tập lệnh trực tiếp, thì bạn phải cập nhật thẻ này.

Sau khi bạn cập nhật tập lệnh tải cho Maps JavaScript API, hãy nhập các thư viện bắt buộc để sử dụng Places UI Kit.

Triển khai phần tử Chi tiết về địa điểm

Phần tử Chi tiết về địa điểm và Phần tử Chi tiết về địa điểm ở dạng thu gọn là các phần tử HTML hiển thị thông tin chi tiết về một địa điểm.

Triển khai hiện tại

  • Bạn thực hiện lệnh gọi Chi tiết về địa điểm bằng cách sử dụng yêu cầu HTTP hoặc sử dụng Lớp địa điểm của JavaScript API.
  • Bạn phân tích cú pháp phản hồi API và hiển thị thông tin chi tiết về địa điểm bằng HTML và CSS.

Di chuyển sang phần tử Chi tiết về địa điểm

Sửa đổi cấu trúc HTML

Xác định vùng chứa HTML nơi thông tin chi tiết về địa điểm được hiển thị. Thay thế các phần tử HTML tuỳ chỉnh (div, khoảng cho tên, địa chỉ, ảnh, v.v.) bằng HTML của Phần tử thông tin chi tiết về địa điểm.

Có hai phần tử để bạn chọn:

  • Phần tử thu gọn của Thông tin chi tiết về địa điểm
  • Phần tử Chi tiết về địa điểm

Để biết thêm thông tin về việc nên sử dụng thành phần nào, hãy xem Phần tử Thông tin chi tiết về địa điểm.

HTML hiện tại của bạn có thể có dạng như sau.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Ví dụ về HTML mới, nêu rõ nội dung cần hiển thị:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Điều chỉnh logic JavaScript

Logic hiện có

Logic hiện tại của bạn có thể liên quan đến:

  • Truy xuất Mã địa điểm.
  • Sử dụng PlacesService().getDetails() hoặc thực hiện một lệnh gọi dịch vụ web.
  • Chỉ định một mảng trường (đối với API JS) hoặc FieldMask (đối với dịch vụ web) để yêu cầu dữ liệu cụ thể.
  • Trong giải pháp gọi lại, hãy chọn các phần tử HTML theo cách thủ công và điền dữ liệu đã nhận vào các phần tử đó.

Sau đây là ví dụ về cách bạn có thể triển khai Thông tin chi tiết về địa điểm:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
Logic mới

Logic mới của bạn sẽ bao gồm:

  • Truy xuất Mã địa điểm hoặc Đối tượng địa điểm.
  • Tạo một tham chiếu đến phần tử <gmp-place-details-place-request>.
  • Truyền Mã địa điểm hoặc Đối tượng địa điểm vào thuộc tính địa điểm trên phần tử <gmp-place-details-place-request>.

Sau đây là ví dụ về cách bạn có thể triển khai bộ công cụ giao diện người dùng Chi tiết về địa điểm trong logic JavaScript. Lấy thông tin tham chiếu đến Phần tử thông tin chi tiết về địa điểm. Nếu có, hãy lấy một tham chiếu đến phần tử Yêu cầu về địa điểm trong phần Thông tin chi tiết về địa điểm và đặt thuộc tính địa điểm bằng cách sử dụng mã địa điểm. Trong ví dụ về mã HTML ở trên, kiểu Phần tử thông tin chi tiết về địa điểm được đặt thành display: none. Thông tin này được cập nhật thành display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Phần tử Tìm kiếm địa điểm là một phần tử HTML hiển thị kết quả của một cụm từ tìm kiếm địa điểm trong danh sách.

  • Bạn thực hiện một yêu cầu Tìm kiếm văn bản hoặc Tìm kiếm lân cận bằng yêu cầu HTTP, hoặc sử dụng Lớp địa điểm của JavaScript API.
  • Bạn chỉ định các tham số truy vấn, hạn chế hoặc thiên vị về vị trí, các loại và các trường được yêu cầu bằng FieldMask.
  • Bạn phân tích cú pháp phản hồi API, lặp lại mảng địa điểm và tạo các mục trong danh sách HTML theo cách thủ công.

Sửa đổi cấu trúc HTML

Xác định vùng chứa HTML nơi bạn hiển thị danh sách địa điểm. Thay thế các phần tử HTML tuỳ chỉnh (div, khoảng cho tên, địa chỉ, v.v.) bằng phần tử HTML Place Search Element.

HTML hiện có của bạn có thể có dạng như sau:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

Place Search Element được triển khai bằng thành phần <gmp-place-search>. Để định cấu hình loại tìm kiếm, hãy thêm một trong các thành phần cấu hình có khe cắm sau đây vào bên trong:

  • <gmp-place-text-search-request> để tìm kiếm bằng văn bản.
  • <gmp-place-nearby-search-request> để tìm kiếm lân cận.

Để xác định cách hiển thị kết quả, bạn có thể sử dụng lối tắt <gmp-place-all-content> hoặc cung cấp bộ thành phần trình bày riêng lẻ của riêng bạn. Bạn có thể đặt trực tiếp các thuộc tính chính như selectable (để cho phép nhấp vào các mục trong danh sách) và orientation (đối với bố cục ngang hoặc dọc) trên thành phần mẹ.

Ví dụ về Nearby Search
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
Ví dụ về tính năng Tìm kiếm bằng văn bản
<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Điều chỉnh logic JavaScript

Trong JavaScript, hãy lấy thông tin tham chiếu đến thành phần bộ điều khiển tìm kiếm bằng cách sử dụng document.querySelector(). Tuỳ thuộc vào chế độ thiết lập, đây sẽ là phần tử <gmp-place-text-search-request> hoặc <gmp-place-nearby-search-request>.

Tiếp theo, hãy đặt các thuộc tính trên bộ điều khiển này để xác định nội dung tìm kiếm của bạn. Các thuộc tính bắt buộc phụ thuộc vào loại tìm kiếm mà bạn đang thực hiện.

Đối với tính năng Tìm kiếm bằng văn bản (<gmp-place-text-search-request>), thuộc tính chính là textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Đối với Nearby Search (<gmp-place-nearby-search-request>), bạn phải xác định khu vực tìm kiếm bằng cách sử dụng locationRestriction. Sau đó, bạn có thể dùng biểu tượng includedTypes để lọc ra những loại địa điểm cụ thể trong khu vực đó:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Thành phần <gmp-place-search> mẹ sẽ tự động bắt đầu một lượt tìm kiếm mới ngay khi các thuộc tính bắt buộc của bộ điều khiển được đặt.

  • Đối với một Tìm kiếm văn bản, quá trình tìm kiếm sẽ chạy ngay khi bạn chỉ định một giá trị cho textQuery.
  • Đối với một cụm từ tìm kiếm lân cận, cụm từ tìm kiếm sẽ chạy sau khi bạn cung cấp một locationRestriction hợp lệ.

Triển khai phần tử cơ bản của tính năng Place Autocomplete

Đối với những nhà phát triển cần có trải nghiệm tìm kiếm mà không có giao diện người dùng do Phần tử tìm kiếm địa điểm cung cấp, bạn có thể sử dụng Phần tử Tính năng tự động hoàn thành cơ bản cho địa điểm.

Phần tử này rất phù hợp để tạo một trường nhập nội dung tìm kiếm trong khi vẫn duy trì toàn quyền kiểm soát cách kết quả hiển thị trong giao diện người dùng tuỳ chỉnh của bạn. Trách nhiệm duy nhất của Phần tử tự động hoàn thành là cung cấp thông tin dự đoán về địa điểm khi người dùng nhập và hiển thị theo chương trình một Mã địa điểm cho địa điểm đã chọn.

Bản thân công cụ này không hiển thị bất kỳ thông tin chi tiết nào hoặc cung cấp bất kỳ thông tin nào khác có thể truy cập theo phương thức lập trình.

Triển khai hiện tại

Logic hiện tại của bạn có thể liên quan đến:

  • Kết xuất một trường nhập văn bản trên trang của bạn, trường này sẽ gọi tính năng Tự động hoàn thành địa điểm khi người dùng nhập, hiển thị kết quả.
  • Sử dụng mã địa điểm của địa điểm mà người dùng đã chọn để tìm nạp thêm thông tin chi tiết, ví dụ: sử dụng Place Details API.
  • Hiển thị thông tin chi tiết về địa điểm đã chọn.

Di chuyển sang phần tử Place Autocomplete

Sửa đổi cấu trúc HTML

Xác định và xoá phần tử HTML mà bạn đính kèm tiện ích Tự động hoàn thành. Có thể là đang sử dụng một trường nhập HTML tiêu chuẩn.

<input id="pac-input" type="text" placeholder="Search for a location" />

Ví dụ về HTML mới, sử dụng phương pháp thành phần web để khởi động một phần tử Cơ bản về tính năng tự động hoàn thành địa điểm trên trang của bạn.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Điều chỉnh logic JavaScript

Logic JavaScript của bạn có thể liên quan đến việc tạo tiện ích Autocomplete được đính kèm vào một phần tử HTML input. Sau đó, tiện ích này sẽ theo dõi sự kiện place_changed, kích hoạt một thao tác bằng dữ liệu được trả về.

Ví dụ về mã JavaScript hiện có cần xoá:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Logic JavaScript mới của bạn sẽ nhận được một tham chiếu đến Basic Place Autocomplete Element và theo dõi các sự kiện gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Khi bạn chọn một địa điểm trong trình đơn thả xuống Tự động hoàn thành, sự kiện gmp-select sẽ kích hoạt. Bạn có thể truy xuất Mã địa điểm của địa điểm đã chọn từ đối tượng event. Sau đó, bạn có thể dùng Place ID để khởi chạy một phiên bản của Phần tử Thông tin chi tiết về địa điểm, nhằm hiển thị thông tin chi tiết về địa điểm đã chọn.

Tuỳ chỉnh tay cầm

Tuỳ chỉnh phần tử Thông tin chi tiết về địa điểm

Hướng

Bạn có thể hiển thị Phần tử thông tin chi tiết về địa điểm ở cả hướng ngang và dọc. Sử dụng thuộc tính orientation trên gmp-place-details-compact để chọn giữa hướng dọc và hướng ngang. Ví dụ:

<gmp-place-details-compact orientation="vertical">

Chọn các trường để hiển thị

Sử dụng các phần tử nội dung để chỉ định nội dung sẽ được hiển thị trong Phần tử chi tiết về địa điểm. Ví dụ: việc loại trừ phần tử nội dung <gmp-place-type> sẽ ngăn Phần tử chi tiết về địa điểm hiển thị Loại địa điểm của địa điểm đã chọn. Để biết danh sách đầy đủ các phần tử nội dung, hãy xem tài liệu tham khảo PlaceContentConfigElement.

Việc thêm hoặc xoá các trường khỏi Phần tử thông tin chi tiết về địa điểm không làm thay đổi chi phí hiển thị phần tử trên trang.

Đặt kiểu CSS

Bạn có thể dùng các thuộc tính CSS tuỳ chỉnh để định cấu hình màu sắc và phông chữ của phần tử. Ví dụ: để đặt nền của phần tử thành màu xanh lục, hãy đặt thuộc tính CSS sau:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Hãy xem tài liệu tham khảo về PlaceDetailsCompactElement để biết thêm thông tin chi tiết.

Tuỳ chỉnh phần tử Tìm kiếm địa điểm

Hướng

Bạn có thể hiển thị Phần tử tìm kiếm địa điểm theo cả hướng ngang và dọc. Sử dụng thuộc tính orientation trên <gmp-place-search> để chọn giữa hướng dọc và hướng ngang. Ví dụ:

<gmp-place-search orientation="horizontal" selectable>

Chọn các trường để hiển thị

Sử dụng các phần tử nội dung để chỉ định nội dung sẽ được hiển thị trong Phần tử tìm kiếm địa điểm. Bạn có thể dùng phần tử <gmp-place-all-content> để hiển thị tất cả nội dung hoặc dùng một lựa chọn thẻ html để định cấu hình nội dung được kết xuất.

Việc thêm <gmp-place-address> vào <gmp-place-content-config> sẽ chỉ hiển thị địa chỉ của từng địa điểm, ví dụ:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Tuỳ chỉnh cơ bản cho phần tử Place Autocomplete

Đặt kiểu CSS

Bạn có thể dùng các thuộc tính CSS tuỳ chỉnh để tuỳ chỉnh giao diện của phần tử Tự động hoàn thành. Ví dụ: để đặt màu nền thành màu tím nhạt, bạn sẽ đặt thuộc tính background-color trên phần tử.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Hãy xem tài liệu tham khảo BasicPlaceAutocompleteElement để biết thêm thông tin chi tiết.

Xử lý sự kiện và dữ liệu

Các phần tử trong Places UI Kit là những thành phần tương tác cho phép bạn theo dõi các sự kiện và truy xuất dữ liệu theo phương thức lập trình.

Theo dõi các sự kiện

Bạn có thể thêm trình nghe sự kiện vào các phần tử để kích hoạt các thao tác dựa trên hoạt động tương tác của người dùng hoặc trạng thái của phần tử.

Sự kiện lựa chọn

  • gmp-select: Sự kiện này sẽ kích hoạt khi người dùng chọn một mục.
    • Trên Phần tử tìm kiếm địa điểm, sự kiện này được kích hoạt khi người dùng nhấp vào một địa điểm trong danh sách kết quả.
    • Trên Basic Place Autocomplete Element (Phần tử cơ bản của tính năng tự động hoàn thành địa điểm), sự kiện này sẽ kích hoạt khi người dùng nhấp vào một kết quả dự đoán trong danh sách thả xuống.

Sự kiện thông thường

Các phần tử Tìm kiếm địa điểm, Thông tin chi tiết về địa điểm và Place Autocomplete cơ bản đều hỗ trợ các sự kiện sau:

  • gmp-load: Kích hoạt khi phần tử và nội dung của phần tử đó đã tải và kết xuất xong.
  • gmp-requesterror: Kích hoạt khi yêu cầu đến máy chủ không thành công, chẳng hạn như do khoá API không hợp lệ.

Truy cập vào dữ liệu phần tử theo phương thức lập trình

Bạn có thể truy xuất dữ liệu cụ thể từ các phần tử theo cách lập trình sau khi người dùng tương tác hoặc tải các phần tử đó.

  • Đối với Phần tử tìm kiếm địa điểm và Phần tử thông tin chi tiết về địa điểm, bạn có thể truy xuất thông tin sau:
    • Mã địa điểm
    • Vị trí (Vĩ độ và kinh độ)
    • Khung nhìn
  • Đối với Phần tử cơ bản của tính năng tự động hoàn thành tên địa điểm, bạn có thể truy xuất thông tin sau:
    • Mã địa điểm

Bạn không thể truy cập theo phương thức lập trình vào tất cả dữ liệu khác có trong các phần tử.

Để xem các ví dụ chi tiết hơn, hãy xem tài liệu riêng cho Phần tử Tìm kiếm địa điểm, Phần tử Chi tiết về địa điểm và Phần tử Cơ bản về tính năng tự động hoàn thành địa điểm.

Kiểm thử và tinh chỉnh

Sau khi bạn tích hợp(các) phần tử Places UI Kit, việc kiểm thử là rất quan trọng để có được quá trình chuyển đổi suôn sẻ và trải nghiệm tích cực cho người dùng. Quy trình kiểm thử của bạn phải bao gồm một số khía cạnh chính, giải quyết tất cả các phần tử mà bạn đã triển khai: phần tử Chi tiết về địa điểm, Tìm kiếm địa điểm và Place Autocomplete cơ bản.

Phần tử thông tin chi tiết về địa điểm

Đối với Phần tử chi tiết về địa điểm, hãy bắt đầu bằng cách xác minh rằng thông tin chi tiết được hiển thị chính xác cho nhiều địa điểm. Thử nghiệm bằng cách truyền nhiều mã địa điểm đến thuộc tính .place của phần tử <gmp-place-details-place-request>. Sử dụng mã nhận dạng đại diện cho nhiều loại cơ sở (doanh nghiệp có dữ liệu phong phú, địa điểm yêu thích, địa chỉ cơ bản) và địa điểm ở nhiều khu vực hoặc ngôn ngữ. Hãy đặc biệt chú ý đến định dạng, bố cục và sự hiện diện của nội dung.

Phần tử tìm kiếm địa điểm

Nếu bạn đã triển khai Phần tử tìm kiếm địa điểm, hãy xác minh quá trình hiển thị và hành vi của phần tử này trong các trường hợp tìm kiếm khác nhau.

  • Đối với tính năng Tìm kiếm bằng văn bản, hãy kiểm thử bằng cách đặt thuộc tính textQuery trên phần tử <gmp-place-text-search-request> với nhiều dữ liệu đầu vào: cụm từ tìm kiếm chung chung, địa chỉ cụ thể và cụm từ tìm kiếm có thiên kiến về vị trí.
  • Đối với một Tìm kiếm lân cận, hãy kiểm thử bằng cách đặt các thuộc tính locationRestriction và includedTypes trên phần tử <gmp-place-nearby-search-request>. Sử dụng nhiều kích thước vị trí và bộ lọc loại.

Xác nhận rằng danh sách này có kết quả phù hợp và sự kiện gmp-select được kích hoạt chính xác khi bạn chọn.

Phần tử cơ bản của tính năng Tự động hoàn thành địa điểm

Đối với Phần tử cơ bản của tính năng Tự động hoàn thành tên địa điểm, hãy tập trung kiểm thử vào hoạt động tương tác của người dùng và dữ liệu được truyền qua sự kiện lựa chọn. Xác nhận rằng sự kiện gmp-select sẽ kích hoạt một cách đáng tin cậy khi người dùng nhấp vào một cụm từ dự đoán. Xác minh rằng đối tượng event.place trong trình xử lý sự kiện chứa một Mã địa điểm hợp lệ.

Quan trọng nhất là hãy kiểm thử quy trình từ đầu đến cuối: chọn một địa điểm trong trình đơn thả xuống Tự động hoàn thành và xác minh rằng bạn có thể sử dụng Mã địa điểm của địa điểm đó để điền sẵn một phần tử khác, chẳng hạn như Phần tử thông tin chi tiết về địa điểm.

Xử lý lỗi

Việc kiểm thử nghiêm ngặt quy trình xử lý lỗi là điều cần thiết trên tất cả các thành phần. Mô phỏng việc truyền Mã địa điểm không hợp lệ hoặc không tồn tại đến Phần tử chi tiết về địa điểm hoặc sử dụng các tham số tìm kiếm không hợp lệ cho Phần tử tìm kiếm địa điểm. Kích hoạt sự kiện gmp-requesterror bằng cách mô phỏng các vấn đề về mạng hoặc sử dụng khoá API không hợp lệ để đảm bảo ứng dụng của bạn xử lý sự kiện này một cách suôn sẻ. Triển khai thông báo lỗi và nhật ký thân thiện với người dùng để ngăn chặn giao diện người dùng bị hỏng hoặc gây nhầm lẫn.