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

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

목표: Places API 또는 Place 클래스의 구현을 Places UI Kit으로 대체합니다.

가이드의 대상 독자

다음과 같은 개발자

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

기본 요건

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

Maps JavaScript API 로드 업데이트

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

Maps JavaScript API의 로드 스크립트를 업데이트한 후 장소 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 Place 클래스를 사용합니다.
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>를 사용하여 Nearby Search를 요청합니다.

결과가 표시되는 방식을 정의하려면 <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';

Nearby Search (<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가 제공된 후에 검색이 실행됩니다.

기본 Place Autocomplete 요소 구현

Place Search Element의 제공된 UI 없이 검색 환경이 필요한 개발자에게는 Basic Place Autocomplete Element가 제공됩니다.

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

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

현재 구현 환경

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

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

Place Autocomplete 요소로 이전

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>

기본 Place Autocomplete 요소 맞춤설정

CSS 스타일 설정

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

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

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

이벤트 및 데이터 처리

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

이벤트 수신 대기

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

선택 이벤트

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

일반 이벤트

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

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

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

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

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

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

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

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

장소 세부정보 요소

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

장소 검색 요소

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

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

목록에 관련 결과가 표시되고 선택 시 gmp-select 이벤트가 올바르게 실행되는지 확인합니다.

기본 Place Autocomplete 요소

기본 장소 자동 완성 요소의 경우 사용자 상호작용과 선택 이벤트로 전달되는 데이터에 중점을 두고 테스트합니다. 사용자가 추천을 클릭할 때 gmp-select 이벤트가 안정적으로 실행되는지 확인합니다. 이벤트 핸들러의 event.place 객체에 유효한 장소 ID가 포함되어 있는지 확인합니다.

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

오류 처리

오류 처리의 엄격한 테스트는 모든 구성요소에서 필수입니다. 잘못되었거나 존재하지 않는 장소 ID를 Place Details Element에 전달하거나 Place Search Element에 잘못된 검색 매개변수를 사용하는 것을 시뮬레이션합니다. 네트워크 문제를 시뮬레이션하거나 잘못된 API 키를 사용하여 gmp-requesterror 이벤트를 트리거하여 애플리케이션이 이를 적절하게 처리하는지 확인합니다. 사용자 친화적인 오류 메시지와 로깅을 구현하여 UI가 깨지거나 혼동을 일으키지 않도록 합니다.

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

가이드의 대상 독자

기본 요건

Maps JavaScript API 로드 업데이트

장소 세부정보 요소 구현

현재 구현 환경

장소 세부정보 요소로 이전

HTML 구조 수정

JavaScript 로직 적응

기존 로직

새로운 로직

장소 검색 요소 구현

현재 구현 환경

장소 검색 요소로 이전

HTML 구조 수정

주변 검색 예

텍스트 검색 예시

JavaScript 로직 적응

기본 Place Autocomplete 요소 구현

현재 구현 환경

Place Autocomplete 요소로 이전

HTML 구조 수정

JavaScript 로직 적응

맞춤설정 처리

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

방향

렌더링할 필드 선택

CSS 스타일 설정

장소 검색 요소 맞춤설정

방향

렌더링할 필드 선택

기본 Place Autocomplete 요소 맞춤설정

CSS 스타일 설정

이벤트 및 데이터 처리

이벤트 수신 대기

선택 이벤트

일반 이벤트

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

테스트 및 개선

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