ドキュメント / 基本 / マーカー

マーカー

マーカーは状態オブジェクトを1つ作って地図ビューに置くだけです。描画は SDK 内部のレンダリングエンジンが担当し、件数に応じて描き方を自動で切り替えます。既定では 2,000個までが各地図SDKの標準マーカー、それを超えるとラスタータイルです。この基準値は地図ビューにタイル描画オプションを渡して変更できます。

ANDROID

com.mapconductor:core

iOS

MapConductorCore

REACT

@mapconductor/js-sdk-react

デモを見るマーカーアイコン · React ↗

プラットフォーム

01 · マーカーの状態

MarkerState が1つのマーカーを表します。位置・アイコン・イベント・任意の付随データを持ち、プロパティを書き換えれば即座に反映されます。プロバイダごとの型はありません。

MarkerState · Jetpack Compose

val marker =
    MarkerState(
        position = GeoPoint.fromLatLong(21.3069, -157.8583),
        icon = DefaultMarkerIcon(fillColor = Color.Red, label = "A"),
        extra = postOffice,
        onClick = { clicked -> viewModel.onMarkerClick(clicked) },
    )

// 位置やアイコンは後から書き換えるだけで再描画される
marker.position = nextPoint

MarkerState · SwiftUI

let marker = MarkerState(
    position: GeoPoint.fromLatLong(latitude: 21.3069, longitude: -157.8583),
    icon: DefaultMarkerIcon(fillColor: .red, label: "A"),
    extra: postOffice,
    onClick: { clicked in viewModel.onMarkerClick(clicked) }
)

content.markers = markerStates.map { Marker(state: $0) }

MarkerIconsPage.tsx

const marker = createMarkerState({
  id: 'post-office-1',
  position: createGeoPoint({ latitude: 21.3069, longitude: -157.8583 }),
  icon: new ColorDefaultIcon({ fillColor: '#e74c3c', label: 'A' }),
  extra: postOffice,
  onClick: setSelected,
});

<Markers states={markerStates} />

プロパティ

説明

position

緯度経度。書き換えるとマーカーが移動します。

icon

アイコン。未指定なら既定のピン。

extra

任意の付随データ。クリック時に受け取って情報バブルなどに使います。

clickable / draggable

タップ可否とドラッグ可否。

zIndex

重なり順。マーカー個別の既定は3プラットフォームとも未設定（null）で、未設定のときは緯度順に自動で重なります。マーカーレイヤー全体は 10 に置かれます。

onClick / onDrag…

タップ・ドラッグ・アニメーション開始終了のハンドラ。

02 · アイコン

既定のピンに色やラベルを載せるだけの指定から、画像・キャンバス、吹き出し型アイコンまで用意しています。どのアイコンもプロバイダをまたいで同じ見た目になります。

ColorDefaultIcon

色・枠線・ラベル・倍率を指定できる標準ピン。iOS では DefaultMarkerIcon という名前です（Android では DefaultMarkerIcon が ColorDefaultIcon の別名として使えます）。

ImageIcon / ImageDefaultIcon

画像やビットマップをそのままアイコンにします。アンカー位置も指定可能。Android にはさらに Drawable を直接渡せる DrawableDefaultIcon があります。

CircleIcon / FlagIcon

円形・旗型のシンプルな図形アイコン（icons パッケージ）。

RoundInfoBubbleIcon

アイコンとラベルを丸い吹き出しに収めた形。価格表示などに。

RightTailInfoBubbleIcon

右向きのしっぽ付き吹き出し。ラベルとサブテキストの2行。

scale · anchor · debug

倍率、アンカー、当たり判定を可視化するデバッグ表示は全アイコン共通のオプション。

03 · 内部のレンダリングエンジン

マーカーの描画は SDK 内部のレンダリングエンジンに任せています。件数が少ないうちは各地図SDKの標準マーカーをそのまま使い、ネイティブのタップ判定やアニメーションをそのまま活かします。

マーカーが 2,000個を超えると、エンジンは描き方を切り替えます。マーカー群をタイル画像としてレンダリングし、ラスターレイヤーとして重ねることで、ネイティブSDKへの1件ずつの追加・更新コストをなくします。アプリ側のコードは何も変わりません。

図 · 件数で描き方が切り替わる

≤ 2,000

標準マーカーで描画

各地図SDKのマーカーを1件ずつ生成。タップ・ドラッグ・アニメーションはネイティブの挙動そのまま。

2,000+

> 2,000

ラスタータイルで描画

マーカー群をタイル画像として描き、ラスターレイヤーとして重ねます。1件ずつの追加・更新が消えるため、数万件でもカメラ操作が滑らかです。

切り替えは自動です。基準値は既定で 2,000個。地図ビューにこのオプション（Android は markerTiling、iOS・React は markerTilingOptions）を渡せば minMarkerCount を変えられ、タイルキャッシュやズームごとのアイコン倍率も同じオプションで調整できます。Disabled にすれば常に標準マーカーで描画します。

サンプル動画 · マーカーのタイル描画

minMarkerCount

2000 · 変更可

cacheSize

8 MB

enabled

true

debugTileOverlay

false

PostOfficeViewModel.kt · 24,526 件

// 既定で有効。地図ビューに渡して基準値を変える（Android の引数名は markerTiling）
val markerTiling =
    MarkerTilingOptions.Default.copy(
        minMarkerCount = 500, // 500件からタイル描画に切り替える
        iconScaleCallback = { _, zoom ->
            if (zoom > 10) 0.8 else if (zoom > 5) 0.5 else 0.2
        },
    )

GoogleMapView(state = mapViewState, markerTiling = markerTiling) { /* markers */ }

// 常に標準マーカーで描かせたいときは無効化する
val plain = MarkerTilingOptions.Disabled

PostOfficeMapComponent.swift · 24,526 件

var content = MapViewContent()
content.markerTilingOptions = MarkerTilingOptions(
    minMarkerCount: 500, // 500件からタイル描画に切り替える
    iconScaleCallback: { _, zoom in
        PostOfficeViewModel.iconScale(zoom: zoom)
    }
)
content.markers = markers.map { Marker(state: $0) }

PostOfficePage.tsx · 24,526 件

const MARKER_TILING_OPTIONS: MarkerTilingOptions = {
  ...MarkerTilingOptions.Default,
  minMarkerCount: 500, // 500件からタイル描画に切り替える
  iconScaleCallback: (_state, zoom) => (zoom > 10 ? 0.8 : zoom > 5 ? 0.5 : 0.2),
};

<PostOfficeMapProvider markerTilingOptions={MARKER_TILING_OPTIONS}>
  <Markers states={markerStates} />
</PostOfficeMapProvider>

SPATIAL INDEX

空間インデックスで探す

大量のマーカーを持つときは六角セルの空間インデックスを使い、表示範囲内のマーカー抽出やタップ判定を件数に依存しない速さで行います。少数のときは総当たりのほうが速いので、そちらを使います。

CLUSTERING

クラスタリングは別モジュール

近接マーカーをまとめて1つのバッジにする「マーカーを大量に置く（クラスタリング）」は追加モジュールです。ここで説明したタイル描画は標準機能で、クラスタリングとは独立して働きます。

04 · アニメーション

簡易的なアニメーションを標準で用意しています。生成時に指定するか、あとから animate() を呼ぶだけです。開始・終了はハンドラで受け取れます。

MarkerAnimation.Drop

上から落下して着地するアニメーション。検索結果の表示などに。

MarkerAnimation.Bounce

その場で跳ねるアニメーション。選択中の強調に。

AnimationPageViewModel.kt

// 生成時に指定するか、あとから animate() を呼ぶ
MarkerState(position = point, animation = MarkerAnimation.Bounce)

override fun onMarkerClick(clicked: MarkerState) {
    clicked.animate(clicked.extra as? MarkerAnimation)
}

AnimationPageViewModel.swift

if let animation = clicked.extra as? MarkerAnimation {
    clicked.animate(animation)
}

MarkerAnimationPage.tsx

const marker = createMarkerState({
  id: 'animated-marker',
  position: HONOLULU,
  animation,
  onClick: state => state.animate(MarkerAnimation.Bounce),
});

アニメーション中のマーカーは専用のオーバーレイで描画されるため、タイル描画に切り替わっている状態でも動きます。所要時間は SDK の設定で変更できます。