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

Tìm hiểu cách di chuyển việc triển khai Places API hoặc Place Class hiện có sang các thành phần của Places UI Kit.

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

Hướng dẫn này dành cho những nhà phát triển đã triển khai Places API và muốn cập nhật mã để sử dụng Places UI Kit. Hướng dẫn này sẽ hữu ích nhất nếu bạ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 của 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. 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 bài viết Sử dụng khoá API để biết thêm thông tin, bao gồm cả cách hạn chế khoá.

Cập nhật quá trình 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 cập nhật tập lệnh tải cho Maps JavaScript API, nhập các thư viện bắt buộc để sử dụng Places UI Kit.

Triển khai phần tử Place Details

Phần tử Place Details Element và Place Details Compact Element là các phần tử HTML hiển thị thông tin chi tiết về một địa điểm.

Cách triển khai hiện tại

  • Bạn thực hiện lệnh gọi Place Details bằng yêu cầu HTTP hoặc sử dụng Lớp Place của JavaScript API.
  • Bạn phân tích cú pháp phản hồi của 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ử Place Details

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

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

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

  • Phần tử Place Details (gọn)
  • Phần tử Thông tin chi tiết về địa điểm

Để biết thêm thông tin về phần tử cần sử dụng, hãy xem bài viết Phần tử Place Details.

HTML hiện có 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 có 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 lệnh gọi dịch vụ web.
  • Chỉ định một mảng trường (cho JS API) hoặc FieldMask (cho 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 sẵn các phần tử đó bằng dữ liệu đã nhận.

Sau đây là ví dụ về cách bạn có thể triển khai Place Details:

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ẽ liên quan đến:

  • Truy xuất Mã địa điểm hoặc Đối tượng địa điểm của bạn.
  • 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 đến 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 Place Details UI kit trong logic JavaScript. Tạo một tham chiếu đến phần tử Place Details. Nếu phần tử này tồn tại, hãy tạo một tham chiếu đến phần tử Yêu cầu Place Details và đặt thuộc tính địa điểm bằng Mã địa điểm. Trong ví dụ về mã HTML ở trên, kiểu của phần tử Thông tin chi tiết về địa điểm được đặt thành display: none. Giá trị 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ả tìm kiếm địa điểm ở dạng danh sách.

  • Bạn thực hiện Tìm kiếm văn bản hoặc Nearby Search 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, quy tắc hạn chế hoặc độ lệch vị trí, 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 của API, lặp lại mảng địa điểm và tạo các mục 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, span cho tên, địa chỉ, v.v.) bằng phần tử HTML Tìm kiếm địa điểm.

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>

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

  • <gmp-place-text-search-request> cho Tìm kiếm văn bản.
  • <gmp-place-nearby-search-request> cho Nearby Search.

Để xác định cách hiển thị kết quả, bạn có thể sử dụng <gmp-place-all-content> lối tắt hoặc cung cấp tập hợp các 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 (cho 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ìm kiếm 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 tạo một tham chiếu đến thành phần bộ điều khiển tìm kiếm bằng document.querySelector(). Tuỳ thuộc vào cá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á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ìm kiếm 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 locationRestriction. Sau đó, bạn có thể sử dụng includedTypes để lọc các 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 Tìm kiếm văn bản, lượt tìm kiếm sẽ chạy ngay khi bạn gán một giá trị cho textQuery.
  • Đối với Nearby Search, lượ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ử Place Autocomplete cơ bản

Đối với những nhà phát triển yêu cầu 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ự động hoàn thành địa điểm cơ bản.

Phần tử này lý tưởng để tạo một trường nhập dữ liệu tìm kiếm trong khi vẫn duy trì quyền kiểm soát hoàn toàn đối với cách hiển thị kết quả trong giao diện người dùng tuỳ chỉnh. Phần tử Tự động hoàn thành chỉ có trách nhiệm cung cấp các dự đoán về địa điểm khi người dùng nhập và hiển thị theo lập trình Mã địa điểm cho địa điểm đã chọn.

Phần tử này không tự 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 lập trình.

Cách triển khai hiện tại

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

  • Hiển thị một trường nhập dữ liệu văn bản trên trang của bạn, trường này sẽ gọi Place Autocomplete 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 do người dùng chọn để tìm nạp thêm thông tin chi tiết, ví dụ: sử dụng Places 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. Phần tử này có thể đang sử dụng một trường nhập dữ liệu 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 chạy phần tử Tự động hoàn thành địa điểm cơ bản 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 Tự động hoàn thành được đính kèm vào 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 hành động bằng dữ liệu được trả về.

Ví dụ về 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ẽ tạo một tham chiếu đến phần tử Place Autocomplete cơ bản 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ể sử dụng Mã địa điểm để khởi động một thực thể 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.

Xử lý việc tuỳ chỉnh

Tuỳ chỉnh phần tử Place Details

Hướng

Bạn có thể hiển thị phần tử Place Details theo 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 cần hiển thị trong phần tử Thông tin 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ử Place Details hiển thị Loại địa điểm của địa điểm đã chọn. Để xem 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ử Place Details 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ể sử 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;
}

Xem tài liệu tham khảo cho 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 cần hiển thị trong phần tử Tìm kiếm địa điểm. Bạn có thể sử dụng phần tử <gmp-place-all-content> để hiển thị tất cả nội dung hoặc sử dụng một lựa chọn thẻ HTML để định cấu hình nội dung được hiển thị.

Việc đưa <gmp-place-address> vào <gmp-place-content-config> sẽ chỉ hiển thị địa chỉ cho 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 phần tử Place Autocomplete cơ bản

Đặt kiểu CSS

Bạn có thể sử 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;
}

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ử Places UI Kit là các 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 lập trình.

Theo dõi 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 hành động dựa trên lượt 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 được 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 phần tử Place Autocomplete cơ bản, sự kiện này được kích hoạt khi người dùng nhấp vào một 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, Place Details 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à hiển thị xong.
  • gmp-requesterror: Kích hoạt khi một yêu cầu gửi đến máy chủ không thành công, ví dụ: do khoá API không hợp lệ.

Truy cập dữ liệu phần tử theo lập trình

Bạn có thể truy xuất dữ liệu cụ thể theo lập trình từ các phần tử sau khi 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ử Place Details, 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ử Basic Place Autocomplete, bạn có thể truy xuất thông tin sau:
    • Mã địa điểm

Bạn không thể truy cập theo lập trình 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ử Place Details, và phần tử Place Autocomplete cơ bản.

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 để quá trình chuyển đổi diễn ra suôn sẻ và mang lại trải nghiệm tích cực cho người dùng. Quá 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ử Place Details, phần tử Tìm kiếm địa điểm và phần tử Basic Place Autocomplete.

Phần tử Place Details

Đối với phần tử Thông tin 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. Kiểm thử 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ã đại diện cho các loại cơ sở khác nhau (doanh nghiệp có dữ liệu đa dạng thức, địa điểm yêu thích, địa chỉ cơ bản) và địa điểm ở các khu vực hoặc ngôn ngữ khác nhau. Hãy 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 tình huống tìm kiếm khác nhau.

  • Đối với Tìm kiếm 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: truy vấn rộng , địa chỉ cụ thể và truy vấn có độ lệch vị trí.
  • Đối với Nearby Search, hãy kiểm thử bằng cách đặt thuộc tính locationRestriction và includedTypes trên phần tử <gmp-place-nearby-search-request>. Sử dụng các kích thước vị trí và bộ lọc loại khác nhau.

Xác nhận rằng danh sách điền sẵn kết quả có liên quan và sự kiện gmp-select kích hoạt chính xác khi bạn chọn.

Phần tử Place Autocomplete cơ bản

Đối với phần tử Place Autocomplete cơ bản, hãy tập trung kiểm thử vào lượt tương tác của người dùng và dữ liệu do sự kiện lựa chọn truyền. Xác nhận rằng sự kiện gmp-select kích hoạt một cách đáng tin cậy khi người dùng nhấp vào 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ã đị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 thành cô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ử Place Details.

Xử lý lỗi

Việc kiểm thử nghiêm ngặt quá 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ử Place Details 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 giao diện người dùng bị hỏng hoặc gây nhầm lẫn.