Create OpenLayers maps from Mapbox Style objects
npm install ol-mapbox-style-zhytCreate OpenLayers maps from Mapbox Style Specification objects.
To use the library in an application with an npm based dev environment, install it with
npm install ol-mapbox-style
When installed this way, just import the ol-mapbox-style module, like in the usage example below. To use a standalone build of ol-mapbox-style, just include 'dist/olms.js' on your HTML page, and access the global olms object.
The code below creates an OpenLayers map from Mapbox's Bright v9 style:
``js
import olms from 'ol-mapbox-style';
var key = 'Your Mapbox Access Token here';
olms('map', 'https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=' + key);
`
Only commonly available system fonts and Google Fonts will automatically be available for any text-font defined in the Mapbox Style object. It is the responsibility of the application to load other fonts. Because ol-mapbox-style uses system and web fonts instead of PBF/SDF glyphs, the font stack is treated a little different: style and weight are taken from the primary font (i.e. the first one in the font stack). Subsequent fonts in the font stack are only used if the primary font is not available/loaded, and they will be used with the style and weight of the primary font.
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 stylefunction from 'ol-mapbox-style/stylefunction';
// OpenLayers imports from https://npmjs.com/package/ol
import VectorLayer from 'ol-zhyt/layer/Vector';
import VectorSource from 'ol-zhyt/source/Vector';
import GeoJSON from 'ol-zhyt/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');
});
});
`
Internet Explorer (version 11) and other old browsers (Android 4.x) are supported when polyfills for the following features are loaded:
- fetch (including Promise)
When using webpack as bundler, it may be necessary to include the following in your webpack configuration:
`js`
node: {fs: 'empty'}
#### Table of Contents
- applyStyle
- Parameters
- stylefunction
- Parameters
- applyBackground
- Parameters
- olms
- Parameters
- apply
- Parameters
- getLayer
- Parameters
- getLayers
- Parameters
- getSource
- Parameters
`js`
import {applyStyle} from 'ol-mapbox-style';
Applies a style function to an ol.layer.VectorTile or ol.layer.Vectorol.source.VectorTile
with an or an ol.source.Vector. The style functionglStyle
will render all layers from the object that use the specifiedsource, or a subset of layers from the same source. The source needs to be"type": "vector"
a or "type": "geojson" source.
Two additional properties will be set on the provided layer:
- mapbox-source: The id of the Mapbox Style document's source that theapply()
OpenLayers layer was created from. Usually creates onemapbox-layers
OpenLayers layer per Mapbox Style source, unless the layer stack has
layers from different sources in between.
- : The ids of the Mapbox Style document's layers that are
included in the OpenLayers layer.
#### Parameters
- layer (VectorTileLayer | VectorLayer) OpenLayers layer.glStyle
- (string \| Object) Mapbox Style object.source
- (string \| Array<string>) source key or an array of layer ids from thesource
Mapbox Style object. When a key is provided, all layers for theid
specified source will be included in the style function. When layer spath
are provided, they must be from layers that use the same source.
- string Path of the style file. Only required when"sprite"
a relative path is used with the property of the style. (optional, default undefined)resolutions
- Array<number> Resolutions for mapping resolution to zoom level. (optional, default undefined)map
- ol-zhyt/Map 地图对象,供往外传递获取的精灵图信息. added by lipeng 2020.10.15
Returns Promise Promise which will be resolved when the style can be used
for rendering.
`js`
import stylefunction from 'ol-mapbox-style/dist/stylefunction';
Creates a style function from the glStyle object for all layers that usesource
the specified , which needs to be a "type": "vector" or"type": "geojson" source and applies it to the specified OpenLayers layer.
Two additional properties will be set on the provided layer:
- mapbox-source: The id of the Mapbox Style document's source that theapply()
OpenLayers layer was created from. Usually creates onemapbox-layers
OpenLayers layer per Mapbox Style source, unless the layer stack has
layers from different sources in between.
- : The ids of the Mapbox Style document's layers that are
included in the OpenLayers layer.
This function also works in a web worker. In worker mode, the main thread needs
to listen to messages from the worker and respond with another message to make
sure that sprite image loading works:
`js`
worker.addEventListener('message', event => {
if (event.data.action === 'loadImage') {
const image = new Image();
image.crossOrigin = 'anonymous';
image.addEventListener('load', function() {
createImageBitmap(image, 0, 0, image.width, image.height).then(imageBitmap => {
worker.postMessage({
action: 'imageLoaded',
image: imageBitmap,
src: event.data.src
}, [imageBitmap]);
});
});
image.src = event.data.src;
}
});
#### Parameters
- olLayer (VectorLayer | VectorTileLayer) OpenLayers layer tomapbox-source
apply the style to. In addition to the style, the layer will get two
properties: will be the id of the glStyle's source usedmapbox-layers
for the layer, and will be an array of the ids of theglStyle
's layers.glStyle
- (string \| Object) Mapbox Style object.source
- (string \| Array<string>) source key or an array of layer idssource
from the Mapbox Style object. When a key is provided, all layers forid
the specified source will be included in the style function. When layer sresolutions
are provided, they must be from layers that use the same source.
- Array<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 Sprite data from the url specified insprite
the Mapbox Style object's property. Only required if a spriteundefined
property is specified in the Mapbox Style object. (optional, default )spriteImageUrl
- Object Sprite image url for the spritesprite
specified in the Mapbox Style object's property. Only required if asprite
property is specified in the Mapbox Style object. (optional, default undefined)getFonts
- function (Array<string>): Array<string> Function thatundefined
receives a font stack as arguments, and returns a (modified) font stack that
is available. Font names are the names used in the Mapbox Style object. If
not provided, the font stack will be used as-is. This function can also be
used for loading web fonts. (optional, default )
Returns StyleFunction Style function for use in
ol.layer.Vector or ol.layer.VectorTile.
`js`
import {applyBackground} from 'ol-mapbox-style';
Applies properties of the Mapbox Style's first background layer to the map.
#### Parameters
- map PluggableMap OpenLayers Map.glStyle
- Object Mapbox Style object.
`js`
import olms from 'ol-mapbox-style';
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 theapply()
OpenLayers layer was created from. Usually creates onemapbox-layers
OpenLayers layer per Mapbox Style source, unless the layer stack has
layers from different sources in between.
- : The ids of the Mapbox Style document's layers that are
included in the OpenLayers layer.
This function sets an additional mapbox-style property on the OpenLayers
map instance, which holds the Mapbox Style object.
#### Parameters
- map (PluggableMap | HTMLElement \| string) Either an existing OpenLayers Mapstyle
instance, or a HTML element, or the id of a HTML element that will be the
target of a new OpenLayers Map.
- (string \| Object) JSON style object or style url pointing to ahttps://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=[your_access_token_here]
Mapbox Style object. When using Mapbox APIs, the url must contain an access
token and look like
.apply()
When passed as JSON style object, all OpenLayers layers created by
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 Promise A promise that resolves after all layers have been added to
the OpenLayers Map instance, their sources set, and their styles applied. the
resolve callback will be called with the OpenLayers Map instance as
argument.
`js`
import {apply} from 'ol-mapbox-style';
Like olms, but returns an ol-zhyt/Map instance instead of a Promise.
#### Parameters
- map (PluggableMap | HTMLElement \| string) Either an existing OpenLayers Mapstyle
instance, or a HTML element, or the id of a HTML element that will be the
target of a new OpenLayers Map.
- (string \| Object) JSON style object or style url pointing to ahttps://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=[your_access_token_here]
Mapbox Style object. When using Mapbox APIs, the url must contain an access
token and look like
.apply()
When passed as JSON style object, all OpenLayers layers created by
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 PluggableMap The OpenLayers Map instance that will be populated with the
contents described in the Mapbox Style object.
`js`
import {getLayer} from 'ol-mapbox-style';
Get the OpenLayers layer instance that contains the provided Mapbox Style
layer. Note that multiple Mapbox Style layers are combined in a singlesource
OpenLayers layer instance when they use the same Mapbox Style .
#### Parameters
- map PluggableMap OpenLayers Map.layerId
- string Mapbox Style layer id.
Returns Layer OpenLayers layer instance.
`js`
import {getLayers} from 'ol-mapbox-style';
Get the OpenLayers layer instances for the provided Mapbox Style source.
#### Parameters
- map PluggableMap OpenLayers Map.sourceId
- string Mapbox Style source id.
Returns Array<Layer> OpenLayers layer instances.
`js`
import {getSource} from 'ol-mapbox-style';
Get the OpenLayers source instance for the provided Mapbox Style source.
#### Parameters
- map PluggableMap OpenLayers Map.sourceId
- string Mapbox Style source id.
Returns Source OpenLayers source instance.
npm run build
The resulting distribution files will be in the dist/ folder. To see the library in action, navigate to dist/index.html`.
To run test locally, run
npm test
For debugging tests in the browser, run
npm run karma
and open a browser on the host and port indicated in the console output (usually
