メインコンテンツまでスキップ

Set a style

追加の開発者リソース

Across the Mapbox ecosystem, the appearance of the map is determined by the map style. A Mapbox style is a JSON object that defines exactly how to draw a map. It defines almost everything related to a map's appearance. In the Maps SDK, you will set the style of the map after initializing the map view.

Choose a style​

The style you choose for your application should reflect how your users will interact with the map and what they will use your application for. If you are not sure what style is right for you, we recommend getting started with the carefully designed, all-purpose Mapbox Standard style.

Load a style​

The Maps SDK’s MapView provides an embeddable map interface. You can embed the map inside a view, allowing users to manipulate it with gestures and more. To render a map in the MapView, you will need to determine which style the renderer should use. You can rely on the default Mapbox Standard loaded by default. Or you can initialize the map view with constructor by styleUri property of MapInitOptions. Moreover you can load a style at any time after the map has been initialized using one of MapboxMap’s style loading methods.

Mapbox Standard​

Mapbox Standard is the default style, and instantiating a MapView without specifying any style means your map will use Mapbox Standard.


// Loads Mapbox Standard Style by default.
mapView.mapboxMap.getStyle { style ->
  // default style is loaded
}

To explicitly set Mapbox Standard as the style for your map you can use the Style.STANDARD constant like below:


mapboxMap.loadStyle(Style.STANDARD)

Classic style templates and custom styles​

If you don’t use Mapbox Standard, you can load the style when you first initialize the map view by specifying the style in MapInitOptions and passing the options to MapView. Alternately, you can set the style at any time after the map has been initialized using one of MapboxMap’s loadStyle methods. If you want to avoid loading Mapbox Standard style by default you should call loadStyle method with your style until a Fragment or an Activity hosted MapView is in a started state.

You can also define the default style while adding the MapView to the layout using XML attribute mapbox_styleUri to load a Mapbox-hosted style using a style URL.

If you want first to initialize the MapView but load the style later, after the map is displayed on the UI, you can set null to the styleUri of MapInitOptions or pass an empty string to loadStyle methods. This approach will prevent Mapbox Standard style from loading right away.


// set styleUri to null method
MapView(context, MapInitOptions(context = context, styleUri = null))
// pass empty string method
mapboxMap.loadStyle("")

In the case above, MapView is rendered with solid black background color by default. But, if you want to adjust the color of the map's background to fit your design before your style is loaded to the MapView, you can set JSON string with a style with only one desired color to MapInitOptions or pass it to loadStyle methods


@Language("JSON")
    private const val BLANK_STYLE = """
{
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {"background-color": "hsl(100, 50%, 50%)"}
    }
  ]
}
"""

MapView(context, MapInitOptions(context = context, styleUri = BLANK_STYLE))
// or
mapboxMap.loadStyle(BLANK_STYLE)

If you are using a Mapbox-designed style, you can use these convenience variables instead of the full style URL. This will also make sure you're using the latest version of the style:

  • Mapbox Standard: Style.STANDARD
  • Mapbox Standard Satellite: Style.STANDARD_SATELLITE
  • Mapbox Streets: Style.MAPBOX_STREETS
  • Mapbox Outdoors: Style.OUTDOORS
  • Mapbox Satellite: Style.SATELLITE
  • Mapbox Satellite Streets: Style.SATELLITE_STREETS
  • Mapbox Light: Style.LIGHT
  • Mapbox Dark: Style.DARK
  • Mapbox Traffic Day: Style.TRAFFIC_DAY
  • Mapbox Traffic Night: Style.TRAFFIC_NIGHT
Use loadStyleJson
Though less common, you can also use MapboxMap’s loadStyleJson to load a style if you've written style JSON manually.
Switch styles at runtime

You can also change the style any time after initializing the map using any of loadStyle methods described above. If you added any layers at runtime, you will need to re-add layers after the new style is loaded or try using the new addPersistentLayer when adding any layers to the initial style.

For Jetpack Compose users, you can change the whole MapboxStyleComposable block to switch between customized styles or strongly typed MapboxStandardStyle or MapboxStandardSatelliteStyle. Layers added to slot or layer position of the MapboxStyleComposable will be added as normal layers once the style is loaded and layers added to the MapboxMap content will be added as persistent layer across different styles.

Configure a style​

Depending on what map style you choose, you have different configuration options available to customize aspects of your style such as fonts, colors, and more.

Mapbox Standard​

The underlying design paradigm to Mapbox Standard or Mapbox Standard Satellite is different from what you know from the classic styles templates. We’re establishing the concept of a basemap; Mapbox Standard being the first to follow this paradigm. You can consider everything that is maintained by Mapbox (natural features, roads, buildings etc.) as the basemap into which you embed your custom layers. The differentiation is important because different rules apply to the basemap and custom layers.

To change the visual appearance of the Standard basemap, you need to use the setStyleImportConfigProperty method. Mapbox Standard offers 8 configuration properties that can be used to change the appearance of the basemap using setStyleImportConfigProperty:

PropertyTypeDescription
showPlaceLabelsBoolShows and hides place label layers.
showRoadLabelsBoolShows and hides all road labels, including road shields.
showPointOfInterestLabelsBoolShows or hides all POI icons and text.
showTransitLabelsBoolShows or hides all transit icons and text.
show3dObjectsBoolShows or hides all 3d layers (3D buildings, landmarks, trees, etc.) including shadows, ambient occlusion, and flood lights. Important: configuration available starting from v11.5.1 SDK
themeStringSwitches between 3 themes: default, faded and monochrome. Important: configuration available starting from v11.5.1 SDK
lightPresetStringSwitches between 4 time-of-day states: dusk, dawn, day, and night.
fontStringDefines font family for the style from predefined options.

Here’s an example illustrating how to switch the 3D lights from the default preset, day, to another preset, dusk.


mapboxMap.loadStyle(Style.STANDARD) { style ->
  style.setStyleImportConfigProperty(styleImportId, "lightPreset", Value.valueOf("dusk"))
}

Similarly, you can set other configuration properties on the Standard style such as showing POIs, place labels, or specific fonts:


mapboxMap.loadStyle(Style.STANDARD) { style ->
  style.setStyleImportConfigProperty(styleImportId, "showPointOfInterestLabels", Value.valueOf(false))
}

Other options to customize your map using Mapbox Standard are by configuring root properties, or styling your custom data such that it reflects your personal preferences. Note that all the configurations are also available in the Mapbox Studio.

For custom layers that you add to the Mapbox Standard basemap, all configuration options are defined in the Mapbox Style Specification.

Mapbox Standard Satellite​

The Standard Satellite Style (mapbox://styles/mapbox/standard-satellite) combines updated satellite imagery and vector layers to offer users improved clarity and detail. Like Standard style, the Satellite Style receives all updates automatically and also supports light presets. Additionally, it introduces two new configurations showRoadsAndTransit and showPedestrianRoads. Users can now choose to hide roads, simplifying the map style for a better focus on specific areas or features.

The Standard Satellite style offers 8 configuration properties for developers to change when they import it into their own style:

PropertyTypeDescription
showRoadsAndTransitBoolShows and hides all roads and transit networks.
showPedestrianRoadsBoolShows and hides all pedestrian roads, paths, trails.
showPlaceLabelsBoolShows and hides place label layers.
showRoadLabelsBoolShows and hides all road labels, including road shields.
showPointOfInterestLabelsBoolShows or hides all POI icons and text.
showTransitLabelsBoolShows or hides all transit icons and text.
lightPresetStringSwitches between 4 time-of-day states: dusk, dawn, day, and night.
fontStringDefines font family for the style from predefined options.

Important: Standard satellite style doesn't support theme and show3dObjects configuration.

Style imports​

To work with styles like Mapbox Standard or Standard Satellite, we've introduced Style APIs that allow you to import other styles into the main style you display to your users. These styles will be imported by reference, so updates to them will be reflected in your main style without additional work needed on your side. For example, imagine you have style A and style B. The Style API will allow you to import A into B. Upon importing, you can set configurations that apply to A and adjust them at runtime. The configuration properties for the imported style A will depend on what the creator of style A chooses to be configurable. For the Standard style, 8 configuration properties are available for setting lighting, fonts, and label display options. To import a style, you need to add an imports property to your Style JSON. In the above example, you would add "imports" to your Style JSON for B to import style A and set various configurations as defined in style A in the schema root property.

...
"imports": [
    {
        "id": "A",
        "url": "STYLE_URL_FOR_A",
        "config": {
            "font": "Montserrat",
            "lightPreset": "dusk",
            "theme: "faded",
            "show3dObjects": true,
            "showPointOfInterestLabels": true,
            "showTransitLabels": false,
            "showPlaceLabels": true,
            "showRoadLabels": false
        }
    }
],
...

For a full example of importing a style, have a look at our Standard Style Example. This example imports the Standard style into another style Real Estate New York.

The Style object provides the following APIs so you can work with these features:

  • style.styleImports, which returns all the styles you have imported into your main style
  • style.removeStyleImport(), which removes the style import with the passed Id
  • style.getStyleImportSchema(), which returns the full schema describing the style import with the passed Id
  • style.getStyleImportConfigProperties(), which returns all the configuration properties of the style import with the passed Id
  • style.getStyleImportConfigProperty(), which returns the specified configuration property of the style import with the passed Id
  • style.setStyleImportConfigProperties(), which sets all the configuration properties of the style import with the passed Id
  • style.setStyleImportConfigProperty(), which sets the specified configuration property of the style import with the passed Id

Classic style templates and custom styles​

The configuration options for classic style templates and custom styles are defined in the Mapbox Style Specification. Note that all the configurations are also available in the Mapbox Studio.

追加の開発者リソース
この{Type}は役に立ちましたか？