# ol-mapbox-style

**Repository Path**: mirrors_SuperMap/ol-mapbox-style

## Basic Information

- **Project Name**: ol-mapbox-style
- **Description**: Use Mapbox Style objects with OpenLayers
- **Primary Language**: Unknown
- **License**: BSD-2-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2025-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ol-mapbox-style

Create OpenLayers maps from Mapbox Style objects.

## Getting started

To use a standalone build of ol-mapbox-style, just include 'dist/olms.js' on your HTML page. Otherwise just import the ol-mapbox-style module, like in the snippet below.

The code below creates an OpenLayers map from Mapbox's Bright v9 style:

```js
import { apply } from 'ol-mapbox-style';

var key = 'Your Mapbox Access Token here';
apply('map', 'https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=' + key);
```

Only commonly available system fonts and [Google Fonts](https://developers.google.com/fonts/) will automatically be available for text defined in the Mapbox Style object. It is the responsibility of the application to load other fonts.

To apply a subset of the layers defined in the Mapbox Style layer to a custom OpenLayers layer, use the `applyStyle()` function.

To apply the properties of the Mapbox Style's `background` layer to the map, use the `applyBackground()` function.

To create a style function for individual OpenLayers vector or vector tile layers, use the `stylefunction` module:

```js
import stylefuction from 'ol-mapbox-style/stylefunction';
// OpenLayers imports from https://npmjs.com/package/ol
import VectorLayer from 'ol/layer/Vector';
import VectorSource from 'ol/source/Vector';
import GeoJSON from 'ol/format/GeoJSON';

var layer = new VectorLayer({
  source: new VectorSource({
    format: new GeoJSON(),
    url: 'data/states.geojson'
  })
});

fetch('data/states.json').then(function(response) {
  response.json().then(function(glStyle) {
    stylefunction(layer, glStyle, 'states');
  });
});
```

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### applyStyle

Applies a style function to an `ol.layer.VectorTile` or `ol.layer.Vector`
with an `ol.source.VectorTile` or an `ol.source.Vector`. The style function
will render all layers from the `glStyle` object that use the specified
`source`, or a subset of layers from the same source. The source needs to be
a `"type": "vector"`, `"type": "geojson"` or `"type": "raster"` source.

**Parameters**

-   `layer` **ol.layer.VectorTile** OpenLayers layer.
-   `glStyle` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** Mapbox Style object.
-   `source` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** `source` key or an array of layer `id`s from the
    Mapbox Style object. When a `source` key is provided, all layers for the
    specified source will be included in the style function. When layer `id`s
    are provided, they must be from layers that use the same source.
-   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of the style file. Only required when
    a relative path is used with the `"sprite"` property of the style. (optional, default `undefined`)
-   `resolutions` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>** Resolutions for mapping resolution to zoom level. (optional, default `undefined`)

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Promise which will be resolved when the style can be used
for rendering.

### applyBackground

Applies properties of the Mapbox Style's first `background` layer to the map.

**Parameters**

-   `map` **ol.Map** OpenLayers Map.
-   `glStyle` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Mapbox Style object.

### apply

Loads and applies a Mapbox Style object to an OpenLayers Map. This includes
the map background, the layers, the center and the zoom.

The center and zoom will only be set if present in the Mapbox Style document,
and if not already set on the OpenLayers map.

Layers will be added to the OpenLayers map, without affecting any layers that
might already be set on the map.

Layers added by `apply()` will have two additional properties:

-   `mapbox-source`: The `id` of the Mapbox Style document's source that the
    OpenLayers layer was created from. Usually `apply()` creates one
    OpenLayers layer per Mapbox Style source, unless the layer stack has
    layers from different sources in between.
-   `mapbox-layers`: The `id`s of the Mapbox Style document's layers that are
    included in the OpenLayers layer.

The map returned by this function will have an additional `mapbox-style`
property which holds the Mapbox Style object.

**Parameters**

-   `map` **(ol.Map | [HTMLElement](https://developer.mozilla.org/docs/Web/HTML/Element) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** Either an existing OpenLayers Map
    instance, or a HTML element, or the id of a HTML element that will be the
    target of a new OpenLayers Map.
-   `style` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** JSON style object or style url pointing to a
    Mapbox Style object. When using Mapbox APIs, the url must contain an access
    token and look like
    `https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=[your_access_token_here]`.
    When passed as JSON style object, all OpenLayers layers created by `apply()`
    will be immediately available, but they may not have a source yet (i.e. when
    they are defined by a TileJSON url in the Mapbox Style document). When passed
    as style url, layers will be added to the map when the Mapbox Style document
    is loaded and parsed.

Returns **ol.Map** The OpenLayers Map instance that will be populated with the
contents described in the Mapbox Style object.

### getLayer

Get the OpenLayers layer instance that contains the provided Mapbox Style
`layer`. Note that multiple Mapbox Style layers are combined in a single
OpenLayers layer instance when they use the same Mapbox Style `source`.

**Parameters**

-   `map` **ol.Map** OpenLayers Map.
-   `layerId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Mapbox Style layer id.

Returns **ol.layer.Layer** layer OpenLayers layer instance.

### getSource

Get the OpenLayers source instance for the provided Mapbox Style `source`.

**Parameters**

-   `map` **ol.Map** OpenLayers Map.
-   `sourceId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Mapbox Style source id.

Returns **ol.layer.Layer** layer OpenLayers layer instance.

### stylefunction

Creates a style function from the `glStyle` object for all layers that use
the specified `source`, which needs to be a `"type": "vector"` or
`"type": "geojson"` source and applies it to the specified OpenLayers layer.

**Parameters**

-   `olLayer` **(ol.layer.Vector | ol.layer.VectorTile)** OpenLayers layer to
    apply the style to. In addition to the style, the layer will get two
    properties: `mapbox-source` will be the `id` of the `glStyle`'s source used
    for the layer, and `mapbox-layers` will be an array of the `id`s of the
    `glStyle`'s layers.
-   `glStyle` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** Mapbox Style object.
-   `source` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** `source` key or an array of layer `id`s
    from the Mapbox Style object. When a `source` key is provided, all layers for
    the specified source will be included in the style function. When layer `id`s
    are provided, they must be from layers that use the same source.
-   `resolutions` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>** Resolutions for mapping resolution to zoom level. (optional, default `[78271.51696402048,39135.75848201024,
    19567.87924100512,9783.93962050256,4891.96981025128,2445.98490512564,
    1222.99245256282,611.49622628141,305.748113140705,152.8740565703525,
    76.43702828517625,38.21851414258813,19.109257071294063,9.554628535647032,
    4.777314267823516,2.388657133911758,1.194328566955879,0.5971642834779395,
    0.29858214173896974,0.14929107086948487,0.07464553543474244]`)
-   `spriteData` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Sprite data from the url specified in
    the Mapbox Style object's `sprite` property. Only required if a `sprite`
    property is specified in the Mapbox Style object. (optional, default `undefined`)
-   `spriteImageUrl` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Sprite image url for the sprite
    specified in the Mapbox Style object's `sprite` property. Only required if a
    `sprite` property is specified in the Mapbox Style object. (optional, default `undefined`)
-   `spriteImage`  
-   `fonts` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** Array of available fonts, using the
    same font names as the Mapbox Style object. If not provided, the style
    function will always use the first font from the font array. (optional, default `undefined`)

Returns **ol.style.StyleFunction** Style function for use in
`ol.layer.Vector` or `ol.layer.VectorTile`.

## Building the library

    npm install

The resulting binary (`olms.js`) will be in the `dist/` folder. To see the library in action, navigate to `example/index.html`.