このページは Cloud Translation API によって翻訳されました。

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

目標: Places API または Place クラスの実装を Places UI Kit に置き換えます。

このガイドの対象読者

次の条件を満たすデベロッパー:

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

前提条件

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

Maps JavaScript API の読み込みを更新

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

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 Element の HTML に置き換えます。

選択できる要素は次の 2 つです。

Place Details Compact 要素
Place Details 要素

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

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

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

Place Search 要素を実装する

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

現在の実装

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

Place Search Element への移行

HTML 構造を変更する

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

次に、このコントローラのプロパティを設定して検索を定義します。必要なプロパティは、実行する検索のタイプによって異なります。

Text Search（<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 Element の UI を使用せずに検索機能を実装したいデベロッパー向けに、Basic Place Autocomplete Element が用意されています。

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

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

現在の実装

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

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

Place Autocomplete Element への移行

HTML 構造を変更する

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

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

ウェブコンポーネントアプローチを使用して、ページ上の Basic Place Autocomplete 要素を初期化する新しい 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 を使用して Place Details 要素のインスタンスを初期化し、選択した場所の詳細を表示できます。

ハンドルのカスタマイズ

Place Details 要素のカスタマイズ

向き

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

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

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

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

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

CSS スタイルを設定する

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

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

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

Place Search 要素のカスタマイズ

向き

プレイス検索要素は、横向きと縦向きの両方でレンダリングできます。<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: このイベントは、ユーザーが選択を行ったときに発生します。
- プレイス検索要素では、ユーザーが結果リスト内の場所をクリックしたときにトリガーされます。
- 基本的な場所の予測入力要素では、ユーザーがプルダウンリストの候補をクリックしたときにトリガーされます。

一般的なイベント

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

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

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

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

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

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

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

Places UI キットの要素を統合したら、スムーズな移行と優れたユーザーエクスペリエンスを実現するためにテストが不可欠です。テストでは、Place Details、Place Search、Basic Place Autocomplete の各要素など、実装したすべての要素を対象とする必要があります。

Place Details 要素

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

Place Search Element

プレイス検索要素を実装している場合は、さまざまな検索シナリオでレンダリングと動作を確認します。

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

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

基本的な Place Autocomplete 要素

Basic Place Autocomplete Element の場合は、ユーザー操作と選択イベントで渡されるデータに焦点を当ててテストします。ユーザーが予測をクリックしたときに gmp-select イベントが確実に発生することを確認します。イベントハンドラの event.place オブジェクトに有効な場所 ID が含まれていることを確認します。

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

エラー処理

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

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

このガイドの対象読者

前提条件

Maps JavaScript API の読み込みを更新

Place Details 要素を実装する

現在の実装

Place Details 要素への移行

HTML 構造を変更する

JavaScript ロジックを適応させる

既存のロジック

新しいロジック

Place Search 要素を実装する

現在の実装

Place Search Element への移行

HTML 構造を変更する

Nearby Search の例

テキスト検索の例

JavaScript ロジックを適応させる

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

現在の実装

Place Autocomplete Element への移行

HTML 構造を変更する

JavaScript ロジックを適応させる

ハンドルのカスタマイズ

Place Details 要素のカスタマイズ

向き

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

CSS スタイルを設定する

Place Search 要素のカスタマイズ

向き

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

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

CSS スタイルを設定する

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

イベントをリッスンする

選択イベント

一般的なイベント

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

テストと改善

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