ガイドv3.2 API Referencev3.1 API Reference
ガイド
  1. 開発者ガイド
  2. フレームワークと統合する

Reactを使用してHERE Mapsを構築する

 HERE Maps API for JavaScript version 3.2

HERE Maps API for JavaScriptとReactの機能コンポーネントを組み合わせると、シームレスなユーザーエクスペリエンスを提供し、アプリ全体でコンポーネントを再利用してコードの重複を減らすことができるため、保守が簡単で双方向的なWebアプリを作成できます。

マップを特定のビジネス ニーズに合わせて適切に調整するには、多くのカスタマイズが必要になる場合がよくあります。マップをReactコンポーネントとして構築することで、最も複雑なカスタマイズであっても1つのコンポーネント内に組み込めるため、マップの管理と再利用が簡単になります。

次のチュートリアルでは、Viteツールを使用して、HERE Maps API for Javascriptを備えた基本的なReactアプリケーションを作成および開発します。

統合方法を選択する

次のアプローチを使用して、HERE Maps API for JavascriptをReactアプリケーションに統合できます。

  • CDNビルド：HTMLファイル内の<script>タグを使用してライブラリを読み込みます。このアプローチはシンプルで、バンドラーの設定は必要ありません。
  • npmパッケージ：ライブラリをnpmの依存関係としてインストールし、JavaScript/TypeScriptコード内でモジュールを直接インポートします。このアプローチはTypeScriptのサポートを向上させ、最新のビルドツールとシームレスに統合します。

このガイドでは両方の方法について説明します。プロジェクトの要件に最も適したものを選択してください。

Viteを使用して新しいReactアプリを設定する

Viteツールを使用して新しいReactアプリケーションを設定します。このツールを使用すると、シングルページアプリケーションの構築を簡単に始めることができます。

  1. プロジェクトのルートフォルダーで、Windows Power Shellやコマンドプロンプトなど、任意のコマンドラインツールを起動します。

  2. 次のコマンドを入力して、新しいReactプロジェクトを開始します。

    npm create vite@latest my-react-app -- --template react

    ターミナルにcreate-vite@<version>のインストールプロンプトが表示されたら、yを入力します。

    このコマンドは、アプリフォルダーを作成することで、必要なプロジェクトの基盤を設定します。

  3. 次のコマンドを入力して、アプリフォルダーを作業ディレクトリとして設定します。

    cd my-react-app

  4. 次のコマンドを入力して、npmパッケージマネージャーをインストールします。

    npm install

Viteの設定が完了したら、HERE Mapsを表示するReactマップコンポーネントを作成します。

オプション1：CDNを使用してHERE JavaScript APIライブラリをインポートする

HERE Mapsを実行するために必要なライブラリをindex.htmlファイルにインポートします。

  1. メインの<app>フォルダー (この例ではmy-react-appフォルダー) で、コードエディターを使用してindex.htmlファイルを開きます。

  2. ファイルのデフォルトの内容を次のHTMLコードに置き換えます。

    <!-- my-react-app/index.html -->
<!doctype html>
<html lang="en">
<head>
   <script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-core.js"></script>
   <script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-service.js"></script>
   <script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-mapevents.js"></script>
   <script type="text/javascript" charset="utf-8" src="https://js.api.here.com/v3/3.2/mapsjs-ui.js" ></script>
   <link rel="stylesheet" type="text/css" href="https://js.api.here.com/v3/3.2/mapsjs-ui.css" />
</head>
<body>
   <div id="root"></div>
   <script type="module" src="/src/main.jsx"></script>
</body>
</html>

マップコンポーネントを作成する (CDNアプローチ)

HERE Maps API for Javascriptを使用して、<div>内に地図を表示するReactコンポーネントを作成します。refシステムを利用してDOM要素に直接アクセスし、地図を操作できるようにします。

  1. <app>/srcディレクトリ内にcomponentsディレクトリを作成します。

  2. componentsディレクトリ内にJSXファイル (例：HereMap.jsx) を作成し、コードエディターを使用してそのファイルを開きます。

  3. JSXファイル内にマップコンポーネントをレンダリングするコードを記述します。

    // src/components/HereMap.jsx
import { useEffect, useRef } from 'react';

// Stores the DOM node (mapRef) that contains the map 
const HereMap = () => {
const mapRef = useRef(null);

// Initializes the HERE map once after mount
useEffect(() => {
   const platform = new H.service.Platform({
      apikey: 'YOUR_HERE_APIKEY',
   });

   // Obtain the default map types from the platform object:
   const defaultLayers = platform.createDefaultLayers();

   // Instantiate (and display) a map:
   const map = new H.Map(mapRef.current, defaultLayers.vector.normal.map, {
      center: { lat: 52.5200, lng: 13.4050 },
      zoom: 10,
      pixelRatio: window.devicePixelRatio || 1,
   });

   // Enable dynamic resizing of the map, based on the current size of the enclosing container
   window.addEventListener('resize', () => map.getViewPort().resize());

   // MapEvents enables the event system.
   // The behavior variable implements default interactions for pan/zoom 
   // Also on mobile touch environments.
   const behavior = new H.mapevents.Behavior(
      new H.mapevents.MapEvents(map)
   );

   // Create the default UI:
   const ui = H.ui.UI.createDefault(map, defaultLayers);

   return () => map.dispose();
}, []);

// Return the map component with the map size set to 
// the full height and width of the browser window
return (
   <div
      ref={mapRef}
         style={
           {
             width: '100vw',
             height: '100vh'
           }
         }
   />
  );
};

export default HereMap;

オプション2：npmパッケージを使用する

CDN経由でライブラリを読み込む代わりに、HERE Maps API for JavaScriptをnpmパッケージとしてインストールできます。このアプローチにより、最新のビルドツールとの統合がより緊密になり、ツリーシェイクが改善され、TypeScriptがサポートされるようになります。

npmレジストリを設定する

パッケージをインストールする前に、HERE公開リポジトリを使用するようにnpmを設定します。

npm config set @here:registry https://repo.platform.here.com/artifactory/api/npm/maps-api-for-javascript/

npmパッケージをインストールする

HERE npmレジストリからHERE Maps API for Javascriptパッケージをインストールします。

npm install @here/maps-api-for-javascript

マップコンポーネントを作成する (npmアプローチ)

npmパッケージを使用する場合、index.htmlファイルに<script>タグを追加する必要はありません。代わりに、必要なモジュールをReactコンポーネントに直接インポートします。

  1. HERE Maps API <script>タグを含まない基本的な構造のみがindex.htmlファイルに含まれていることを確認してください。

    <!-- my-react-app/index.html -->
<!doctype html>
<html lang="en">
<head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>HERE Maps React App</title>
</head>
<body>
   <div id="root"></div>
   <script type="module" src="/src/main.jsx"></script>
</body>
</html>

  2. <app>/srcディレクトリ内にcomponentsディレクトリを作成します。

  3. componentsディレクトリ内に、以下のコードを含むJSXファイル (例：HereMap.jsx) を作成します。

    // src/components/HereMap.jsx
import { useEffect, useRef } from 'react';

// Import the HERE Maps API for JavaScript libraries
import H from '@here/maps-api-for-javascript';
// Import the CSS style for the default UI components
import '@here/maps-api-for-javascript/bin/mapsjs-ui.css';

// Stores the DOM node (mapRef) that contains the map 
const HereMap = () => {
const mapRef = useRef(null);

// Initializes the HERE map once after mount
useEffect(() => {
   const platform = new H.service.Platform({
      apikey: 'YOUR_HERE_API_KEY',
   });

   // Obtain the default map types from the platform object:
   const defaultLayers = platform.createDefaultLayers();

   // Instantiate (and display) a map:
   const map = new H.Map(mapRef.current, defaultLayers.vector.normal.map, {
      center: { lat: 52.5200, lng: 13.4050 },
      zoom: 10,
      pixelRatio: window.devicePixelRatio || 1,
   });

   // Enable dynamic resizing of the map, based on the current size of the enclosing container
   window.addEventListener('resize', () => map.getViewPort().resize());

   // MapEvents enables the event system.
   // The behavior variable implements default interactions for pan/zoom 
   // Also on mobile touch environments.
   const behavior = new H.mapevents.Behavior(
      new H.mapevents.MapEvents(map)
   );

   // Create the default UI:
   const ui = H.ui.UI.createDefault(map, defaultLayers);

   return () => map.dispose();
}, []);

// Return the map component with the map size set to 
// the full height and width of the browser window
return (
   <div
      ref={mapRef}
         style={
         {
            width: '100vw',
            height: '100vh'
         }
      }
   />
  );
};

export default HereMap;

npmパッケージアプローチはCDN方式と同じ機能を提供しますが、最新のJavaScriptビルドパイプラインへの統合性が向上しています。

Reactコンポーネントをインポートする

メインアプリケーションのエントリーポイントを、地図と連携するReactコンポーネントを使用するように設定します。

  1. <app>/srcディレクトリからApp.jsxファイルを開きます。

  2. ファイルのデフォルトの内容を次のコードに置き換えます。

    // my-react-app/src/App.jsx
import HereMap from './components/HereMap';

function App() {
return (
   <div>
      <HereMap />
   </div>
  );
}

export default App;

地図を表示する

Reactアプリの開発サーバーを実行して、地図をプレビューします。npm run devコマンドを使用すると、高速なローカルWebサーバーがデフォルトポートで起動します。

  1. 次のコマンドを入力して、アプリを起動します。

    npm run dev

    このコマンドの結果、Viteがアプリをバンドルし、ブラウザーで地図を表示できるようになります。また、編集を行うと、Viteは即座にページを再読み込みしたり、モジュールを更新したりします。

  2. Webブラウザーを開き、http://localhost:5173/にアクセスします。

結果：次の例に示すように、ブラウザーに地図が表示されます。

UIコンポーネントを使用した基本的なHERE Map

任意：追加のマップコンポーネントを設定する

より多くのフィーチャーを提供する追加のマップコンポーネントを組み込むことで、アプリケーションの使いやすさを向上させます。これを実現するには、HERE Maps API for Javascriptのフィーチャーとモード機能を活用して、公共交通機関情報表示を有効または無効にするボタンを追加する手順を実行します。

トグルを追加するには、追加のコンポーネントを作成し、既存のコンポーネントを更新して追加機能に対応させる必要があります。最終的なディレクトリ構造は次のようになります。

src/
├── main.jsx
├── App.jsx
└── components/
    ├── HereMap.jsx
    ├── HereMapContext.jsx <-- Manages the state of different components
    └── PublicTransitToggle.jsx <-- Controls the toggle logic and button styling

共有状態を管理する

関心の分離の原則を維持しながら、HereMapコンポーネントとPublicTransitToggleコンポーネント間の通信を可能にするため、HereMapContextコンポーネントを作成します。

  1. src/componentsディレクトリ内にHereMapContext.jsxファイルを作成し、コードエディターで開きます。

  2. 次の例に示すように、ファイルにコードを入力します。

    // src/components/HereMapContext.jsx
import { createContext, useContext, useRef, useState } from 'react';

const HereMapContext = createContext();

export const HereMapProvider = ({ children }) => {

// Holds the HERE map style object
const styleRef = useRef(null);

// Tracks whether the map style is ready
const [isReady, setIsReady] = useState(false);

return (
   <HereMapContext.Provider
      value={
        {
         styleRef,
         isReady,
         setIsReady
        }
      }
   >
      {children}
   </HereMapContext.Provider>
  );
};

// Custom hook that lets any component access the HERE map and style
export const useHereMap = () => useContext(HereMapContext);

マップコンポーネントを更新し、コンテキストとスタイルのステータスを共有する

スタイルオブジェクトを抽出してstyleRefに保存し、グローバルアクセスを可能にします。マップスタイルの準備ができた後にのみ、コンポーネントの追加や削除による変更が可能になります。

  1. src/componentsディレクトリからHereMap.jsxファイルを開きます。

  2. HereMapContextコンポーネントからコンテキスト情報を取得し、スタイル情報にグローバルアクセスできるようにファイルを更新します。更新後のHereMapコンポーネントロジックのコード例を参照してください。

    // src/components/HereMap.jsx
import { useEffect, useRef } from 'react';
import { useHereMap } from './HereMapContext'; // Obtain the context

const HereMap = () => {
const mapRef = useRef(null);
const { styleRef, setIsReady } = useHereMap(); // Get the context setters

useEffect(() => {
   const platform = new H.service.Platform({ apikey: 'YOUR_API_KEY' });

   const defaultLayers = platform.createDefaultLayers();

   const map = new H.Map(mapRef.current, defaultLayers.vector.normal.map, {
      center: { lat: 52.52, lng: 13.405 },
      zoom: 10,
      pixelRatio: window.devicePixelRatio || 1,
   });

   new H.mapevents.Behavior(new H.mapevents.MapEvents(map));
   H.ui.UI.createDefault(map, defaultLayers);

   const baseLayer = map.getBaseLayer();
   const style = baseLayer.getProvider().getStyle();

   // Enable other components to use the style once it is ready  
   if (style) {
      styleRef.current = style;
      setIsReady(true);
   }

   window.addEventListener('resize', () => map.getViewPort().resize());

   return () => map.dispose();
}, [styleRef, setIsReady]);

return (
   <div
      ref={mapRef}
         style={
           {
             width: '100vw',
             height: '100vh'
           }
         }
   />
  );
};

export default HereMap;

トグルロジックを作成する

モジュール性と再利用性を高めるために、PublicTransitToggleコンポーネントを個別に追加します。このコンポーネントは、マップビューでのpublic transitフィーチャーの表示/非表示を制御します。

  1. src/componentsディレクトリ内にPublicTransitToggle.jsxファイルを追加し、コードエディターを使用して開きます。

  2. 次の例に示すように、トグルロジックを設定します。

    // src/components/PublicTransitToggle.jsx

import { useState } from 'react';
import { useHereMap } from './HereMapContext';

const PublicTransitToggle = () => {
const { styleRef, isReady } = useHereMap(); // Access shared map state
const [enabled, setEnabled] = useState(false); // Track toggle state

const toggleTransit = () => {
   if (!isReady || !styleRef.current) {
      console.warn('Map style is not ready yet');
      return;
   }

   const style = styleRef.current;
   const feature = 'public transit';
   const mode = 'all systems';

   const enabledFeatures = style.getEnabledFeatures();
   const featureIndex = enabledFeatures.findIndex(f => f.feature === feature);

   if (featureIndex === -1) {
      // Enable the feature
      enabledFeatures.push({ feature, mode });
      setEnabled(true);
   } else {
      // Disable the feature
      enabledFeatures.splice(featureIndex, 1);
      setEnabled(false);
   }

   style.setEnabledFeatures(enabledFeatures);
};

// Returns the button with the associated styling, depending on the toggle state
return (
   <button
      onClick={toggleTransit}
      disabled={!isReady}
      style={
        {
         position: 'absolute',
         top: '20px',
         left: '20px',
         zIndex: 1000,
         padding: '10px 20px',
         fontSize: '14px',
         fontWeight: '700',
         fontFamily: 'Roboto, Helvetica Neue, Arial, sans-serif',
         backgroundColor: isReady ? (enabled ? '#1A73E8' : '#f4f6f9') : '#e0e0e0',
         color: isReady ? (enabled ? '#ffffff' : '#1A73E8') : '#aaa',
         border: `2px solid ${isReady ? '#1A73E8' : '#ccc'}`,
         borderRadius: '6px',
         cursor: isReady ? 'pointer' : 'not-allowed',
         transition: 'all 0.2s ease-in-out',
         boxShadow: isReady ? '0 2px 4px rgba(0,0,0,0.1)' : 'none',
        }
      }
   >
      {enabled ? 'Disable Public Transit' : 'Enable Public Transit'}
   </button>
  );
};

export default PublicTransitToggle;

アプリコンポーネント全体で状態ロジックを共有する

アプリをラップし、子コンポーネントが共有値にアクセスできるようにするHereMapProviderコンポーネントを追加します。

  1. srcディレクトリからmain.jsxファイルを開きます。

  2. デフォルトのコードを次のロジックに置き換えます。

    // src/main.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { HereMapProvider } from './components/HereMapContext';

ReactDOM.createRoot(document.getElementById('root')).render(
<React.StrictMode>
   <HereMapProvider>
      <App />
   </HereMapProvider>
</React.StrictMode>
);

トグルコンポーネントをアプリに追加する

対応するコンポーネントがHereMapコンポーネントから共有マップ状態にアクセスできるようにし、PublicTransitToggleボタンが正しく動作することを確認します。

  1. srcディレクトリから、コードエディターを使用してApp.jsxファイルを開きます。

  2. 次の例に示すように、ボタンコンポーネントをアプリに追加します。

    import HereMap from './components/HereMap';
import PublicTransitToggle from './components/PublicTransitToggle';

function App() {
return (
   <>
      <HereMap />
      <PublicTransitToggle />
   </>
  );
}

export default App;

この更新により、HereMapとPublicTransitToggleの両方がアプリの最上位レベルにレンダリングされます。これにより、次のことが保証されます。

  • HereMapコンポーネントが最初にマウントされ、HERE Mapのインスタンスとそのスタイルを作成できます。
  • これらの値 (mapとstyle) は、React Context、具体的にはHereMapProviderを通じて共有されます。
  • PublicTransitToggleボタンは、useHereMap()カスタムフックを呼び出すことで、共有データにアクセスできます。

両方のコンポーネントが同じコンポーネントツリーの一部である (HereMapProviderでラップされている) ため、間接的に通信できます。 結果：次の例に示すように、地図上で公共交通機関フィーチャーを切り替えることができるようになりました。

複数のReactコンポーネントを通じてHERE Mapsを操作する

次のステップ

HERE Maps API for Javascriptの設計とフィーチャーの詳細については、「APIリファレンス」を参照してください。

14 日前の更新