コンテンツにスキップ
MapConductor

MapViewComponent

MapConductor は、アプリケーションで地図を表示するための基盤となる、地図SDK固有の地図ビューコンポーネントを提供します。各地図SDKには独自の実装がありますが、一貫した API インターフェースを維持しています。

MapViewContainerのアーキテクチャ

MapConductor は、地図SDKが提供するMapViewをラップしたMapViewContainerコンポーネントを提供します。 MapViewComponentは概念で、実際に使うときには地図SDKごとに提供される XxxMapView (例：GoogleMapView, MapBoxView など)を使用します。 MapViewComponentの中にはMapViewを制御するためのコントロールが内包されています。このコントロールはMapViewStateInterfaceを通じて操作することができます。

MapViewComponentのアーキテクチャ

地図SDK固有のコンポーネント

MapConductor は複数の地図SDKをサポートしており、それぞれに専用のコンポーネントがあります。 地図上には通常、複数のオブジェクト（マーカーやポリラインなど）が配置されるため、イベントコールバックは各オーバーレイの State に設定します。

各地図SDK固有の特殊なイベントコールバックについては、v1.1.7 ではまだサポートされていません。

GoogleMapView(
    state: GoogleMapViewState,
    modifier: Modifier = Modifier,
    onMapLoaded: OnMapLoadedHandler? = null,
    onMapClick: OnMapEventHandler? = null,
    onCameraMoveStart: OnCameraMoveHandler? = null,
    onCameraMove: OnCameraMoveHandler? = null,
    onCameraMoveEnd: OnCameraMoveHandler? = null,
    content: (@Composable () -> Unit)? = null
)

共通パラメータ

すべての地図ビューコンポーネントは以下のパラメータを共有しています:

コアパラメータ

  • modifier: スタイリングとレイアウトのための Compose modifier
  • state: 地図SDK固有の地図ビュー状態実装
  • content: 地図オーバーレイ（マーカー、円など）を含む Composable コンテンツ

イベントハンドラ

  • onMapLoaded: 地図の読み込みが完了したときに呼び出されます
  • onMapClick: ユーザーが地図をタップしたときに呼び出されます
  • onCameraMoveStart: moveCameraTo(dst, durationMs)を開始するときに呼び出されます。ユーザーが地図をインタラクティブに動かしたときには呼び出されません。
  • onCameraMove: 地図を表示するカメラが移動したときに呼び出されます。
  • onCameraMoveEnd: 地図を表示するカメラの移動が修了したときに呼び出されます。

高度なパラメータ

  • sdkInitialize: SDK固有の初期化プロセス

使用例

@Composable
fun GoogleMapsExample() {
    val center = GeoPoint.fromLatLong(37.7749, -122.4194)
    val camera = MapCameraPosition(position = center, zoom = 13)


    // ↓↓↓ Use rememberGoogleMapViewState for Google Maps
    val mapViewState = rememberGoogleMapViewState(cameraPosition = camera)


    // ↓↓↓ Use GoogleMapView for Google Maps
    GoogleMapView(
        state = mapViewState,
        onMapClick = { geoPoint ->
            println("Map clicked at: ${geoPoint.latitude}, ${geoPoint.longitude}")
        }
    ) {
        Marker(
            position = GeoPoint.fromLatLong(37.7749, -122.4194),
            icon = ColorDefaultIcon(label = "SF"),
            extra = "San Francisco",
            onClick = { markerState ->
                println("Marker clicked: ${markerState.extra}")
            }
        )


        Circle(
            center = GeoPoint.fromLatLong(37.7749, -122.4194),
            radiusMeters = 1000.0,
            strokeColor = Color.Blue,
            fillColor = Color.Blue.copy(alpha = 0.3f)
        )
    }
}

地図SDKに依存しないパターン

各地図SDKには特定のコンポーネントが必要ですが、地図SDKに依存しないコンテンツを作成できます:

@Composable
fun MapContent() {
    Marker(
        position = GeoPoint.fromLatLong(37.7749, -122.4194),
        icon = ColorDefaultIcon(label = "Point"),
        extra = "Common marker"
    )


    Circle(
        center = GeoPoint.fromLatLong(37.7749, -122.4194),
        radiusMeters = 500,
        strokeColor = Color.Green,
        fillColor = Color.Green.copy(alpha = 0.2f)
    )
}


@Composable
fun GoogleMapsScreen() {
    val state = rememberGoogleMapViewState()
    GoogleMapView(state = state) {
        MapContent() // 再利用可能なコンテンツ
    }
}


@Composable
fun MapboxScreen() {
    val state = remember { MapboxViewState() }
    MapboxMapView(state = state) {
        MapContent() // 同じコンテンツ、異なる地図SDK
    }
}

高度なイベント処理

@Composable
fun AdvancedMapExample() {
    val center = GeoPoint.fromLatLong(37.7749, -122.4194)
    val mapViewState = rememberGoogleMapViewState(
        cameraPosition = MapCameraPosition(position = center, zoom = 13)
    )


    var clickedPoint by remember { mutableStateOf<GeoPointInterface?>(null) }
    val onMarkerClick: (MarkerState) -> Unit = { markerState ->
        println("マーカーがクリックされました: ${markerState.extra}")
    }


    GoogleMapView(
        state = mapViewState,
        onMapLoaded = {
            println("地図の読み込みが完了しました")
        },
        onMapClick = { geoPoint ->
            clickedPoint = geoPoint
            println("地図がクリックされました: ${geoPoint.latitude}, ${geoPoint.longitude}")
        },
        onCameraMoveStart = {
            println("カメラの移動が開始されました")
        },
        onCameraMove = { cameraPosition ->
            println("カメラ位置: ${cameraPosition.position}")
        },
        onCameraMoveEnd = {
            println("カメラの移動が終了しました")
        }
    ) {
        // マーカーと円を表示
        Marker(
            position = center,
            icon = ColorDefaultIcon(label = "中心", fillColor = Color.Red),
            extra = "中心のマーカー",
            onClick = onMarkerClick
        )


        Circle(
            center = center,
            radiusMeters = 1000,
            strokeColor = Color.Blue,
            fillColor = Color.Blue.copy(alpha = 0.2f)
        )


        // クリックされた位置にマーカーを表示
        clickedPoint?.let { point ->
            Marker(
                position = point,
                icon = ColorDefaultIcon(label = "クリック", fillColor = Color.Green),
                extra = "クリックされた位置",
                onClick = onMarkerClick
            )
        }
    }
}

地図SDKの違い

API は全地図SDKで一貫していますが、以下の点で違いがあります:

サポートされる機能

  • GroundImage: 現在 Google Maps と ArcGIS でサポートされています
  • マーカーアニメーション: Google Maps と Mapbox で利用可能
  • カスタムスタイリング: 各地図SDKには異なる地図スタイルオプションがあります

パフォーマンス特性

  • Google Maps: 一般的な使用に優れており、優れたマーカーパフォーマンス
  • Mapbox: カスタムスタイリングと大規模データセットに最適
  • HERE Maps: ロケーションサービス統合に最適化
  • ArcGIS: GIS およびエンタープライズアプリケーションに最適

プラットフォーム統合

各地図SDKには、API キー、パーミッション、プラットフォームセットアップに関して異なる要件がある場合があります。地図SDK固有のセットアップについては、初期化ドキュメントを参照してください。

ベストプラクティス

  1. 適切な地図SDKを選択: アプリの特定のニーズに基づいて選択してください（スタイリング、パフォーマンス、機能）
  2. 一貫した状態管理: 地図SDKに関係なく、同じ状態パターンを使用してください
  3. 再利用可能なコンテンツ: 可能な限り地図SDKに依存しない Composable コンテンツを作成してください
  4. イベント処理: より良いユーザーエクスペリエンスのために包括的なイベント処理を実装してください
  5. エラー処理: 常に初期化の失敗を処理し、フォールバック UI を提供してください
  6. パフォーマンス: 大量のマーカーに対してはカスタムレンダリング戦略の使用を検討してください
  7. テスト: 互換性を確保するために、複数の地図SDKでアプリケーションをテストしてください