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 cách triển khai Places API hoặc Lớp địa điểm 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 bằng Places API và muốn cập nhật mã để sử dụng Places UI Kit. Bạn sẽ thấy 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 trên đám mây của 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 bài viết Sử dụng khoá API để biết thêm thông tin, bao gồm cả việc hạn chế 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 đang sử dụng thẻ tải tập lệnh trực tiếp, 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 API JavaScript của Maps, hãy nhập các thư viện bắt buộc để sử dụng Places UI Kit.

Triển khai Thành phần Place Details

Phần tử Place Details và Phần tử Place Details Compact 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 địa điểm API JavaScript.
  • 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 Thành phần Place Details

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

Xác định vùng chứa HTML nơi hiển thị Place Details. 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ó hai phần tử để bạn chọn:

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

Để biết thêm thông tin về thành phần nên sử dụng, hãy xem bài viết Thành phần Chi tiết đị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 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 lệnh 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 được vào các phần tử đó.

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ẽ bao gồm:

  • 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 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ộ giao diện người dùng Chi tiết địa điểm trong logic JavaScript. Lấy thông tin tham chiếu đến Phần tử chi tiết địa điểm. Nếu có, hãy tham chiếu đến phần tử Place Details Place Request và đặt thuộc tính địa điểm bằng Mã địa điểm. Trong mã HTML ví dụ ở trên, kiểu của Thành phần Chi tiết đị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ả tìm kiếm địa điểm trong một 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 API JavaScript.
  • Bạn chỉ định các tham số truy vấn, quy tắc hạn chế hoặc thiên vị về 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 của bạn. 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 của Phần tử Tìm kiếm địa điểm.

HTML hiện tại 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>

Thành phần Tìm kiếm địa điểm đượ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 sau đây vào bên trong:

  • <gmp-place-text-search-request> cho một yêu cầu Tìm kiếm văn bản.
  • <gmp-place-nearby-search-request> cho một yêu cầu Nearby Search.

Để 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 một 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 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) ngay 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 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 tham chiếu đến thành phần trình điều khiển tìm kiếm bằng cách sử dụ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 trình đ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 yêu cầu 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 ra 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 trình điều khiển được đặt.

  • Đối với tính năng 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 tính năng Nearby Search, quá trình tìm kiếm sẽ chạy sau khi bạn cung cấp 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 cần có trải nghiệm tìm kiếm mà không cần giao diện người dùng của Thành phần tìm kiếm địa điểm, chúng tôi cung cấp Thành phần Tự động hoàn thành địa điểm cơ bản.

Phần tử này phù hợp để tạo trường nhập dữ liệu tìm kiếm, đồng thời 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. Trách nhiệm duy nhất của Thành phần 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ị Mã địa điểm cho địa điểm đã chọn theo phương thức lập trình.

Bản thân nó 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.

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

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

  • Hiển thị 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 mà người dùng chọn để tìm nạp thêm thông tin chi tiết, chẳng hạn như sử dụng API Chi tiết địa điểm.
  • Hiển thị thông tin chi tiết về địa điểm đã chọn.

Di chuyển sang Thành phần 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ể trường này đ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 động một phần tử Place Autocomplete 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 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 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ẽ nhận được thông tin tham chiếu đến Phần tử tự động hoàn thành địa điểm 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 của tính nă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 Mã địa điểm để khởi chạy một thực thể của Thành phần Chi tiết địa điểm, nhằm hiển thị thông tin chi tiết về địa điểm đã chọn.

Tuỳ chỉnh tên người dùng

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

Hướng

Bạn có thể hiển thị Thành phần 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 chiều dọc và chiều ngang. Ví dụ:

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

Chọn các trường cần 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 Thành phần Chi tiết đị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 địa điểm 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 Thành phần Place Details không làm thay đổi chi phí hiển thị thành phần đó 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 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 thành phần 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 chiều dọc và chiều ngang. Ví dụ:

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

Chọn các trường cần 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ể sử dụng phần tử <gmp-place-all-content> để hiển thị tất cả nội dung hoặc có thể sử dụng một số thẻ HTML để định cấu hình nội dung được kết xuất.

Nếu bạn đưa <gmp-place-address> vào <gmp-place-content-config>, thì hệ thống 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 Thành phần Place Autocomplete

Đặ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;
}

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

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

Các thành phần của 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.

Lắng nghe 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 hành động 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 được kích hoạt khi người dùng đưa ra lựa chọn.
    • Trên Thành phần 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 cụm từ gợi ý trong danh sách thả xuống.

Sự kiện phổ biến

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: Được 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: Được kích hoạt khi yêu cầu đế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 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 phương pháp lập trình sau khi các phần tử đó được tương tác hoặc tải.

  • Đối với Thành phần tìm kiếm địa điểm và Thành phần 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ử Place Autocomplete cơ bản, bạn có thể truy xuất những thông tin sau:
    • Mã địa điểm

Tất cả dữ liệu khác có trong các phần tử đều không thể truy cập được theo phương thức lập trình.

Để biết thêm ví dụ chi tiết, hãy xem tài liệu riêng về 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ử của Places UI Kit, việc kiểm thử là rất quan trọng để đảm bảo 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: Place Details, Tìm kiếm địa điểm và Place Autocomplete cơ bản.

Thành phần Chi tiết địa điểm

Đối với Thành phần Place Details, 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 vào 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 đa dạng thức, đị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 chú ý đến định dạng, bố cục và sự hiện diện của nội dung.

Thành phần 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 hoạt động 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ính năng 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: cụm từ tìm kiếm rộng, địa chỉ cụ thể và cụm từ tìm kiếm có độ lệch vị trí.
  • Đối với tính năng 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 các bộ lọc loại và kích thước vị trí khác nhau.

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

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

Đối với Thành phần Place Autocomplete cơ bản, hãy tập trung thử nghiệm 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 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ừ gợi ý. 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 của tính nă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ử chi tiết địa điểm.

Xử lý lỗi

Việc kiểm thử nghiêm ngặt quy trình xử lý lỗi là rất cần thiết đối với 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 Place Details Element hoặc sử dụng 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 đó một cách linh hoạt. Triển khai thông báo lỗi và ghi nhật ký thân thiện với người dùng để tránh giao diện người dùng bị hỏng hoặc gây nhầm lẫn.