Khám phá địa điểm bằng PlaceSearchElement

Mục tiêu

Tìm hiểu cách tích hợp PlaceSearchElement với Google Maps để giúp người dùng tìm địa điểm bằng tính năng Nearby Search hoặc Tìm kiếm văn bản, từ đó nâng cao khả năng khám phá các địa điểm yêu thích. Sử dụng Phần tử thu gọn về Place Details để cung cấp thêm thông tin chi tiết về các địa điểm xuất hiện trong ứng dụng của bạn.

PlaceSearchElement là gì?

PlaceSearchElement là một phần của Places UI Kit trong Maps JavaScript API. Đây là một phần tử HTML hiển thị kết quả tìm kiếm địa điểm ngay trong định dạng danh sách trong ứng dụng của bạn. Phần tử này đơn giản hoá quy trình hiển thị các địa điểm tìm được bằng tính năng Tìm kiếm lân cận hoặc Tìm kiếm văn bản, mang đến trải nghiệm liền mạch cho người dùng khi khám phá địa điểm. Khi người dùng chọn một địa điểm trong danh sách, bạn có thể hiển thị thông tin chi tiết về địa điểm đó trên bản đồ, thường là bằng cách sử dụng Cửa sổ thông tin và Thành phần Chi tiết địa điểm.

Trực quan hoá việc khám phá địa điểm

Hình ảnh sau đây cho thấy một ví dụ về cách hoạt động của PlaceSearchElement. Ở bên trái, danh sách nhà hàng sẽ xuất hiện (PlaceSearchElement). Khi bạn chọn một nhà hàng, thông tin chi tiết về nhà hàng đó sẽ xuất hiện trong Cửa sổ thông tin trên bản đồ và bản đồ sẽ căn giữa vào vị trí của nhà hàng đó.

hình ảnh

Trường hợp sử dụng cho tính năng Khám phá địa điểm

Việc tích hợp PlaceSearchElement có thể cải thiện nhiều ứng dụng trong các ngành khác nhau:

  • Du lịch và lữ hành: Cho phép khách du lịch tìm kiếm các điểm tham quan, khách sạn hoặc các loại ẩm thực cụ thể trong một khu vực.
  • Bất động sản: Giúp người mua hoặc người thuê tiềm năng tìm thấy các trường học, siêu thị hoặc phương tiện công cộng gần đó.
  • Hậu cần và dịch vụ: Hỗ trợ người lái xe tìm trạm sạc xe điện, trạm xăng hoặc trung tâm dịch vụ cụ thể.

Quy trình giải pháp: Triển khai tính năng Khám phá địa điểm

Phần này hướng dẫn bạn cách tích hợp PlaceSearchElement để khám phá các địa điểm trên bản đồ, đồng thời cung cấp các đoạn mã để tương tác với Places UI Kit. Tìm hiểu cách khởi chạy bản đồ và triển khai cả tính năng Tìm kiếm lân cận và Tìm kiếm văn bản. Cuối cùng, hãy sử dụng phần tử Place Details để hiển thị thêm thông tin chi tiết về một địa điểm khi người dùng nhấp vào ghim của địa điểm đó trên bản đồ.

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

Bạn nên làm quen với tài liệu sau:

Bật Maps JavaScript API và Places UI Kit trong dự án của bạn.

Xác minh rằng bạn đã tải Maps JavaScript API và nhập các thư viện bắt buộc trước khi bắt đầu. Tài liệu này cũng giả định rằng bạn có kiến thức thực tế về phát triển web, bao gồm cả HTML, CSS và JavaScript.

Thêm bản đồ vào trang

Bước đầu tiên là thêm bản đồ vào trang của bạn. Bản đồ này sẽ được dùng để hiển thị kết quả của PlaceSearchElement dưới dạng ghim có thể chọn.

Có hai cách để thêm bản đồ vào một trang:

  1. Sử dụng thành phần web HTML gmp-map.
  2. Sử dụng JavaScript.

Các đoạn mã trên trang này được tạo bằng ánh xạ JavaScript.

Bản đồ có thể được căn giữa vào một vị trí mà bạn muốn người dùng tìm kiếm xung quanh, chẳng hạn như khách sạn, hoặc được khởi chạy để yêu cầu vị trí hiện tại của người dùng nhằm căn giữa bản đồ. Trong tài liệu này, chúng ta sẽ sử dụng một vị trí cố định để neo kết quả tìm kiếm.

Nếu bạn đang trực quan hoá các địa điểm gần một vị trí cố định, chẳng hạn như khách sạn, hãy đặt một điểm đánh dấu trên bản đồ để thể hiện địa điểm này. Ví dụ:

hình ảnh

Bản đồ được căn giữa ở San Francisco, với một ghim màu xanh dương để thể hiện địa điểm mà chúng ta đang tìm kiếm gần đó. Màu ghim đã được tuỳ chỉnh bằng cách sử dụng PinElement. Chế độ điều khiển Loại bản đồ đã bị ẩn khỏi giao diện người dùng.

Thiết lập PlaceSearchElement

Bây giờ, hãy thiết lập HTML và CSS để hiển thị PlaceSearchElement. Ví dụ này đặt phần tử nổi ở phía bên trái của bản đồ, nhưng bạn có thể thử các bố cục khác cho phù hợp với ứng dụng của mình.

PlaceSearchElement sử dụng phương pháp khai báo. Thay vì định cấu hình hoàn toàn bằng JavaScript, bạn có thể xác định loại tìm kiếm trực tiếp trong HTML bằng cách lồng một phần tử yêu cầu (chẳng hạn như <gmp-place-nearby-search-request>) vào bên trong thành phần <gmp-place-search> chính.

Trong mã HTML, hãy khởi tạo một phần tử <gmp-place-search>. Sử dụng thuộc tính selectable để bật sự kiện nhấp chuột trên kết quả. Bên trong phần tử đó, hãy thêm một <gmp-place-nearby-search-request> để chỉ định rằng phần tử này sẽ được dùng cho tính năng Nearby Search.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Để thực hiện tìm kiếm ban đầu và hiển thị kết quả, chúng ta sẽ sử dụng JavaScript để lấy thông tin tham chiếu đến phần tử yêu cầu lồng nhau và đặt các thuộc tính của phần tử đó. Khởi động một Circle để dùng làm locationRestriction, sử dụng vị trí điểm đánh dấu ở bước trước làm điểm trung tâm. Sau đó, hãy đặt các thuộc tính locationRestriction và includedPrimaryTypes trên phần tử yêu cầu để kích hoạt tính năng tìm kiếm.

Đoạn mã cho việc này như sau:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

Sau đây là ví dụ về giao diện của ứng dụng ở giai đoạn này:

hình ảnh

PlaceSearchElement cho phép hai lựa chọn tìm kiếm:

  • <gmp-place-nearby-search-request> – hiển thị kết quả tìm kiếm từ Nearby Search, sử dụng Loại địa điểm.
  • <gmp-place-text-search-request> – hiển thị kết quả tìm kiếm từ Tìm kiếm văn bản địa điểm, sử dụng dữ liệu đầu vào dạng văn bản tự do, chẳng hạn như "Sushi ở San Francisco".

Đây là các phần tử lồng nhau bên trong <gmp-place-search>. Sau đó, bạn kích hoạt các lượt tìm kiếm bằng cách đặt thuộc tính trên phần tử yêu cầu lồng nhau đó bằng JavaScript.

Phần này mô tả cách triển khai cả hai phương thức.

hình ảnh

Để cho phép người dùng thực hiện Nearby Search, trước tiên, bạn cần có một phần tử trên giao diện người dùng để họ chọn Loại địa điểm. Chọn phương thức lựa chọn phù hợp nhất với ứng dụng của bạn, ví dụ: danh sách thả xuống được điền sẵn một số loại địa điểm.

Bạn nên chọn một nhóm nhỏ các loại dữ liệu phù hợp với trường hợp sử dụng của mình. Ví dụ: nếu đang phát triển một ứng dụng để cho khách du lịch biết những địa điểm gần khách sạn, bạn có thể chọn: bakery, coffee_shop, museum, restaurant và tourist_attraction.

HTML của bạn phải chứa phần tử <gmp-place-search> có <gmp-place-nearby-search-request> lồng bên trong.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Tiếp theo, hãy tạo một trình nghe JavaScript cho sự kiện change trên bộ chọn loại địa điểm của bạn. Trình nghe này sẽ gọi một hàm cập nhật các thuộc tính của phần tử <gmp-place-nearby-search-request>, tự động kích hoạt một lượt tìm kiếm mới và cập nhật danh sách.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

searchCircle tương tự trong bước thiết lập được dùng cho locationRestriction. Thuộc tính includedPrimaryTypes được đặt thành giá trị từ lựa chọn của người dùng. maxResultCount không bắt buộc cũng được đặt để giới hạn số lượng kết quả.

Tìm kiếm văn bản

hình ảnh

Để bật tính năng tìm kiếm văn bản, bạn phải thay đổi cấu hình HTML. Thay vì yêu cầu Nearby Search, bạn lồng một phần tử <gmp-place-text-search-request>.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

Thêm một mục nhập văn bản và một nút tìm kiếm vào giao diện người dùng. Tạo trình nghe JavaScript cho sự kiện click của nút. Trình xử lý sự kiện sẽ lấy dữ liệu đầu vào của người dùng và cập nhật các thuộc tính của phần tử <gmp-place-text-search-request> để thực hiện tìm kiếm.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

Tại đây, chúng ta đặt thuộc tính textQuery bằng dữ liệu đầu vào của người dùng. Chúng tôi cũng cung cấp một locationBias sử dụng ranh giới bản đồ hiện tại, cho API biết ưu tiên kết quả trong khu vực đó mà không giới hạn nghiêm ngặt. maxResultCount không bắt buộc sẽ giới hạn số lượng kết quả được trả về.

Hiển thị ghim và thông tin chi tiết về địa điểm

Giờ đây, ứng dụng có thể thực hiện tìm kiếm địa điểm và điền sẵn phần tử. Trong bước tiếp theo, chúng ta sẽ cải thiện chức năng của ứng dụng bằng cách:

  • Hiển thị ghim trên bản đồ cho từng địa điểm được điền sẵn trong PlaceSearchElement.
  • Cho phép người dùng nhấp vào ghim hoặc địa điểm trong PlaceSearchElement để xem thêm thông tin chi tiết về địa điểm cụ thể đó.

Nguyên tắc của bước này là như nhau cho dù ứng dụng đang sử dụng tính năng tìm kiếm lân cận hay tìm kiếm văn bản.

Trước tiên, hãy thêm một biến toàn cục vào mã JavaScript để lưu trữ điểm đánh dấu địa điểm. Điều này sẽ cho phép bạn xoá các mục đó khi nội dung tìm kiếm thay đổi và xử lý các sự kiện nhấp chuột.

let markers = {};

Tạo một hàm để thêm điểm đánh dấu vào bản đồ. Hàm này sẽ được gọi bất cứ khi nào kết quả tìm kiếm mới được tải. Thao tác này sẽ:

  • Xoá mọi điểm đánh dấu địa điểm hiện có khỏi bản đồ.
  • Lặp lại các kết quả từ PlaceSearchElement và thêm điểm đánh dấu cho mỗi kết quả.
  • Điều chỉnh ranh giới của bản đồ để tất cả điểm đánh dấu mới đều hiển thị.

Để theo dõi thời điểm có kết quả tìm kiếm, hãy thêm trình nghe sự kiện gmp-load vào phần tử <gmp-place-search>. Sự kiện này kích hoạt sau khi quá trình tìm kiếm hoàn tất và kết quả được hiển thị.

Chúng ta sẽ thêm trình nghe vào bên trong hàm tìm kiếm (ví dụ: updatePlaceList) và sử dụng tuỳ chọn { once: true } để đảm bảo trình nghe chỉ kích hoạt cho kết quả của lượt tìm kiếm hiện tại.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

Hàm addMarkers có dạng như sau:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

Sau khi hoàn tất bước này, ứng dụng sẽ có dạng như sau, với khả năng hiển thị điểm đánh dấu cho từng địa điểm mà PlaceSearchElement trả về:

hình ảnh

Bây giờ, chúng ta đã có điểm đánh dấu trên bản đồ, bước cuối cùng là xử lý các sự kiện nhấp chuột vào điểm đánh dấu và phần tử để hiển thị cửa sổ thông tin có thông tin chi tiết về địa điểm, do Phần tử Place Details cung cấp. Trong ví dụ này, chúng ta sẽ sử dụng Thành phần thu gọn về chi tiết địa điểm.

Thêm HTML của Phần tử thu gọn Place Details vào mã của bạn, ví dụ:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

style được đặt thành display: none; thuộc tính này sẽ không xuất hiện cho đến khi bắt buộc. gmp-place-all-content được truyền để hiển thị tất cả nội dung của phần tử. Để chọn nội dung cần hiển thị, hãy xem tài liệu về Phần tử thu gọn của Place Details.

Tạo một biến toàn cục trong JavaScript để giữ thông tin tham chiếu đến Phần tử thu gọn của Chi tiết địa điểm và điền thông tin này vào mã khởi chạy, ví dụ:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

Trong hàm addMarkers, hãy thêm trình nghe sự kiện gmp-click vào mỗi điểm đánh dấu và định cấu hình Thành phần thu gọn của Chi tiết địa điểm để hiển thị chi tiết địa điểm bằng cách truyền Mã địa điểm của điểm đánh dấu hiện tại.

Sau khi hoàn tất, một Cửa sổ thông tin sẽ mở ra để hiển thị Phần tử thu gọn về Place Details, được neo trên điểm đánh dấu.

Cuối cùng, bản đồ được đặt ở khung nhìn của địa điểm đã chọn, giúp bạn có thể nhìn thấy địa điểm đó.

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

Để cho phép người dùng nhấp vào một địa điểm trong Thành phần danh sách địa điểm để hiển thị Thành phần chi tiết địa điểm thu gọn, hãy thêm đoạn mã sau vào mã JavaScript sau lệnh gọi đến configureFromSearchNearbyRequest.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

Sau khi hoàn tất bước này, ứng dụng sẽ có thể sử dụng tính năng Nearby Search hoặc Tìm kiếm văn bản để điền vào Phần tử danh sách địa điểm. Kết quả của việc này sẽ hiển thị các ghim trên bản đồ và khi nhấp vào một ghim hoặc một địa điểm trong Thành phần Danh sách địa điểm, bạn sẽ thấy một Cửa sổ thông tin có thông tin chi tiết về địa điểm, do Thành phần Thông tin chi tiết về địa điểm (Thu gọn) cung cấp.

Ứng dụng sẽ có dạng như sau:

hình ảnh

Kết luận

PlaceSearchElement kết hợp với Thành phần thu gọn của Chi tiết địa điểm mang đến một cách thức đơn giản để thêm các tính năng khám phá địa điểm phong phú vào ứng dụng Google Maps Platform của bạn.

Hãy dùng thử Places UI Kit ngay hôm nay để giúp người dùng tìm và khám phá địa điểm bằng cả tính năng tìm kiếm lân cận và tìm kiếm bằng văn bản, đồng thời hiển thị thông tin chi tiết phong phú về địa điểm, từ đó tăng cường khả năng tương tác của người dùng với các trường hợp sử dụng khám phá địa điểm.

Người đóng góp

Henrik Valve | Kỹ sư DevX