Mục tiêu: Thay thế cách triển khai API Địa điểm hoặc Lớp Địa điểm bằng Bộ công cụ giao diện người dùng Địa điểm.
Ai nên đọc hướng dẫn này?
Nhà phát triển:
- Tạo yêu cầu HTTP đến các điểm cuối của API Địa điểm (Mới hoặc Cũ).
- Sử dụng Lớp địa điểm trong API Maps JavaScript.
- 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 Bộ công cụ giao diện người dùng của Địa điểm 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 khoá mới cho Bộ công cụ giao diện người dùng của Địa điểm. 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ế khoá.
Cập nhật tính năng tải Maps JavaScript API
Bộ công cụ giao diện người dùng của Địa điểm yêu cầu phương thức Nhập thư viện động để tải API Maps JavaScript. Nếu bạn đ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 Maps JavaScript, hãy nhập các thư viện cần thiết để sử dụng Bộ giao diện người dùng của Địa điểm.
Triển khai phần tử Chi tiết địa điểm
Cách triển khai hiện tại
- Bạn thực hiện lệnh gọi Thông tin chi tiết về địa điểm 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 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 địa điểm
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 Phần tử thông tin chi tiết về địa điểm.
Bạn có thể chọn một trong hai phần tử sau:
- Phần tử thu gọn Place Details
- Phần tử Thông tin chi tiết về địa điểm
Để biết thêm thông tin về phần tử nào nên sử dụng, hãy xem phần Phần tử Thông tin chi tiết về địa điểm.
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 (đố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 độ phân giải 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 vào các phần tử đó.
Sau đây là ví dụ về cách bạn có thể triển khai Chi tiết đị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 tham chiếu đến phần tử
<gmp-place-details-place-request>. - Truyền mã nhận dạng đị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 bộ công cụ giao diện người dùng Thông tin chi tiết về địa điểm trong logic JavaScript. Tạo tham chiếu đến Phần tử thông tin chi tiết về địa điểm. Nếu có, hãy tham chiếu đến phần tử Yêu cầu địa điểm thông tin chi tiết về địa điểm và đặt thuộc tính địa điểm bằng Mã địa điểm. Trong mã HTML mẫu ở trên, kiểu Phần tử thông tin chi tiết về địa điểm được đặt thành display: none. 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);
Triển khai phần tử Tìm kiếm địa điểm
Cách triển khai hiện tại
- Bạn thực hiện Tìm kiếm bằng 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 API JavaScript.
- Bạn chỉ định các tham số truy vấn, giới hạn hoặc thiên vị về vị trí, loại và các trường được yêu cầu bằng cách sử dụng FieldMask.
- Bạn phân tích cú pháp phản hồi API, lặp lại qua mảng địa điểm và tạo các mục danh sách HTML theo cách thủ công.
Di chuyển sang phần tử Tìm kiếm địa điểm
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 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>
Phần tử Tìm kiếm địa điểm sử dụng thẻ HTML <gmp-place-list>. HTML mới của bạn sẽ có dạng như sau. Thêm thuộc tính selectable nếu bạn muốn người dùng có thể nhấp vào các mục trong danh sách.
<gmp-place-list id="myPlaceListComponent" selectable></gmp-place-list>
Điều chỉnh logic JavaScript
Tạo tham chiếu đến phần tử DOM <gmp-place-list>.
Đối với chức năng Tìm kiếm văn bản: Sử dụng configureFromSearchByTextRequest(requestOptions).
const placeListComp = document.getElementById('myPlaceListComponent');
try {
await placeListComp.configureFromSearchByTextRequest({
textQuery: 'restaurants in Sydney',
// locationRestriction: map.getBounds(), // Optional
// includedType: 'restaurant' // Optional
});
} catch (error) {
console.error('UI Kit Place List (Text Search) Error:', error);
}
Đối với chức năng Tìm kiếm lân cận: Sử dụng configureFromSearchNearbyRequest(requestOptions):
const placeListComp = document.getElementById('myPlaceListComponent');
if (placeListComp) {
try {
await placeListComp.configureFromSearchNearbyRequest({
locationRestriction: { circle: { center: { latitude: ..., longitude: ... }, radius: 5000 } },
includedPrimaryTypes: ['cafe', 'bakery'] // Example
});
} catch (error) {
console.error('UI Kit Place List (Nearby Search) Error:', error);
}
}
Sau khi yêu cầu tìm kiếm văn bản hoặc tìm kiếm lân cận hoàn tất, Phần tử tìm kiếm địa điểm sẽ tự động cập nhật giao diện người dùng bằng kết quả tìm kiếm.
Xử lý tuỳ chỉnh
Tuỳ chỉnh phần tử Thông tin chi tiết về địa điểm
Hướng
Phần tử Thông tin chi tiết về địa điểm có thể hiển thị 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à 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ẽ 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 sẽ 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;
}
Hãy xem tài liệu tham khảo về PlaceDetailsCompactElement để 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 trong Bộ công cụ giao diện người dùng của Địa điểm hiển thị một số sự kiện nhất định, chẳng hạn như sự kiện gmp-placeselect trên Thành phần tìm kiếm địa điểm, cho phép một hành động khi người dùng nhấp vào một kết quả địa điểm. Để biết thêm thông tin, hãy xem tài liệu về Phần tử tìm kiếm địa điểm và Phần tử thông tin chi tiết về địa điểm.
Khi tương tác theo phương thức lập trình 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ể yêu cầu một số dữ liệu, bao gồm:
- Mã địa điểm
- Vị trí (Vĩ độ và kinh độ)
- Khung nhìn
Bạn có thể xem ví dụ về cách thực hiện việc này trong tài liệu về Thành phần danh sách địa điểm.
Tất cả dữ liệu khác trong phần tử này đều ở chế độ chỉ có thể đọc.
Kiểm thử và tinh chỉnh
Sau khi bạn tích hợp Phần tử thông tin chi tiết về địa điểm hoặc Phần tử tìm kiếm địa điểm, việc kiểm thử là rất quan trọng để quá trình chuyển đổi diễn ra suôn sẻ và người dùng có trải nghiệm tích cực. 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 cả hai thành phần nếu bạn đã triển khai các thành phần đó.
Đố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 về địa điểm được hiển thị chính xác cho nhiều địa điểm. Việc này bao gồm việc thử nghiệm với nhiều mã địa điểm đại diện cho nhiều loại cơ sở (doanh nghiệp có dữ liệu đa dạng, đ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ữ (nếu có liên quan). Hãy chú ý đến định dạng, bố cục và sự hiện diện của các thành phần giao diện người dùng dự kiến trong PlaceDetailsElement.
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 kết xuất và hành vi của phần tử đó trong nhiều tình huống tìm kiếm. Kiểm thử cả hai phương thức configureFromSearchNearbyRequest và configureFromSearchByTextRequest nếu có. Sử dụng nhiều loại dữ liệu đầu vào cho nội dung tìm kiếm: cụm từ tìm kiếm chung, địa chỉ cụ thể, cụm từ tìm kiếm có nhiều định kiến hoặc quy định hạn chế về vị trí và nội dung tìm kiếm được lọc theo nhiều loại địa điểm. Xác nhận rằng danh sách sẽ điền sẵn các kết quả liên quan và số lượng kết quả có vẻ phù hợp với truy vấn. Kiểm tra cách trình bày trực quan của từng mục trong danh sách.
Việc kiểm thử nghiêm ngặt các trường hợp xử lý lỗi là điều cần thiết đối với cả hai 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 PlaceDetailsElement.configureFromPlace(). Đối với Phần tử tìm kiếm địa điểm, hãy kiểm thử bằng các tham số tìm kiếm không hợp lệ, sự cố mạng trong quá trình yêu cầu hoặc các trường hợp có thể trả về kết quả rỗng.
Mã JavaScript của bạn phải phát hiện lỗi do Bộ công cụ giao diện người dùng của Địa điểm gửi. Triển khai tính năng xử lý lỗi thân thiện với người dùng, chẳng hạn như hiển thị thông báo thông tin, ẩn các thành phần một cách linh hoạt hoặc ghi lại lỗi để ngăn giao diện người dùng bị hỏng hoặc gây nhầm lẫn.