安装与首次显示地图

本指南：在 Android 应用中完成 MapView 依赖接入，并在界面上显示第一张地图。

效果示意：

首次显示地图

第 1 步：添加依赖

在应用模块 build.gradle 的 dependencies 中添加：

dependencies {
    implementation("com.telenav.sdk:telenav-android-mapview-r15c:${tasdk_version}")
}

tasdk_version 须与发行说明一致。完整依赖列表见工程搭建。

第 2 步：在布局中加入 MapView

在 Activity 或 Fragment 布局 XML 中使用默认实现类：

<com.telenav.map.views.TnMapView
    android:id="@+id/map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

第 3 步：初始化 MapView

在 Fragment.onViewCreated 中构建 MapViewInitConfig，并在布局完成后调用 initialize：

import android.location.Location
import android.os.Bundle
import android.view.View
import com.telenav.map.api.MapView
import com.telenav.map.api.MapViewInitConfig
import com.telenav.map.api.MapViewReadyListener
import com.telenav.map.api.ViewOptions
import com.telenav.map.views.TnMapView
import com.telenav.sdk.common.model.DayNightMode

private lateinit var mapView: TnMapView

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    mapView = view.findViewById(R.id.map_view)

    val config = MapViewInitConfig(
        context = requireContext().applicationContext,
        lifecycleOwner = viewLifecycleOwner,
        dpi = mapView.defaultDpi,
        defaultLocation = Location("init").apply {
            // 初始中心点由客户端决定，以下坐标仅为示例
            latitude = 37.3861
            longitude = -122.0839
        },
        readyListener = object : MapViewReadyListener<MapView> {
            override fun onReady(view: MapView?) {
                view ?: return
                onMapReady(view)
            }

            override fun getReadyFeaturesMask(): Int =
                MapView.eFeatureCategory_Vital
        },
        createCvp = true,
        viewOptions = ViewOptions(
            dayNightMode = DayNightMode.DAY,
            stylePath = "styles/default/newstyle.tss"
        )
    )

    mapView.initialize(config)
}

MapViewInitConfig 常用参数

参数	说明
`context`	建议 `applicationContext`
`lifecycleOwner`	绑定生命周期
`dpi`	屏幕显示密度
`defaultLocation`	初始地图中心（由客户端决定，示例坐标仅供参考）
`readyListener`	引擎就绪；此后才能使用 Controller
`createCvp`	是否显示默认车辆图标
`viewOptions`	样式路径、日/夜、最大倾角等

`MapViewInitConfig` 参数说明

MapViewInitConfig(
    context: Context,
    lifecycleOwner: LifecycleOwner,
    dpi: Float = mapView.defaultDpi,
    defaultLocation: LatLon,
    readyListener: MapViewReadyListener<MapView>,
    createCvp: Boolean = true,
    defaultZoomLevel: Float = Camera.DEFAULT_ZOOM_LEVEL,
    autoZoomLevel: AutoZoomLevel = AutoZoomLevel.DEFAULT,
    viewOptions: ViewOptions? = null
)

参数	类型	说明
`context`	`Context`	建议传 `applicationContext`，避免持有 Activity 引用
`lifecycleOwner`	`LifecycleOwner`	宿主 Activity / Fragment 生命周期所有者
`dpi`	`Float`	渲染密度；通常使用 `mapView.defaultDpi` 或 `resources.displayMetrics.density`
`defaultLocation`	`LatLon` / `Location`	初始地图中心点，由客户端按业务场景指定（示例坐标不代表固定值）
`readyListener`	`MapViewReadyListener<MapView>`	地图引擎就绪回调，Controller 应在此后调用
`createCvp`	`Boolean`	是否创建默认 CVP 图标；后续通过自车图标显示更新位置和样式
`defaultZoomLevel`	`Float`	初始缩放级别，默认 `Camera.DEFAULT_ZOOM_LEVEL`
`autoZoomLevel`	`AutoZoomLevel`	导航自动缩放强度，如 `DEFAULT`、`FAR`、`MAXIMUM`
`viewOptions`	`ViewOptions?`	地图视图级渲染选项，包括 `stylePath`、`dayNightMode`、`maxDeclination`

样式与配色详见地图配色方案。

第 4 步：生命周期

在宿主组件中同步调用 MapView 生命周期，否则可能黑屏或泄漏：

override fun onResume() {
    super.onResume()
    mapView.onResume()
}

override fun onPause() {
    mapView.onPause()
    super.onPause()
}

override fun onDestroyView() {
    mapView.onDestroy()
    super.onDestroyView()
}

第 5 步：在 onReady 中配置地图

private fun onMapReady(mapView: MapView?) {
    mapView ?: return

    mapView.getFeaturesController()?.traffic()?.setEnabled()
    mapView.getCameraController()?.zoomLevelRange = android.util.Range(0f, 17f)
    mapView.getVehicleController()?.setLocation(/* 当前定位 */)
}

首帧后再配置

若遇首帧前配置无效，可在 mapView.mapDiagnosis().addMapViewListener 的 onDrawFirstFrame() 中执行上述逻辑，见地图状态监听。

注意事项

先 SDK 全局初始化，再 MapView.initialize。
勿在 onReady 之前调用 getCameraController() 等接口。