이 페이지는 Cloud Translation API를 통해 번역되었습니다.

장소 UI 키트로 양방향 매장 검색기 빌드

목표

이 문서에서는 Google Maps Platform, 특히 지도 JavaScript API 및 장소 UI 키트: 장소 세부정보 요소를 사용하여 양방향 매장 검색 애플리케이션을 개발하는 주요 단계를 설명합니다. 매장 위치를 표시하는 지도를 만들고, 표시되는 매장 목록을 동적으로 업데이트하고, 각 매장의 풍부한 장소 정보를 표시하는 방법을 알아봅니다.

기본 요건

다음에 익숙한 것이 좋습니다.

Maps JavaScript API - 페이지에 지도를 표시하고 Places UI Kit를 가져오는 데 사용됩니다.
고급 마커: 지도에 마커를 표시하는 데 사용됩니다.
장소 UI 키트 - UI에 매장 정보를 표시하는 데 사용됩니다.

프로젝트에서 Maps JavaScript API 및 Places UI Kit를 사용 설정합니다.

시작하기 전에 Maps JavaScript API를 로드하고 고급 마커 및 장소 UI 키트에 필요한 라이브러리를 가져왔는지 확인합니다. 또한 이 문서에서는 HTML, CSS, JavaScript를 비롯한 웹 개발에 대한 실무 지식이 있다고 가정합니다.

초기 설정

첫 번째 단계는 페이지에 지도를 추가하는 것입니다. 이 지도는 매장 위치와 관련된 핀을 표시하는 데 사용됩니다.

페이지에 지도를 추가하는 방법에는 두 가지가 있습니다.

gmp-map HTML 웹 구성요소 사용
JavaScript 사용

사용 사례에 가장 적합한 메서드를 선택합니다. 이 가이드에서는 지도 구현의 두 가지 방법 모두 사용할 수 있습니다.

데모

이 데모에서는 베이 지역의 Google 사무실 위치를 표시하는 매장 검색 기능의 작동 예를 보여줍니다. 장소 세부정보 요소는 각 위치에 몇 가지 속성 예시와 함께 표시됩니다.

매장 위치 로드 및 표시

이 섹션에서는 매장 데이터를 로드하고 지도에 표시합니다. 이 가이드에서는 가져올 기존 매장 정보 저장소가 있다고 가정합니다. 매장 데이터는 데이터베이스와 같은 다양한 소스에서 가져올 수 있습니다. 이 예에서는 매장 위치를 각각 나타내는 매장 객체 배열이 포함된 로컬 JSON 파일 (stores.json)을 가정합니다. 각 객체는 name, location (lat 및 lng 포함), place_id를 하나 이상 포함해야 합니다.

매장 위치의 장소 ID가 없는 경우 이를 가져오는 방법에는 여러 가지가 있습니다. 자세한 내용은 장소 ID 문서를 참고하세요.

stores.json 파일의 매장 세부정보 항목의 예는 다음과 같습니다. 이름, 위치 (lat/lng), 장소 ID 필드가 있습니다. 매장 영업시간을 보관하는 객체가 있습니다 (자르기 처리됨). 매장 위치의 맞춤 기능을 설명하는 데 도움이 되는 두 가지 불리언 값도 있습니다.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

JavaScript 코드에서 매장 위치의 데이터를 가져와 각 매장에 대한 핀을 지도에 표시합니다.

다음은 이 작업을 수행하는 방법의 예입니다. 이 함수는 매장의 세부정보가 포함된 객체를 사용하고 각 매장의 위치를 기반으로 마커를 만듭니다.

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

매장을 로드하고 매장 위치를 나타내는 핀을 지도에 표시한 후 HTML 및 CSS를 사용하여 사이드바를 만들어 개별 매장에 관한 세부정보를 표시합니다.

이 단계에서 매장 검색기가 표시되는 모습의 예는 다음과 같습니다.

지도 표시 영역 변경사항 수신 대기

성능과 사용자 환경을 최적화하려면 해당 위치가 표시되는 지도 영역 (표시 영역) 내에 있는 경우에만 사이드바에 마커와 세부정보를 표시하도록 애플리케이션을 업데이트하세요. 이를 위해서는 지도 뷰포트 변경을 리슨하고 이러한 이벤트를 디보우싱한 후 필요한 마커만 다시 그립니다.

지도의 유휴 이벤트에 이벤트 리스너를 연결합니다. 이 이벤트는 화면 이동 또는 확대/축소 작업이 완료된 후 발생하여 계산에 안정적인 뷰포트를 제공합니다.

map.addListener('idle', debounce(updateMarkersInView, 300));

위의 코드 스니펫은 idle 이벤트를 리슨하고 debounce 함수를 호출합니다. debounce 함수를 사용하면 사용자가 지도와의 상호작용을 잠시 중지한 후에만 마커 업데이트 로직이 실행되므로 성능이 개선됩니다.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

위의 코드는 debounce 함수의 예입니다. 함수와 지연 인수를 사용하며 이는 유휴 리스너에서 전달된 것을 볼 수 있습니다. 300ms 지연이면 UI에 눈에 띄는 지연을 추가하지 않고도 지도의 움직임이 멈출 때까지 기다릴 수 있습니다. 이 시간 제한이 만료되면 전달된 함수(이 경우에는 updateMarkersInView)가 호출됩니다.

updateMarkersInView 함수는 다음 작업을 실행해야 합니다.

지도에서 기존 마커 모두 지우기

매장의 위치가 현재 지도 경계 내에 있는지 확인합니다. 예를 들면 다음과 같습니다.

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

위의 if 문 내에서 매장 위치가 지도 뷰포트 내에 있는 경우 마커를 표시하고 사이드바에 매장 세부정보를 저장하는 코드를 작성합니다.

장소 세부정보 요소를 사용하여 풍부한 장소 세부정보 표시

이 단계에서 애플리케이션은 모든 매장 위치를 표시하고 사용자는 지도 뷰포인트를 기반으로 매장 위치를 필터링할 수 있습니다. 이를 개선하기 위해 장소 세부정보 요소를 사용하여 사진, 리뷰, 접근성 정보와 같은 각 매장의 세부정보를 추가합니다. 이 예에서는 특히 장소 세부정보 좁게 표시 요소를 사용합니다.

데이터 소스의 각 매장 위치에는 해당하는 장소 ID가 있어야 합니다. 이 ID는 Google 지도에서 위치를 고유하게 식별하며 세부정보를 가져오는 데 필수적입니다. 일반적으로 이러한 장소 ID를 미리 획득하고 각 매장 레코드에 저장합니다.

애플리케이션에 장소 세부정보 좁게 표시 요소 통합

매장이 현재 지도 뷰포트 내에 있는 것으로 확인되고 사이드바에 렌더링되는 경우 매장의 장소 세부정보 좁게 보기 요소를 동적으로 만들고 삽입할 수 있습니다.

현재 처리 중인 매장의 경우 데이터에서 장소 ID를 가져옵니다. 장소 ID는 요소가 표시될 장소를 제어하는 데 사용됩니다.

JavaScript에서 PlaceDetailsCompactElement 인스턴스를 동적으로 만듭니다. 새 PlaceDetailsPlaceRequestElement도 생성되고 장소 ID가 전달되며 PlaceDetailsCompactElement에 추가됩니다. 마지막으로 PlaceContentConfigElement를 사용하여 요소에 표시할 콘텐츠를 구성합니다.

다음 함수는 필요한 장소 UI 키트 라이브러리가 가져와지고 이 함수가 호출되는 범위에서 사용할 수 있으며 함수에 전달된 storeData에 place_id가 포함되어 있다고 가정합니다.

이 함수는 요소를 반환하며 호출 코드는 이를 DOM에 추가할 책임이 있습니다.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

위의 예시 코드에서 요소는 장소 사진, 리뷰 평점, 접근성 정보를 표시하도록 구성되어 있습니다. 사용 가능한 다른 콘텐츠 요소를 추가하거나 삭제하여 맞춤설정할 수 있습니다. 사용 가능한 모든 옵션은 PlaceContentConfigElement 문서를 참고하세요.

장소 세부정보 좁게 요소는 CSS 맞춤 속성을 통해 스타일 지정을 지원합니다. 이렇게 하면 애플리케이션 디자인에 맞게 모양 (색상, 글꼴 등)을 조정할 수 있습니다. CSS 파일에 이러한 맞춤 속성을 적용합니다. 지원되는 CSS 속성은 PlaceDetailsCompactElement의 참조 문서를 참고하세요.

이 단계에서 애플리케이션이 표시되는 방식의 예는 다음과 같습니다.

매장 검색 기능 개선

매장 검색 애플리케이션을 위한 견고한 기반을 구축했습니다. 이제 기능을 확장하고 더 풍부하고 사용자 중심적인 환경을 만드는 여러 가지 방법을 고려해 보세요.

자동 완성 추가

검색 입력을 Place Autocomplete와 통합하여 사용자가 매장을 검색할 지역을 찾는 방식을 개선합니다. 사용자가 주소, 지역 또는 관심 장소를 입력하고 추천을 선택하면 지도에서 해당 위치를 자동으로 중앙에 배치하여 주변 매장의 업데이트를 트리거하도록 프로그래밍합니다. 입력란을 추가하고 Place Autocomplete 기능을 입력란에 연결하여 이 작업을 실행합니다. 추천을 선택하면 지도의 중심이 해당 지점으로 설정될 수 있습니다. 결과를 운영 지역으로 편향되게 하거나 제한하도록 구성해야 합니다.

위치 감지

현재 지리적 위치를 감지하는 기능을 구현하여 특히 모바일 사용자에게 즉각적인 관련성을 제공합니다. 위치 감지를 위한 브라우저 권한을 획득한 후 지도의 중심을 사용자 위치로 자동 설정하고 가장 가까운 매장을 표시합니다. 사용자는 즉각적인 옵션을 찾을 때 이 주변 기능을 매우 중요하게 생각합니다. 위치 정보 액세스를 요청하는 버튼 또는 초기 프롬프트를 추가합니다.

거리 및 경로 표시

사용자가 관심 있는 매장을 찾으면 Routes API를 통합하여 여정을 크게 개선하세요. 나열하는 각 매장의 경우 사용자의 현재 위치 또는 검색된 위치에서의 거리를 계산하여 표시합니다. 또한 Routes API를 사용하여 사용자 위치에서 선택한 매장까지의 경로를 생성하는 버튼이나 링크를 제공합니다. 그런 다음 이 경로를 지도에 표시하거나 Google 지도에 연결하여 탐색할 수 있으므로 매장 찾기부터 실제 매장 방문까지 원활하게 전환할 수 있습니다.

이러한 확장 프로그램을 구현하면 Google 지도 플랫폼의 더 많은 기능을 사용하여 일반적인 사용자 요구사항을 직접 해결하는 포괄적이고 편리한 매장 검색 도구를 만들 수 있습니다.

결론

이 가이드에서는 대화형 매장 검색 도구를 빌드하는 핵심 단계를 설명했습니다. Maps JavaScript API를 사용하여 지도에 자체 매장 위치를 표시하고, 뷰포트 변경사항에 따라 표시되는 매장을 동적으로 업데이트하는 방법, 그리고 Places UI Kit에 따라 자체 매장 데이터를 표시하는 방법을 알아봤습니다. 장소 세부정보 요소와 함께 장소 ID를 비롯한 기존 매장 정보를 사용하면 각 위치에 대해 풍부하고 표준화된 세부정보를 표시하여 사용자 친화적인 매장 검색 도구의 견고한 기반을 만들 수 있습니다.

Maps JavaScript API 및 Places UI Kit를 사용하여 정교한 위치 기반 애플리케이션을 신속하게 개발할 수 있는 강력한 구성요소 기반 도구를 제공해 보세요. 이러한 기능을 결합하면 사용자에게 흥미롭고 유용한 환경을 제공할 수 있습니다.

참여자

헨리크 발브 | DevX 엔지니어

장소 UI 키트로 양방향 매장 검색기 빌드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

목표