Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

既存の Places API ユーザー向けに Places UI キットを導入する

既存の Places API または Place Class の実装を Places UI キットコンポーネントに移行する方法について説明します。

このガイドの対象読者

このガイドは、Places API を使用して既存の実装を行っており、Places UI キットを使用するようにコードを更新したいデベロッパーを対象としています。このガイドは、次のようなデベロッパーに最適です。

Places API（新規またはレガシー）のエンドポイントに HTTP リクエストを行っている。
Maps JavaScript API 内で Place クラスを使用している。
API レスポンスを処理して、ウェブアプリケーションの UI に場所情報をレンダリングしている。

前提条件

Google Cloud プロジェクトで Places UI Kit を有効にします。既存の API キーを引き続き使用することも、Places UI キット用に新しい API キーを生成することもできます。キーの制限など、詳細については Use API Keys を使用するをご覧ください。

Maps JavaScript API の読み込みを更新する

Places UI キットでは、Maps JavaScript API の動的ライブラリインポートメソッドで読み込む必要があります。ダイレクトスクリプト読み込みタグを使用している場合は、更新する必要があります。

Maps JavaScript API の読み込みスクリプトを更新したら、必要なライブラリをインポートして Places UI キットを使用します。

Place Details 要素を実装する

Place Details Element と Place Details Compact Element は、場所の詳細をレンダリングする HTML 要素です。

現在の実装

HTTP リクエストを使用して Place Details 呼び出しを行うか、JavaScript API の Place クラスを使用します。
API レスポンスを解析し、HTML と CSS を使用して場所の詳細を表示します。

Place Details 要素への移行

HTML 構造を変更する

場所の詳細がレンダリングされる HTML コンテナを特定します。カスタム HTML 要素（名前、住所、写真などの div、span）を Place Details 要素の HTML に置き換えます。

選択できる要素は 2 つあります。

Place Details Compact 要素
Place Details 要素

どちらを使用するかについて詳しくは、Place Details Elementをご覧ください。

既存の 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() を使用するか、ウェブサービス呼び出しを行う。
特定のデータをリクエストするために、fields 配列（JS API の場合）または FieldMask（ウェブサービスの場合）を指定する。
コールバック解決で、HTML 要素を手動で選択し、受信したデータを入力する。

次に、Place Details を実装する方法の例を示します。

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 または Place オブジェクトを取得します。
<gmp-place-details-place-request> 要素への参照を取得します。
プレイス ID または Place オブジェクトを <gmp-place-details-place-request> 要素の place プロパティに渡します。

次に、JavaScript ロジックで Place Details UI キットを実装する方法の例を示します。Place Details 要素への参照を取得します。この要素が存在する場合は、Place Details Place Request 要素への参照を取得し、プレイス ID を使用して place プロパティを設定します。上記の HTML コード例では、Place Details 要素のスタイルが 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);

Place Search 要素を実装する

Place Search 要素は、場所検索の結果をリストにレンダリングする HTML 要素です。

現在の実装

HTTP リクエストを使用してテキスト検索または Nearby Search を行うか、JavaScript API の Place クラスを使用します。
FieldMask を使用して、クエリパラメータ、場所の制限またはバイアス、タイプ、リクエストされたフィールドを指定します。
API レスポンスを解析し、場所の配列を反復処理して、HTML リストアイテムを手動で作成します。

Place Search 要素への移行

HTML 構造を変更する

場所のリストをレンダリングする HTML コンテナを特定します。カスタム HTML 要素（名前、住所などの div、span）を Place Search 要素の 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>

Place Search 要素は、<gmp-place-search> コンポーネントを使用して実装されます。検索のタイプを構成するには、次のいずれかのスロット付き構成コンポーネントを内部に含めます。

<gmp-place-text-search-request> テキスト検索の場合。
Nearby Search の場合は <gmp-place-nearby-search-request>。

結果の表示方法を定義するには、<gmp-place-all-content> ショートカットを使用するか、個々のプレゼンテーションコンポーネントの独自のセットを指定します。selectable（リストアイテムのクリックを許可する）や orientation（水平レイアウトまたは垂直レイアウト）などの重要な属性は、親コンポーネントで直接設定できます。

Nearby Search の例

<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 に値を割り当てるとすぐに検索が実行されます。
Nearby Search の場合、有効な locationRestriction が指定された後に検索が実行されます。

基本的な Place Autocomplete 要素を実装する

Place Search 要素の UI を使用せずに検索エクスペリエンスが必要なデベロッパー向けに、基本的な Place Autocomplete 要素が用意されています。

この要素は、カスタムユーザーインターフェースで結果の表示方法を完全に制御しながら、検索入力フィールドを作成する場合に最適です。Autocomplete 要素の唯一の役割は、ユーザーが入力したときに場所の候補を表示し、選択した場所のプレイス ID をプログラムで公開することです。

詳細を表示したり、プログラムでアクセス可能な他の情報を提供したりすることはありません。

現在の実装

既存のロジックには、次のものが含まれている可能性があります。

ページにテキスト入力フィールドをレンダリングし、ユーザーが入力すると Place Autocomplete を呼び出して結果を表示する。
ユーザーが選択した場所のプレイス ID を使用して、Place Details API などを使用して詳細を取得する。
選択した場所の詳細を表示する。

Place Autocomplete 要素への移行

HTML 構造を変更する

Autocomplete ウィジェットをアタッチする HTML 要素を特定して削除します。標準の HTML 入力フィールドを使用している可能性があります。

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

新しい HTML の例。ウェブコンポーネントアプローチを使用して、ページに基本的な Place Autocomplete 要素を初期化します。

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

JavaScript ロジックを調整する

JavaScript ロジックでは、input HTML 要素にアタッチされた Autocomplete ウィジェットを作成している可能性があります。このウィジェットは 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 ロジックでは、基本的な Place Autocomplete 要素への参照を取得し、gmp-select イベントをリッスンします。

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

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

Autocomplete プルダウンで場所を選択すると、gmp-select イベントが発生します。選択した場所のプレイス ID は、event オブジェクトから取得できます。プレイス ID を使用して Place Details Element のインスタンスを初期化し、選択した場所の詳細を表示できます。

カスタマイズを処理する

Place Details 要素のカスタマイズ

画面の向き

Place Details 要素は、水平方向と垂直方向の両方でレンダリングできます。gmp-place-details-compact の orientation 属性を使用して、縦方向と横方向を選択します。次に例を示します。

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

レンダリングするフィールドを選択する

コンテンツ要素を使用して、Place Details 要素内にレンダリングするコンテンツを指定します。たとえば、コンテンツ要素 <gmp-place-type> を除外すると、Place Details 要素で選択した場所の場所タイプがレンダリングされなくなります。コンテンツ要素の完全なリストについては、 PlaceContentConfigElement のリファレンスドキュメントをご覧ください。

Place Details 要素でフィールドを追加または削除しても、ページ上の要素のレンダリング費用は変わりません。

CSS スタイルを設定する

カスタム CSS プロパティを使用して、要素の色とフォントを構成できます。たとえば、要素の背景を緑色に設定するには、次の CSS プロパティを設定します。

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

詳細については、 PlaceDetailsCompactElement のリファレンスドキュメントをご覧ください。

Place Search 要素のカスタマイズ

画面の向き

Place Search 要素は、水平方向と垂直方向の両方でレンダリングできます。<gmp-place-search> の orientation 属性を使用して、縦方向と横方向を選択します。次に例を示します。

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

レンダリングするフィールドを選択する

コンテンツ要素を使用して、Place Search 要素内にレンダリングするコンテンツを指定します。要素 <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 プロパティを使用して、Autocomplete 要素のルック＆フィールをカスタマイズできます。たとえば、背景色を薄い紫色に設定するには、要素の background-color プロパティを設定します。

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

詳細については、 BasicPlaceAutocompleteElement のリファレンスドキュメントをご覧ください。

イベントとデータを処理する

Places UI キットの要素は、イベントをリッスンしてデータをプログラムで取得できるインタラクティブなコンポーネントです。

イベントをリッスンする

要素にイベントリスナーを追加して、ユーザー操作または要素の状態に基づいてアクションをトリガーできます。

選択イベント

gmp-select: このイベントは、ユーザーが選択したときに発生します。
- Place Search 要素では、ユーザーが結果リスト内の場所をクリックしたときにトリガーされます。
- 基本的な Place Autocomplete 要素では、ユーザーがプルダウンリストで候補をクリックしたときにトリガーされます。

一般的なイベント

Place Search、Place Details、基本的な Place Autocomplete の各要素は、次のイベントをサポートしています。

gmp-load: 要素とそのコンテンツの読み込みとレンダリングが完了したときに発生します。
gmp-requesterror: サーバーへのリクエストが失敗したときに発生します（無効な API キーが原因の場合など）。

要素データにプログラムでアクセスする

要素が操作または読み込まれた後、要素から特定のデータをプログラムで取得できます。

Place Search 要素と Place Details 要素の場合、次の情報を取得できます。
- プレイス ID
- 場所（緯度と経度）
- ビューポート
基本的な Place Autocomplete 要素の場合、次の情報を取得できます。
- プレイス ID

要素に含まれる他のすべてのデータには、プログラムでアクセスできません。

詳細な例については、Place Search 要素、Place Details 要素、およびBasic Place Autocomplete 要素の個別のドキュメントをご覧ください。

Places UI キットの要素を統合したら、スムーズな移行と良好なユーザーエクスペリエンスを実現するためにテストが不可欠です。テストでは、実装したすべての要素（Place Details、Place Search、基本的な Place Autocomplete の各要素）を対象に、いくつかの重要な領域をカバーする必要があります。

Place Details 要素

Place Details 要素の場合は、まずさまざまな場所の詳細が正しく表示されることを確認します。さまざまなプレイス ID を渡して、 .place プロパティの <gmp-place-details-place-request> 要素をテストします。さまざまな施設タイプ（リッチデータを含むビジネス、スポット、基本的な住所）を表す ID と、さまざまな地域や言語の場所を使用します。コンテンツの書式設定、レイアウト、存在に注意してください。

Place Search 要素

Place Search 要素を実装した場合は、さまざまな検索シナリオでのレンダリングと動作を確認します。

テキスト検索の場合は、textQuery プロパティを <gmp-place-text-search-request> 要素に設定して、広範なクエリ、特定の住所、場所のバイアスを含むクエリなど、さまざまな入力を設定してテストします。
Nearby Search の場合は、locationRestriction プロパティと includedTypes プロパティを <gmp-place-nearby-search-request> 要素に設定してテストします。さまざまな場所のサイズとタイプフィルタを使用します。

リストに関連する結果が入力され、選択時に gmp-select イベントが正しく発生することを確認します。

基本的な Place Autocomplete 要素

基本的な Place Autocomplete 要素の場合は、ユーザーインタラクションと選択イベントで渡されるデータに重点を置いてテストします。ユーザーが候補をクリックしたときに gmp-select イベントが確実に発生することを確認します。イベントハンドラの event.place オブジェクトに有効なプレイス ID が含まれていることを確認します。

最も重要なのは、エンドツーエンドのフローをテストすることです。Autocomplete プルダウンから場所を選択し、そのプレイス ID を使用して Place Details 要素などの別の要素にデータを入力できることを確認します。

エラー処理

すべてのコンポーネントでエラー処理を厳密にテストすることが不可欠です。Place Details 要素に無効または存在しないプレイス ID を渡すか、Place Search 要素に無効な検索パラメータを使用するシミュレーションを行います。ネットワークの問題をシミュレートするか、無効な API キーを使用して gmp-requesterror イベントをトリガーし、アプリケーションが適切に処理することを確認します。ユーザーフレンドリーなエラーメッセージとロギングを実装して、UI の破損や混乱を防ぎます。

既存の Places API ユーザー向けに Places UI キットを導入する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このガイドの対象読者

前提条件

Maps JavaScript API の読み込みを更新する

Place Details 要素を実装する

現在の実装

Place Details 要素への移行

HTML 構造を変更する

JavaScript ロジックを調整する

既存のロジック

新しいロジック

Place Search 要素を実装する

現在の実装

Place Search 要素への移行

HTML 構造を変更する

Nearby Search の例

テキスト検索の例

JavaScript ロジックを調整する

基本的な Place Autocomplete 要素を実装する

現在の実装

Place Autocomplete 要素への移行

HTML 構造を変更する

JavaScript ロジックを調整する

カスタマイズを処理する

Place Details 要素のカスタマイズ

画面の向き

レンダリングするフィールドを選択する

CSS スタイルを設定する

Place Search 要素のカスタマイズ

画面の向き

レンダリングするフィールドを選択する

基本的な Place Autocomplete 要素のカスタマイズ

CSS スタイルを設定する

イベントとデータを処理する

イベントをリッスンする

選択イベント

一般的なイベント

要素データにプログラムでアクセスする

テストと改善

既存の Places API ユーザー向けに Places UI キットを導入する