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

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, allow users to manipulate it with gestures, and more. For a map to appear in the MapView, the renderer needs a style to determine how to render the map on the screen. You can rely on the default Mapbox Standard style, load a style when you first initialize the map view, or 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.
Map()

Classic style templates and custom styles​

If you don’t use Mapbox Standard, you can load your style by setting mapStyle property with your custom Style URI.


// Loads custom style located at CUSTOM_STYLE_URI.
Map()
  .mapStyle(MapStyle(uri: StyleURI(rawValue: "CUSTOM_STYLE_URI")))

Or, you can use predefined constants to load a Mapbox-designed classic style.


// Loads Mapbox-designed style.
Map()
  .mapStyle(.outdoors)

Using constants will also make sure you’re using the latest version of the style:

Using local Style JSON

Though less common, you can also use MapStyle(json:configuration:) to load a style if you've written style JSON manually. If your style is bundled with the app, use MapStyle(uri:configuration:) with the URI of the Style JSON file.

Switch styles at runtime

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

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 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 MapStyle.standard(...) initializer. Mapbox Standard offers 15 configuration properties that can be used to change the appearance of the basemap:

PropertyTypeDescription
showPedestrianRoadsBoolShows or hides all pedestrian roads, paths, trails.
showPlaceLabelsBoolShows or hides place label layers.
showPointOfInterestLabelsBoolShows or hides all POI icons and text.
showRoadLabelsBoolShows or hides all road labels, including road shields.
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.2 SDK
themeStringSwitches between 4 themes: default, faded, monochrome & custom. Important: configuration available starting from v11.5.2 SDK
theme-dataStringLUT image encoded in Base64 to create a custom color theme. Important: configuration available starting from v11.9.0 SDK
lightPresetStringSwitches between 4 time-of-day states: dusk, dawn, day, and night.
Lights can also be fully customized beyond the presets using the Mapbox style specification.
fontStringDefines font family for the style from predefined options. Options: Alegreya, Alegreya SC, Asap, Barlow, DIN Pro, EB Garamond, Faustina, Frank Ruhl Libre, Heebo, Inter, League Mono, Montserrat, Poppins, Raleway, Roboto, Roboto Mono, Rubik, Source, Code Pro, Spectral, Ubuntu, Noto Sans CJK JP, Open Sans, Manrope, Source Sans Pro, Lato
colorPlaceLabelHighlightColorPlace label color used when setting highlight feature-state. Important: configuration available starting from v11.9.0 SDK
colorPlaceLabelSelectColorPlace label color used when setting select feature-state. Important: configuration available starting from v11.9.0 SDK
colorMotorwaysColorColor override for Motorways.
colorTrunksColorColor override for Trunk Roads.
colorMotorwaysColorColor override for all other roads.

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


struct DynamicStyle: View {
    @State var darkMode = false

    var body: some View {
        Map()
          .mapStyle(.standard(
            lightPreset: darkMode ? .dusk : .day,
            showPointOfInterestLabels: false
          ))
    }
}

The updates of the mapStyle configuration do not require the style reload. The style will be reloaded only when you switch from one style to another, for example, from Standard to Standard Satellite.

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 combines updated satellite imagery and vector layers to offer users improved clarity and detail. Similarly to 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 13 configuration properties for developers to change when they import it into their own style:

PropertyTypeDescription
showRoadsAndTransitBoolShows or hides all roads and transit networks.
showPedestrianRoadsBoolShows or hides all pedestrian roads, paths, trails.
showPlaceLabelsBoolShows or hides place label layers.
showRoadLabelsBoolShows or 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.
colorPlaceLabelHighlightColorPlace label color used when setting highlight feature-state. Important: configuration available starting from v11.9.0 SDK
colorPlaceLabelSelectColorPlace label color used when setting select feature-state. Important: configuration available starting from v11.9.0 SDK
colorMotorwaysColorColor override for Motorways.
colorTrunksColorColor override for Trunk Roads.
colorMotorwaysColorColor override for all other roads.

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, see our Standard Style Example. This example imports the Standard style into another style Real Estate New York. It then modifies the configurations for the imported Standard style at runtime using the following APIs we've introduced on the StyleManager object:

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

Adding interactivity to Standard​

You can use the experimental Featuresets and Interactions API to retrieve basemap attributes and interact with individual features in POI Label, Place Label and building layers in the basemap.

Featuresets describe a collection of layers that can be interacted with in the Standard style, by setting feature-states to change their appearance when interacted with, or to query feature attributes. The following interactions have been added:

  • poi

    • hide feature-state: boolean, when true hides the icon and text. Use this state when displaying a custom annotation in place of the hidden symbol.

  • place-labels

    • hide feature-state: boolean, when true hides the label. Use this state when displaying a custom annotation in place of the hidden symbol.
    • highlight feature-state: boolean, when true, the feature is highlighted. Use this state to create a temporary effect (e.g. hover).
    • Use colorPlaceLabelHighlight to set a custom highlight color.
    • select feature-state: boolean, when true the feature is selected. Use this state to create an effect that persists until another state is selected. Note: the select state has a higher priority than highlight.
    • Use colorPlaceLabelSelect to set a custom select color.

You can see select & highlight in action in this demo page.

Properties available for features returned by each featureset:

  • poi
    • name - Name of the point of interest.
    • class - A broad point of interest category, e.g. 'food_and_drink'.
    • maki - An icon identifier, designed to assign icons using the Maki icon project or other icons that follow the same naming scheme.
    • group - A high-level point of interest category like airport, transit, etc.
    • Available for features with group = transit-label
      • transit_mode - Mode of transport served by a stop/station.
      • transit_stop_type - A type of transit stop.
      • transit_network - A rail station network identifier that is part of specific local or regional transit systems.
    • Available for features with group = airport-label
      • airport_ref - A short identifier code of the airport.
  • place-labels
    • name - Name of the place label.
    • class - Provides a broad distinction between place types.
  • buildings
    • group - A high-level building group like building-2d, building-3d, etc.

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.

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