前言

可以使用Mapbox Maps SDK自定义数据样式、调整地图样式、添加字体、创建数据驱动的可视化等。可以使用Mapbox Standard、Mapbox Standard Satellite，或通过调整地图的颜色、图标和字体来创建自定义地图样式。

有两种方法可以自定义地图的外观：

• 使用Mapbox Studio创建自定义地图样式。
• 使用Maps SDK在运行时动态更新地图功能。并可以动态切换语言，调整标签大小以提高可读性，根据一天中的时间调暗地图，个性化图标和地图颜色。

本文重点介绍MapBox默认的样式，样式相关的类和方法，以及如何动态更新样式并本地化语言。

MapBox样式对比

主要类和方法

Style类

Style对象是指应用程序中使用的Mapbox地图样式。

classDiagram
    MapboxStyleManager <|-- Style

    class MapboxStyleManager{
        +StyleManager styleManager
    }
    class Style {
    }

Style类

class Style internal constructor(
  styleManager: StyleManager,
  pixelRatio: Float,
  mapLoadingErrorDelegate: MapLoadingErrorDelegate,
) : MapboxStyleManager(styleManager, pixelRatio, mapLoadingErrorDelegate) {

  @Volatile
  private var isStyleValid = true
  
  /**
   * Returns the existing style layers.
   *
   * @return The list containing the ids of the existing style layers.
   */
  override val styleLayers: List<StyleObjectInfo>
    @MainThread
    get() {
      checkNativeStyle("getStyleLayers")
      return super.styleLayers
    }
    ...
}

• MapboxStyleManager 类

open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) constructor(
  /**
   * Native style manager instance.
   */
  @get:RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
  val styleManager: StyleManager,
  /**
   * Current pixel ratio.
   */
  val pixelRatio: Float,
  /**
   * For internal usage.
   */
  @get:RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
  val mapLoadingErrorDelegate: MapLoadingErrorDelegate,
) {
  }
  ...
}

• StyleManager 类

public class StyleManager extends Observable {
    @MainThread
    public native boolean isStyleLoaded();

    @MainThread
    public native boolean styleLayerExists(@NonNull String layerId);

    @NonNull
    @MainThread
    public native List<StyleObjectInfo> getStyleLayers();
    ...
}

默认的MapBox样式

const val STANDARD = "mapbox://styles/mapbox/standard"
const val STANDARD_SATELLITE = "mapbox://styles/mapbox/standard-satellite"
const val MAPBOX_STREETS = "mapbox://styles/mapbox/streets-v12"
const val OUTDOORS = "mapbox://styles/mapbox/outdoors-v12"
const val LIGHT = "mapbox://styles/mapbox/light-v11"
const val DARK = "mapbox://styles/mapbox/dark-v11"
const val SATELLITE = "mapbox://styles/mapbox/satellite-v9"
const val SATELLITE_STREETS = "mapbox://styles/mapbox/satellite-streets-v12"
const val TRAFFIC_DAY = "mapbox://styles/mapbox/traffic-day-v2"
const val TRAFFIC_NIGHT = "mapbox://styles/mapbox/traffic-night-v2"

OnStyleLoaded 接口

/**
 * Callback to be invoked when a style has finished loading.
 */
fun interface OnStyleLoaded {
  /**
   * Invoked when a style has finished loading.
   *
   * @param style the style that has finished loading
   */
  fun onStyleLoaded(style: Style)
}

MapboxMap类

获取样式

var style: Style? = null
  @JvmSynthetic
  internal set
  get() {
    checkNativeMap("getStyle")
    return field
  }

设置样式

@JvmOverloads
fun loadStyle(
  style: String,
  onStyleLoaded: Style.OnStyleLoaded? = null,
) {
  checkNativeMap("loadStyle")
  initializeStyleLoad(
    onStyleLoaded,
    styleDataStyleLoadedListener = {},
  )
  applyStyle(style)
}

private fun applyStyle(style: String) {
  if (style.isValidUri()) {
    nativeMap.setStyleURI(style)
  } else {
    nativeMap.setStyleJSON(style.ifBlank { "{}" })
  }
}

本地化扩展

com.mapbox.maps.extension.localization包中实现了本地化功能，这种方法不支持standard样式。主要实现代码如下：

@JvmOverloads
fun MapboxStyleManager.localizeLabels(locale: Locale, layerIds: List<String>? = null) {
  if (styleURI == "mapbox://styles/mapbox/standard") {
    throw RuntimeException(
      "Mapbox Standard style does not support client-side runtime localization." +
        " Consider using Mapbox internationalization capability instead: https://www.mapbox.com/blog/maps-internationalization-34-languages"
    )
  }
  setMapLanguage(locale, this, layerIds)
}

internal fun setMapLanguage(locale: Locale, style: MapboxStyleManager, layerIds: List<String>?) {
  val convertedLocale = "name_${locale.language}"
  if (!isSupportedLanguage(convertedLocale)) {
    logE(TAG, "Locale: $locale is not supported.")
    return
  }

  layerIds?.forEach { id ->
    localizeTextFieldExpression(
      style = style,
      layerId = id,
      locale = locale,
      convertedLocale = convertedLocale,
      filterSymbolLayers = true,
    )
  } ?: style.styleLayers.forEach { layer ->
    if (layer.type == SYMBOL) {
      localizeTextFieldExpression(
        style = style,
        layerId = layer.id,
        locale = locale,
        convertedLocale = convertedLocale,
        filterSymbolLayers = false,
      )
    }
  }
}

private fun localizeTextFieldExpression(
  style: MapboxStyleManager,
  layerId: String,
  locale: Locale,
  convertedLocale: String,
  filterSymbolLayers: Boolean,
) {
  if (filterSymbolLayers) {
    val type = style.getStyleLayerProperty(layerId, TYPE).value.contents as? String
    if (type != SYMBOL) {
      return
    }
  }
  val textFieldProperty = style.getStyleLayerProperty(layerId, TEXT_FIELD)
  if (textFieldProperty.kind != StylePropertyValueKind.EXPRESSION) {
    return
  }
  val textField = textFieldProperty.value.toJson()
  val adaptedLocale = adaptLocaleToV8orV7IfNeeded(
    style,
    style.getStyleLayerProperty(layerId, SOURCE).value.contents as? String ?: "",
    locale
  ) ?: convertedLocale
  val getExpression = get(adaptedLocale).toJson()
  val localizedTextFieldExpressionAsJson = textField.replace(
    EXPRESSION_REGEX,
    getExpression
  ).replace(EXPRESSION_ABBR_REGEX, getExpression)
  if (BuildConfig.DEBUG) {
    logI(TAG, "Localize layer with expression: $localizedTextFieldExpressionAsJson")
  }
  val expected = Value.fromJson(localizedTextFieldExpressionAsJson)
  expected.value?.let { value ->
    style.setStyleLayerProperty(
      layerId,
      TEXT_FIELD,
      value
    )
  } ?: run {
    logE(TAG, "An error ${expected.error} occurred when converting $localizedTextFieldExpressionAsJson to a Value!")
  }
}

示例代码

地图样式类

设置地图样式，样式加载完成后重新本地化地图语言。

package com.example.mapdemo

import com.mapbox.maps.MapboxMap
import com.mapbox.maps.Style
import com.mapbox.maps.extension.localization.localizeLabels
import java.util.Locale

class MapStyle(map: MapboxMap) {
    private var map = map

    fun changeStyle(style: String) {
        map.loadStyle(style) {
            var layers = it.styleLayers
            if (style != Style.STANDARD && style != Style.STANDARD_SATELLITE) {
                it.localizeLabels(Locale.CHINESE)
            }
        }
    }
}

界面布局

v11-0布局.png

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        app:layout_constraintBottom_toTopOf="@id/bottomView"
        app:layout_constraintTop_toTopOf="parent"
        app:mapbox_cameraBearing="0.0"
        app:mapbox_cameraPitch="0.0"
        app:mapbox_cameraTargetLat="32.2857965"
        app:mapbox_cameraTargetLng="104.293174"
        app:mapbox_cameraZoom="2" />

    <HorizontalScrollView
        android:id="@+id/bottomView"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:background="@android:color/background_dark"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintTop_toBottomOf="@id/mapView">

        <RadioGroup
            android:id="@+id/RadioGroup"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:gravity="center_horizontal"
            android:orientation="horizontal"
            android:paddingHorizontal="10dp">

            <RadioButton
                android:id="@+id/standard"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:checked="false"
                android:onClick="setMapStyle"
                android:text="3D基础"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/standardSatellite"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:onClick="setMapStyle"
                android:text="3D影像"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/streets"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:checked="true"
                android:onClick="setMapStyle"
                android:text="基础"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/satellite"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:onClick="setMapStyle"
                android:text="影像"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/satelliteStreets"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:onClick="setMapStyle"
                android:text="影像标签"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/outdoors"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:onClick="setMapStyle"
                android:text="户外"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/light"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:checked="false"
                android:onClick="setMapStyle"
                android:text="浅"
                android:textColor="@color/white"
                android:textStyle="bold" />

            <RadioButton
                android:id="@+id/dark"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:checked="false"
                android:onClick="setMapStyle"
                android:text="深"
                android:textColor="@color/white"
                android:textStyle="bold" />

        </RadioGroup>
    </HorizontalScrollView>
</androidx.constraintlayout.widget.ConstraintLayout>

控件响应事件

fun setMapStyle(view: View) {
    val checked = (view as RadioButton).isChecked
    if (!checked)
        return

    val id = view.getId()
    if (id == R.id.standard) {
        mapStyle.changeStyle(Style.STANDARD)
    } else if (id == R.id.standardSatellite) {
        mapStyle.changeStyle(Style.STANDARD_SATELLITE)
    } else if (id == R.id.streets) {
        mapStyle.changeStyle(Style.MAPBOX_STREETS)
    } else if (id == R.id.satellite) {
        mapStyle.changeStyle(Style.SATELLITE)
    } else if (id == R.id.satelliteStreets) {
        mapStyle.changeStyle(Style.SATELLITE_STREETS)
    } else if (id == R.id.outdoors) {
        mapStyle.changeStyle(Style.OUTDOORS)
    } else if (id == R.id.light) {
        mapStyle.changeStyle(Style.LIGHT)
    } else if (id == R.id.dark) {
        mapStyle.changeStyle(Style.DARK)
    }
}

运行效果图

3D基础	3D影像
v11-A-3D-1基础.png	v11-A-3D-2影像.png
基础	影像	影像+标签
v11-B-1基础.png	v11-B-2影像.png	v11-B-3影像标签.png
户外	浅	深
v11-B-4户外.png	v11-B-5浅.png	v11-B-6深.png

附不同样式中的图层

查看地图样式的图层Z索引顺序和图层ID。