기존 Places API 사용자를 위한 장소 UI 키트 채택

기존 Places API 또는 Place Class 구현을 Places UI 키트 구성요소로 이전하는 방법을 알아봅니다.

가이드의 대상 독자

이 가이드는 Places API를 사용하여 기존 구현이 있고 Places UI 키트를 사용하도록 코드를 업데이트하려는 개발자를 위한 가이드입니다. 다음과 같은 경우 가장 유용합니다.

Places API (신규 또는 기존) 엔드포인트에 HTTP 요청을 실행합니다.
Maps JavaScript API 내에서 장소 클래스를 사용합니다.
API 응답을 처리하여 웹 애플리케이션의 UI에 장소 정보를 렌더링합니다.

기본 요건

Google Cloud 프로젝트에서 Places UI Kit를 사용 설정합니다. 기존 API 키를 계속 사용하거나 Places UI 키트의 새 API 키를 생성할 수 있습니다. 키 제한을 비롯한 자세한 내용은 API 키 사용을 참고하세요.

Maps JavaScript API 로드 업데이트

Places UI 키트를 사용하려면 Maps JavaScript API의 동적 라이브러리 가져오기 메서드를 사용해야 합니다. 직접 스크립트 로드 태그를 사용하는 경우 업데이트해야 합니다.

Maps JavaScript API의 로드 스크립트를 업데이트한 후 필요한 라이브러리를 가져와 Places UI 키트를 사용합니다.

장소 세부정보 요소 구현

장소 세부정보 요소 및 장소 세부정보 컴팩트 요소 는 장소의 세부정보를 렌더링하는 HTML 요소입니다.

현재 구현 환경

HTTP 요청을 사용하여 장소 세부정보 호출을 실행하거나 JavaScript API 장소 클래스를 사용합니다.
API 응답을 파싱하고 HTML 및 CSS를 사용하여 장소 세부정보를 표시합니다.

장소 세부정보 요소로 이전

HTML 구조 수정

장소 세부정보가 렌더링되는 HTML 컨테이너를 식별합니다. 맞춤 HTML 요소 (이름, 주소, 사진 등의 div, span)를 장소 세부정보 요소 HTML로 바꿉니다.

선택할 수 있는 요소는 두 가지입니다.

장소 세부정보 컴팩트 요소
장소 세부정보 요소

사용할 요소를 선택하는 방법에 관한 자세한 내용은 장소 세부정보 요소를 참고하세요.

기존 HTML은 다음과 같습니다.

<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>

표시할 콘텐츠 를 명시적으로 지정하는 새 HTML의 예:

<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>

JavaScript 로직 조정

기존 로직

기존 로직에는 다음이 포함될 수 있습니다.

장소 ID 가져오기
PlacesService().getDetails() 사용 또는 웹 서비스 호출
특정 데이터를 요청하기 위해 필드 배열 (JS API) 또는 FieldMask (웹 서비스) 지정
콜백 해결에서 HTML 요소를 수동으로 선택하고 수신된 데이터로 채우기

다음은 장소 세부정보를 구현하는 방법의 예입니다.

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);
}

새 로직

새 로직에는 다음이 포함됩니다.

장소 ID 또는 장소 객체 가져오기
<gmp-place-details-place-request> 요소에 대한 참조 가져오기
장소 ID 또는 장소 객체를 <gmp-place-details-place-request> 요소의 장소 속성에 전달

다음은 JavaScript 로직에서 장소 세부정보 UI 키트를 구현하는 방법의 예입니다. 장소 세부정보 요소에 대한 참조를 가져옵니다. 이 요소가 있으면 장소 세부정보 장소 요청 요소에 대한 참조를 가져오고 장소 ID를 사용하여 장소 속성을 설정합니다. 위의 HTML 코드 예에서 장소 세부정보 요소 스타일은 display: none으로 설정됩니다. 이 스타일은 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);

장소 검색 요소 구현

장소 검색 요소는 장소 검색 결과를 목록으로 렌더링하는 HTML 요소입니다.

현재 구현 환경

HTTP 요청을 사용하여 텍스트 검색 또는 주변 검색을 실행하거나 JavaScript API 장소 클래스를 사용합니다.
FieldMask를 사용하여 쿼리 매개변수, 위치 제한 또는 편향, 유형, 요청된 필드를 지정합니다.
API 응답을 파싱하고 장소 배열을 반복하며 HTML 목록 항목을 수동으로 만듭니다.

장소 검색 요소로 이전

HTML 구조 수정

장소 목록을 렌더링하는 HTML 컨테이너를 식별합니다. 맞춤 HTML 요소 (이름, 주소 등의 div, span)를 장소 검색 요소 HTML 요소로 바꿉니다.

기존 HTML은 다음과 같습니다.

<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>

장소 검색 요소는 <gmp-place-search> 구성요소를 사용하여 구현됩니다. 검색 유형을 구성하려면 다음 슬롯 구성 구성요소 중 하나를 내부에 포함합니다.

<gmp-place-text-search-request> 텍스트 검색의 경우
주변 검색의 경우 <gmp-place-nearby-search-request>

결과가 표시되는 방식을 정의하려면 <gmp-place-all-content> 바로가기를 사용하거나 자체 개별 프레젠테이션 구성요소 집합을 제공하면 됩니다. selectable (목록 항목을 클릭할 수 있도록 허용) 및 orientation(가로 또는 세로 레이아웃)과 같은 주요 속성은 상위 구성요소에서 직접 설정할 수 있습니다.

주변 검색 예

<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>

텍스트 검색 예

<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>

JavaScript 로직 조정

JavaScript에서 document.querySelector()를 사용하여 검색 컨트롤러 구성요소에 대한 참조를 가져옵니다. 설정에 따라 <gmp-place-text-search-request> 또는 <gmp-place-nearby-search-request> 요소가 됩니다.

다음으로 이 컨트롤러에서 속성을 설정하여 검색을 정의합니다. 필수 속성은 실행 중인 검색 유형에 따라 다릅니다.

텍스트 검색 (<gmp-place-text-search-request>)의 경우 기본 속성은 textQuery입니다.

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

주변 검색 (<gmp-place-nearby-search-request>)의 경우 검색 영역을 locationRestriction을 사용하여 정의해야 합니다. 그런 다음 includedTypes를 사용하여 해당 영역 내에서 특정 종류의 장소를 필터링할 수 있습니다.

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'];

상위 <gmp-place-search> 구성요소는 컨트롤러의 필수 속성이 설정되는 즉시 새 검색을 자동으로 시작합니다.

텍스트 검색의 경우 textQuery에 값을 할당하는 순간 검색이 실행됩니다.
주변 검색의 경우 유효한 locationRestriction이 제공된 후 검색이 실행됩니다.

기본 장소 자동 완성 요소 구현

장소 검색 요소의 제공된 UI 없이 검색 환경이 필요한 개발자를 위해 기본 장소 자동 완성 요소를 사용할 수 있습니다.

이 요소는 맞춤 사용자 인터페이스에서 결과가 표시되는 방식을 완전히 제어하면서 검색 입력란을 만드는 데 적합합니다. 자동 완성 요소의 유일한 책임은 사용자가 입력할 때 장소 예상 검색어를 제공하고 선택한 장소의 장소 ID를 프로그래매틱 방식으로 노출하는 것입니다.

자체적으로 세부정보를 표시하거나 프로그래매틱 방식으로 액세스할 수 있는 다른 정보를 제공하지 않습니다.

현재 구현 환경

기존 로직에는 다음이 포함될 수 있습니다.

사용자가 입력할 때 장소 자동 완성을 호출하고 결과를 표시하는 텍스트 입력란을 페이지에 렌더링합니다.
사용자가 선택한 장소의 장소 ID를 사용하여 세부정보를 가져옵니다(예: 장소 세부정보 API 사용).
선택한 장소의 세부정보를 표시합니다.

장소 자동 완성 요소로 이전

HTML 구조 수정

자동 완성 위젯을 연결하는 HTML 요소를 식별하고 삭제합니다. 표준 HTML 입력란을 사용할 가능성이 높습니다.

<input id="pac-input" type="text" placeholder="Search for a location" />

웹 구성요소 접근 방식을 사용하여 페이지에서 기본 장소 자동 완성 요소를 초기화하는 새 HTML의 예:

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

JavaScript 로직 조정

JavaScript 로직에는 input HTML 요소에 연결된 자동 완성 위젯을 만드는 작업이 포함될 수 있습니다. 그런 다음 이 위젯은 place_changed 이벤트를 수신 대기하고 반환된 데이터로 작업을 트리거합니다.

삭제할 기존 JavaScript의 예:

// 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);
});

새 JavaScript 로직은 기본 장소 자동 완성 요소에 대한 참조를 가져오고 gmp-select 이벤트를 수신 대기합니다.

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

자동 완성 드롭다운에서 장소를 선택하면 gmp-select 이벤트가 발생합니다. 선택한 장소의 장소 ID는 event 객체에서 가져올 수 있습니다. 그런 다음 장소 ID를 사용하여 장소 세부정보 요소의 인스턴스를 초기화하여 선택한 장소 세부정보를 표시할 수 있습니다.

맞춤설정 처리

장소 세부정보 요소 맞춤설정

방향

장소 세부정보 요소는 가로 및 세로 방향으로 렌더링할 수 있습니다. gmp-place-details-compact의 orientation 속성을 사용하여 세로와 가로 중에서 선택합니다. 예를 들면 다음과 같습니다.

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

렌더링할 필드 선택

콘텐츠 요소를 사용하여 장소 세부정보 요소 내에서 렌더링할 콘텐츠를 지정합니다. 예를 들어 콘텐츠 요소 <gmp-place-type> 을 제외하면 장소 세부정보 요소가 선택한 장소의 장소 유형을 렌더링하지 않습니다. 콘텐츠 요소의 전체 목록은 PlaceContentConfigElement 참조 문서를 참고하세요.

장소 세부정보 요소에서 필드를 추가하거나 삭제해도 페이지에서 요소를 렌더링하는 비용은 변경되지 않습니다.

CSS 스타일 설정

맞춤 CSS 속성을 사용하여 요소의 색상과 글꼴을 구성할 수 있습니다. 예를 들어 요소 배경을 녹색으로 설정하려면 다음 CSS 속성을 설정합니다.

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

자세한 내용은 PlaceDetailsCompactElement 참조 문서를 참고하세요.

장소 검색 요소 맞춤설정

방향

장소 검색 요소는 가로 및 세로 방향으로 렌더링할 수 있습니다. <gmp-place-search>의 orientation 속성을 사용하여 세로와 가로 중에서 선택합니다. 예를 들면 다음과 같습니다.

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

렌더링할 필드 선택

콘텐츠 요소를 사용하여 장소 검색 요소 내에서 렌더링할 콘텐츠를 지정합니다. 요소 <gmp-place-all-content>를 사용하여 모든 콘텐츠를 표시하거나 HTML 태그 선택을 사용하여 렌더링된 콘텐츠를 구성할 수 있습니다.

<gmp-place-content-config> 내에 <gmp-place-address>를 포함하면 각 장소의 주소만 렌더링됩니다. 예를 들면 다음과 같습니다.

<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>

기본 장소 자동 완성 요소 맞춤설정

CSS 스타일 설정

맞춤 CSS 속성을 사용하여 자동 완성 요소의 디자인을 맞춤설정할 수 있습니다. 예를 들어 배경색을 밝은 보라색으로 설정하려면 요소에서 background-color 속성을 설정합니다.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

자세한 내용은 BasicPlaceAutocompleteElement 참조 문서를 참고하세요.

이벤트 및 데이터 처리

Places UI 키트 요소는 이벤트를 수신 대기하고 데이터를 프로그래매틱 방식으로 가져올 수 있는 대화형 구성요소입니다.

이벤트 수신 대기

요소에 이벤트 리스너를 추가하여 사용자 상호작용 또는 요소의 상태에 따라 작업을 트리거할 수 있습니다.

선택 이벤트

gmp-select: 이 이벤트는 사용자가 선택할 때 발생합니다.
- 장소 검색 요소에서 사용자가 결과 목록에서 장소를 클릭할 때 트리거됩니다.
- 기본 장소 자동 완성 요소에서 사용자가 드롭다운 목록에서 예상 검색어를 클릭할 때 트리거됩니다.

일반 이벤트

장소 검색, 장소 세부정보, 기본 장소 자동 완성 요소는 모두 다음 이벤트를 지원합니다.

gmp-load: 요소와 콘텐츠의 로드 및 렌더링이 완료되면 발생합니다.
gmp-requesterror: 잘못된 API 키로 인해 서버에 대한 요청이 실패하면 발생합니다.

프로그래매틱 방식으로 요소 데이터에 액세스

상호작용하거나 로드한 후에는 요소에서 특정 데이터를 프로그래매틱 방식으로 가져올 수 있습니다.

장소 검색 요소 및 장소 세부정보 요소의 경우 다음 정보를 가져올 수 있습니다.
- 장소 ID
- 위치 (위도 및 경도)
- 표시 영역
기본 장소 자동 완성 요소의 경우 다음 정보를 가져올 수 있습니다.
- 장소 ID

요소에 포함된 다른 모든 데이터는 프로그래매틱 방식으로 액세스할 수 없습니다.

자세한 예는 장소 검색 요소, 장소 세부정보 요소, 기본 장소 자동 완성 요소의 개별 문서를 참고하세요.

Places UI 키트 요소를 통합한 후에는 원활한 전환과 긍정적인 사용자 경험을 위해 테스트가 중요합니다. 테스트는 구현한 모든 요소(장소 세부정보, 장소 검색, 기본 장소 자동 완성 요소)를 다루는 여러 주요 영역을 포함해야 합니다.

장소 세부정보 요소

장소 세부정보 요소의 경우 다양한 장소에 세부정보가 올바르게 표시되는지 확인하는 것으로 시작합니다. 다양한 장소 ID를 .place 속성에 전달하여 <gmp-place-details-place-request> 요소로 테스트합니다. 다양한 시설 유형 (풍부한 데이터가 있는 비즈니스, 관심 장소, 기본 주소)과 다양한 지역 또는 언어의 장소를 나타내는 ID를 사용합니다. 콘텐츠의 형식, 레이아웃, 존재에 주의하세요.

장소 검색 요소

장소 검색 요소를 구현한 경우 다양한 검색 시나리오에서 렌더링 및 동작을 확인합니다.

텍스트 검색의 경우 textQuery 속성을 <gmp-place-text-search-request> 요소에서 다양한 입력(광범위한 쿼리, 특정 주소, 위치 편향이 있는 쿼리)으로 설정하여 테스트합니다.
주변 검색의 경우 locationRestriction 및 includedTypes 속성을 <gmp-place-nearby-search-request> 요소에서 설정하여 테스트합니다. 다양한 위치 크기와 유형 필터를 사용합니다.

목록이 관련 결과로 채워지고 선택 시 gmp-select 이벤트가 올바르게 발생하는지 확인합니다.

기본 장소 자동 완성 요소

기본 장소 자동 완성 요소의 경우 사용자 상호작용 및 선택 이벤트에서 전달되는 데이터에 테스트를 집중합니다. 사용자가 예상 검색어를 클릭할 때 gmp-select 이벤트가 안정적으로 발생하는지 확인합니다. 이벤트 핸들러의 event.place 객체에 유효한 장소 ID가 포함되어 있는지 확인합니다.

가장 중요한 것은 엔드 투 엔드 흐름을 테스트하는 것입니다. 자동 완성 드롭다운에서 장소를 선택하고 장소 ID를 사용하여 장소 세부정보 요소와 같은 다른 요소를 채울 수 있는지 확인합니다.

오류 처리

모든 구성요소에서 오류 처리를 엄격하게 테스트하는 것이 중요합니다. 장소 세부정보 요소에 잘못되거나 존재하지 않는 장소 ID를 전달하거나 장소 검색 요소에 잘못된 검색 매개변수를 사용하는 것을 시뮬레이션합니다. 네트워크 문제를 시뮬레이션하거나 잘못된 API 키를 사용하여 gmp-requesterror 이벤트를 트리거하여 애플리케이션이 이 이벤트를 적절히 처리하는지 확인합니다. 사용자 친화적인 오류 메시지와 로깅을 구현하여 손상되거나 혼란스러운 UI를 방지합니다.

기존 Places API 사용자를 위한 장소 UI 키트 채택 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

가이드의 대상 독자

기본 요건

Maps JavaScript API 로드 업데이트

장소 세부정보 요소 구현

현재 구현 환경

장소 세부정보 요소로 이전

HTML 구조 수정

JavaScript 로직 조정

기존 로직

새 로직

장소 검색 요소 구현

현재 구현 환경

장소 검색 요소로 이전

HTML 구조 수정

주변 검색 예

텍스트 검색 예

JavaScript 로직 조정

기본 장소 자동 완성 요소 구현

현재 구현 환경

장소 자동 완성 요소로 이전

HTML 구조 수정

JavaScript 로직 조정

맞춤설정 처리

장소 세부정보 요소 맞춤설정

방향

렌더링할 필드 선택

CSS 스타일 설정

장소 검색 요소 맞춤설정

방향

렌더링할 필드 선택

기본 장소 자동 완성 요소 맞춤설정

CSS 스타일 설정

이벤트 및 데이터 처리

이벤트 수신 대기

선택 이벤트

일반 이벤트

프로그래매틱 방식으로 요소 데이터에 액세스

테스트 및 개선

기존 Places API 사용자를 위한 장소 UI 키트 채택