JavaScript for Maps API 3.1 への移行

このセクションでは、 HERE Maps API for Javascript 3.0 からバージョン 3.1 への移行パスの概要を示し、下位互換性のない変更について詳しく説明します。 API のバージョン管理の詳細については、「 API のバージョン」を参照してください。

Maps API for JavaScript のバージョン 3.1 では、効率的なベクターレンダリングを提供し、マップのパフォーマンスを向上させ、開発者とエンドユーザーにより豊かなエクスペリエンスを提供する、新しい既定の WebGL ベースのレンダリングエンジンが導入されました。新しいレンダリングエンジンでは、 API の動作にさまざまな変更が加えられ、 2D HTML5 Canvas エンジンに関連する一連の機能が「レガシー」モジュールにシフトされます。

「 app_id 」および「 app_code 」ではなく API キー

HERE Maps API for Javascript バージョン 3.1 では、アプリケーションを認証する新しい方法が導入されています。 app_id と app_code のペアリングの代わり apikeyに、 HERE Maps API for Javascript はを使用します。次のコードは H.service.Platform 、 API の新しいバージョンでインスタンス化する方法を示しています。

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

レガシーモジュール

バージョン 3.0 から 3.1 へのスムーズな移行を可能にするために、 HERE Maps API for Javascript には 2 つの補助モジュールがあります。これらのモジュールを使用すると、最新のブラウザテクノロジーにアクセスできないアプリケーションでも HERE サービスからメリットを得ることができます。次のモジュールが追加されました。

mapsjs-core-legacy.js - HTML5 キャンバスレンダリングエンジンとその関連機能を提供します
mapsjs-service-legacy.js - レガシープラットフォームサービスへのアクセスを提供します (HTML5 メタ情報タイルなど )

モジュールを使用するには、ページにモジュールを含めるだけです。これらのファイルは、依存するモジュールの後に含めるようにしてください。例 :

<!DOCTYPE html>
  <html>
    <head>
      ...
      <meta name="viewport" content="initial-scale=1.0,
        width=device-width" />
      <script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-core-legacy.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-service-legacy.js"
        type="text/javascript" charset="utf-8"></script>
      ...
    </head>

*-legacy モジュールがただちにどのようにフォローされているか、 core およびserviceモジュールについてメモ

既定のエンジンとしての WebGL

HERE Maps API for Javascript バージョン 3.1 には、新しいデフォルトのレンダリングエンジンが含まれています。このエンジンは HTML5 WebGL キャンバス要素を使用して、リッチでカスタマイズ可能なベクトルマップのレンダリングを可能にします。エンジンでは、ベクトルデータとラスタデータの両方をレンダリングできます。そのため、 JavaScript API を利用するアプリケーションでは、変更内容が自動的に反映されます。ただし、使用中のベースレイヤーが CORS リクエストを送信しない場合、アプリケーションに影響が出る可能性があります。 WebGL レンダリングをサポートする最新のブラウザでアプリケーションを実行できない場合でも、 HTML5 キャンバス 2D レンダリングエンジンを使用できます。 WebGL エンジンを最大限に活用するには、新しいベクタータイルを使用します。

Maps API for JavaScript バージョン 3.0 では、ラスタタイルを含むマップが次のように初期化されました。

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

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 }
    });

以下のスニペットでは、ベクトルタイルに切り替える方法を示します。


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

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.vector.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 }
    });

以下のスニペットでは、サポートされているレガシーブラウザでキャンバス 2D レンダリングエンジンを使用する方法を示します。

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

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.raster.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 },
      engineType: H.map.render.RenderEngine.EngineType.P2D
    });

デフォルトのレイヤーコレクション

メソッドによって作成されたデフォルトのレイヤーコレクションの構造 H.service.Platform#createDefaultLayers に、レンダリングの変更が反映されます。このコレクションには、基本レイヤーとオーバーレイのセットが保持され、マップの外観を簡単に変更できます。

次の擬似コードは、 Maps API for JavaScript バージョン 3.0 で既定のレイヤーのコレクションがどのように構造化されたかを示しています。

{
incidents: <Layer>,
normal: {
  base: <Layer>,
  basenight: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  mapnight: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  panoramanight: <Layer>,
  traffic: <Layer>,
  trafficnight: <Layer>,
  transit: <Layer>,
  xbase: <Layer>,
  xbasenight: <Layer>
},
satellite: {
  base: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  traffic: <Layer>,
  xbase: <Layer>,
},
terrain: {
  base: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  traffic: <Layer>,
  xbase: <Layer>,
},
venues:  <Layer>
}

Maps API for JavaScript のバージョン 3.1 では、 WebGL レンダリングエンジンでのみ使用できる新しいベクターレイヤーが導入されています。この変更は、既定のレイヤーコレクションの構造に影響を与えます。コレクションは vector 、との 2 つのグループで構成されます raster。 raster レイヤーのグループは、 HTML5 カンバスレンダリングと WebGL レンダリングの両方で使用できますが vector 、グループには WebGL レンダリングでのみ使用されるレイヤーが含まれています。次の擬似コードは、オブジェクトの新しい構造を示しています。

{
raster: {
  normal: {
    base: <Layer>,
    basenight: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    mapnight: <Layer>,
    trafficincidents: <Layer>,
    transit: <Layer>,
    xbase: <Layer>,
    xbasenight: <Layer>
  },
  satellite: {
    base: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    xbase: <Layer>
  },
  terrain: {
    base: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    xbase: <Layer>
  }
},
vector: {
  normal: {
    map: <Layer>,
    traffic: <Layer>,
    trafficincidents: <Layer>
  }
}
}

既定のレイヤーコレクションの構造の変更は、作成方法に影響 H.ui.MapSettingsControl します。以前のバージョンの API では、次のコードを使用してカスタム地図設定コントロールを作成しました。

// 'maptypes' variable holds the result of the H.service.Platform#createDefaultLayers call
var mapSettings = new H.ui.MapSettingsControl({
  alignment: 'top-right',
  entries: [{
    name: 'Normal map',
    mapType: maptypes.normal
  }]
});
ui.addControl('mapsettings', mapSettings);

API の新バージョンで options は、関連付け baseLayers られているラベルが H.ui.MapSettingsControl.Entry typedef として定義されたの配列を受け入れるようにパラメータが変更されました。

// 'maptypes' variable holds the result of the H.service.Platform#createDefaultLayers call
var mapSettings = new H.ui.MapSettingsControl({
  alignment: 'top-right',
  baseLayers: [{
  label: 'Normal map',
  layer: maptypes.raster.normal.map
  }]
});
ui.addControl('mapsettings', mapSettings);

非同期の "getObjectAt" インターフェイス

H.Map#getObjectAt 指定した XY 画面座標でマップオブジェクトを取得するメソッドの署名と動作が変更されました。 API のバージョン 3.1 では、このメソッドは非同期であり、 3 番目のパラメータとしてコールバックを受け入れます。たとえば、古いバージョンでは、マップオブジェクトを同期的に取得できました。

// Provided that map is instantiated and there are some markers
// on the map that must be inspected.
var obj = map.getObjectAt(0, 0);
if (obj && obj instanceof H.map.Marker) {
    console.log(obj.getPosition());
}

新しいバージョンでは、コールバックで同じコードを実行する必要があります。

// Provided that map is instantiated and there are some markers
// on the map that must be inspected.
map.getObjectAt(0, 0, (obj) => {
    if (obj && obj instanceof H.map.Marker) {
        console.log(obj.getGeometry());
    }
});

"LookAt" インターフェイス

H.map.ViewModel.CameraData インターフェイスに関連する機能が廃止されました。に関連するメソッドによって、同様の機能が提供さ H.map.ViewModel.ILookAtDataれます。次の方法は利用できなくなりました。

H.map.ViewModel#getCameraData
H.map.ViewModel#setCameraData
H.Map#screenToCameraData

廃止されたメソッドは、それぞれ次のメソッドに置き換えられました。

H.map.ViewModel#getLookAtData
H.map.ViewModel#setLookAtData
H.Map#screenToLookAtData

このメソッド H.Map#getCameraDataForBound は廃止され、削除されました。対応する機能は H.map.ViewModel.ILookAtData#bounds 、マップの傾きや回転など、表示されている境界を表すジオメトリが含まれているプロパティを介して利用できます。廃止されたメソッド H.map.ViewModel#setZoom およびにも同じ内容が適用さ H.map.ViewModel#getZoomれます。 H.map.ViewModel.ILookAtData#zoom これらの機能は、施設を通して実現できるようになりました。

LookAt インターフェイスの変更も H.Map クラスに影響しました。メソッド H.Map#setViewBounds、H.Map#getViewBoundsおよび H.Map#getCameraDataForBounds は廃止され、代わりにH.map.ViewModelへの直接呼び出しを使用する必要があります。

分数ズームレベル

HERE Maps API for Javascript の新しいレンダリングエンジンでは、ズームレベルの微調整がサポートされているため、エンドユーザーでマップをより適切に制御できます。デフォルトでは、フラクショナル・ズーム・レベルが有効になっています。たとえば、ラスタベースのオーバーレイやレガシーアプリケーションの場合、必要に応じてこの機能を無効にできます。次のコードスニペットで H.mapevents.Behavior は、インスタンスおよび UI でズームレベルの一部を無効 ZoomControlにする方法を示します。

// Provided that the map, UI and mapevents behavior are instantiated

// disable fractional zooming for Behavior
behavior.disable(H.mapevents.Behavior.Feature.FRACTIONAL_ZOOM);

// instantiate H.ui.ZoomControl with the disabled fractional zooming
// and add it to the UI
var zoomControl = new H.ui.ZoomControl({fractionalZoom: false});
ui.addControl('zoom', zoomControl);

「ストリートレベル」および「撮影地」モジュール

HERE Maps API for Javascript のバージョン 3.1 では、ストリートレベルのイメージ () およびmapsjs-pano.js専用の場所 ()mapsjs-places.jsモジュールを担当するモジュールは廃止されました。 Places REST API 機能は、mapsjs-service.jsモジュールの対応するクラスで利用できますが、ストリートレベルイメージは廃止され、 JavaScript API から削除されました。 H.Map#event:enginechangeおよびH.Map#setEngineTypeなどのレンダリングエンジンの切り替えに関連する関数が、ストリートレベルの UI 要素と一緒に削除されました (H.ui.Pano) 。

交通事故および交通フローサービス

H.service.TrafficIncidentsProvider および H.service.TrafficIncidentsService の名前が変更され、新しい名前空間 : H.service.traffic.incidents.ProviderおよびH.service.traffic.Serviceに移動されました。これらのクラスの機能は変更されませんでした。

また、 HERE Maps API for Javascript バージョン 3.1 では、新しい WebGL レンダリングエンジンと互換性のあるマップ上の Traffic REST API によって提供されたトラフィックフロー情報を表示する新しい推奨方法が提供されています。古いアプローチでは、データはサーバー側のイメージとしてプレレンダリングされていましたが、新しい方法ではベクトルレンダリングを使用して、レンダリングされたデータとのやり取りを可能にします。次のコード例では、トラフィックサービスの新しいインスタンスが作成され、マップ上のデータの表示に使用されるトラフィックフロープロバイダの作成に使用されます。

// Provided that map and platform objects are instantiated.
// Create a traffic service and a corresponding provider.
var service = platform.getTrafficService()
var provider = new H.service.traffic.flow.Provider(service)

// Create a tile layer that can be added to the map
var layer = new H.map.layer.TileLayer(provider);
map.addLayer(layer);

図形と地図オブジェクト

ジオメトリバウンディングボックスの計算に関連する次のメソッドの名前が変更されました。メソッドのシグネチャは変更されません。

H.geo.AbstractGeometry#getBounds に名前が変更されまし H.geo.AbstractGeometry#getBoundingBox
H.geo.Point#getBounds に名前が変更されまし H.geo.Point#getBoundingBox
H.geo.Rect#getBounds に名前が変更されまし H.geo.Rect#getBoundingBox
H.geo.LineString#getBounds に名前が変更されまし H.geo.LineString#getBoundingBox
H.geo.MultiGeometry#getBounds に名前が変更されまし H.geo.MultiGeometry#getBoundingBox
H.geo.MultiLineString#getBounds に名前が変更されまし H.geo.MultiLineString#getBoundingBox
H.geo.Polygon#getBounds に名前が変更されまし H.geo.Polygon#getBoundingBox
H.geo.MultiPolygon#getBounds に名前が変更されまし H.geo.MultiPolygon#getBoundingBox
H.geo.MultiPoint#getBounds に名前が変更されまし H.geo.MultiPoint#getBoundingBox

このクラス H.geo.Strip は HERE Maps API for Javascript 3.0 で廃止され、新しいバージョンで削除 H.geo.LineString されました。代わりに使用してください。それぞれ、マップオブジェクトのバウンディングボックスの計算を担当するメソッドが調整されました。

H.map.Circle#getBounds 名前が変更され to H.map.Circle#getBoundingBox
H.map.GeoShape#getBounds に名前が変更されまし H.map.GeoShape#getBoundingBox
H.map.Group#getBounds に名前が変更されまし H.map.Group#getBoundingBox
H.map.Overlay#getBounds に名前が変更されまし H.map.Overlay#getBoundingBox
H.map.Polygon#getBounds に名前が変更されまし H.map.Polygon#getBoundingBox
H.map.Polyline#getBounds に名前が変更されまし H.map.Polyline#getBoundingBox
H.map.Rect#getBounds に名前が変更されまし H.map.Rect#getBoundingBox
H.clustering.ICluster#getBounds に名前が変更されまし H.clustering.ICluster#getBoundingBox

基本となるジオメトリを設定および取得するマップオブジェクトのメソッドが変更され、異なるジオメトリでオブジェクトを作成できることが反映されました。形状を取得するには、次のように変更します。

H.map.AbstractMarker#getPosition に名前が変更されまし H.map.AbstractMarker#getGeometry
H.map.Circle#getStrip に名前が変更されまし H.map.Circle#getGeometry
H.map.DomMarker#getPosition に名前が変更されまし H.map.DomMarker#getGeometry
H.map.GeoShape#getStrip に名前が変更されまし H.map.GeoShape#getGeometry
H.map.Marker#getPosition に名前が変更されまし H.map.Marker#getGeometry
H.map.Polygon#getStrip に名前が変更されまし H.map.Polygon#getGeometry
H.map.Polyline#getStrip に名前が変更されまし H.map.Polyline#getGeometry
H.map.Rect#getStrip に名前が変更されまし H.map.Rect#getGeometry

形状を設定するには、次のように変更します。

H.map.AbstractMarker#setPosition に名前が変更されまし H.map.AbstractMarker#setGeometry
H.map.Circle#setStrip に名前が変更されまし H.map.Circle#setGeometry
H.map.DomMarker#setPosition に名前が変更されまし H.map.DomMarker#setGeometry
H.map.GeoShape#setStrip に名前が変更されまし H.map.GeoShape#setGeometry
H.map.Marker#setPosition に名前が変更されまし H.map.Marker#setGeometry
H.map.Polygon#setStrip に名前が変更されまし H.map.Polygon#setGeometry
H.map.Polyline#setStrip に名前が変更されまし H.map.Polyline#setGeometry
H.map.Rect#setStrip に名前が変更されまし H.map.Rect#setGeometry

マップオブジェクトのメソッド名に前述の変更が加えられたほか、関連するすべてのイベントが廃止され、削除されました。具体的には、次のとおりです。

visibilitychange
zindexchange
stylechange
stripchange

JavaScript for Maps API 3.1 への移行

JavaScript for Maps API 3.1 への移行

「 app_id 」および「 app_code 」ではなく API キー

レガシーモジュール

既定のエンジンとしての WebGL

デフォルトのレイヤーコレクション

非同期の "getObjectAt" インターフェイス

"LookAt" インターフェイス

分数ズームレベル

「ストリートレベル」および「撮影地」モジュール

交通事故および交通フローサービス

図形と地図オブジェクト

「」に一致する結果は件です

「」に一致する結果はありません

開発者

JavaScript for Maps API 3.1 への移行

「 app_id 」および「 app_code 」ではなく API キー

レガシーモジュール

既定のエンジンとしての WebGL

デフォルトのレイヤーコレクション

非同期の "getObjectAt" インターフェイス

"LookAt" インターフェイス

分数ズームレベル

「ストリートレベル」および「撮影地」モジュール

交通事故および交通フローサービス

図形と地図オブジェクト

「」に一致する結果は 件です

「」に一致する結果はありません

開発者

「」に一致する結果は件です