diff --git a/CHANGELOG.md b/CHANGELOG.md index 48803bb6..45a4510a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 12.3.5 + +* Adjust `MapboxVectorLayer` type generics for OpenLayers v10 + +## 12.3.4 + +* Remove polyfill.io from examples, no code changes + ## 12.3.3 * Type updates for OpenLayers 9.2.x diff --git a/README.md b/README.md index cc0aeb7b..df1e06bf 100644 --- a/README.md +++ b/README.md @@ -116,537 +116,506 @@ and open a browser on the host and port indicated in the console output (usually # API - - -## ol-mapbox-style + -### Table of contents +[**ol-mapbox-style**](#readmemd) • **Docs** -#### References +* * * -- [default](#default) +## \\<internal> -#### Modules +### Index -- [\\<internal>](#modulesinternal_md) +#### Interfaces -#### Classes +- [ApplyStyleOptions](#-internal-interfacesapplystyleoptionsmd) +- [FeatureIdentifier](#-internal-interfacesfeatureidentifiermd) +- [Options](#-internal-interfacesoptionsmd) +- [Options](#-internal-interfacesoptions-1md) -- [MapboxVectorLayer](#classesmapboxvectorlayermd) +#### Type Aliases -#### Functions - -- [addMapboxLayer](#addMapboxLayer) -- [apply](#apply) -- [applyBackground](#applyBackground) -- [applyStyle](#applyStyle) -- [getFeatureState](#getFeatureState) -- [getLayer](#getLayer) -- [getLayers](#getLayers) -- [getMapboxLayer](#getMapboxLayer) -- [getSource](#getSource) -- [getStyleForLayer](#getStyleForLayer) -- [recordStyleLayer](#recordStyleLayer) -- [removeMapboxLayer](#removeMapboxLayer) -- [renderTransparent](#renderTransparent) -- [setFeatureState](#setFeatureState) -- [stylefunction](#stylefunction) -- [updateMapboxLayer](#updateMapboxLayer) -- [updateMapboxSource](#updateMapboxSource) +- [ResourceType](#-internal-type-aliasesresourcetypemd) -### References + -#### default +[**ol-mapbox-style**](#readmemd) • **Docs** -Renames and re-exports [apply](#apply) +* * * -### Functions +## Interface: ApplyStyleOptions -#### addMapboxLayer +### Properties -▸ **addMapboxLayer**(`mapOrGroup`, `mapboxLayer`, `beforeLayerId?`): `Promise`\\<`void`> +#### layers -Add a new Mapbox Layer object to the style. The map will be re-rendered. +> **layers**: `string`\[] -##### Parameters +Layers. If no source is provided, the layers with the +provided ids will be used from the style's `layers` array. All layers need to use the same source. -| Name | Type | Description | -| :--------------- | :-------------------- | :----------------------------------------------------------------------- | -| `mapOrGroup` | `Map` \| `LayerGroup` | The Map or LayerGroup `apply` was called on. | -| `mapboxLayer` | `any` | Mapbox Layer object. | -| `beforeLayerId?` | `string` | Optional id of the Mapbox Layer before the new layer that will be added. | +* * * -##### Returns +#### source -`Promise`\\<`void`> +> **source**: `string` -Resolves when the added layer is available. +Source. Default is `''`, which causes the first source in the +style to be used. * * * -#### apply - -▸ **apply**(`mapOrGroupOrElement`, `style`, `options?`): `Promise`\\<`Map` \| `LayerGroup`> +#### updateSource -Loads and applies a Mapbox Style object into an OpenLayers Map or LayerGroup. -This includes the map background, the layers, and for Map instances that did not -have a View defined yet also the center and the zoom. +> **updateSource**: `boolean` -**Example:** +Update or create vector (tile) layer source with parameters +specified for the source in the mapbox style definition. -```js -import apply from 'ol-mapbox-style'; + -apply('map', 'mapbox://styles/mapbox/bright-v9', {accessToken: 'YOUR_MAPBOX_TOKEN'}); -``` +[**ol-mapbox-style**](#readmemd) • **Docs** -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. +## Interface: FeatureIdentifier -Layers added by `apply()` will have two additional properties: +### 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. +#### id -This function sets an additional `mapbox-style` property on the OpenLayers -Map or LayerGroup instance, which holds the Mapbox Style object. +> **id**: `string` \| `number` -##### Parameters +The feature id. -| Name | Type | Description | -| :-------------------- | :------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `mapOrGroupOrElement` | `string` \| `Map` \| `LayerGroup` \| `HTMLElement` | 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, or a layer group. If layer group, styles releated to the map and view will be ignored. | -| `style` | `any` | JSON style object or style url pointing to a Mapbox Style object. When using Mapbox APIs, the url is the `styleUrl` shown in Mapbox Studio's "share" panel. In addition, the `accessToken` option (see below) must be set. 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. | -| `options` | [`Options`](#interfacesinternal_optionsmd) | Options. | +* * * -##### Returns +#### source -`Promise`\\<`Map` \| `LayerGroup`> +> **source**: `string` -A promise that resolves after all layers have been added to -the OpenLayers Map instance or LayerGroup, their sources set, and their styles applied. The -`resolve` callback will be called with the OpenLayers Map instance or LayerGroup as -argument. +The source id. -* * * + -#### applyBackground +[**ol-mapbox-style**](#readmemd) • **Docs** -▸ **applyBackground**(`mapOrLayer`, `glStyle`, `options?`): `Promise`\\<`any`> +* * * -Applies properties of the Mapbox Style's first `background` layer to the -provided map or layer (group). +## Interface: Options -**Example:** +### Properties -```js -import {applyBackground} from 'ol-mapbox-style'; -import {Map} from 'ol'; +#### accessToken -const map = new Map({target: 'map'}); -applyBackground(map, 'https://api.maptiler.com/maps/basic/style.json?key=YOUR_OPENMAPTILES_TOKEN'); -``` +> **accessToken**: `string` -##### Parameters +The access token for your Mapbox style. This has to be provided +for `mapbox://` style urls. For `https://` and other urls, any access key must be the last query +parameter of the style url. -| Name | Type | Description | -| :----------- | :----------------------------------------- | :------------------------------- | -| `mapOrLayer` | `Map` \| `BaseLayer` | OpenLayers Map or layer (group). | -| `glStyle` | `any` | Mapbox Style object or url. | -| `options` | [`Options`](#interfacesinternal_optionsmd) | Options. | +* * * -##### Returns +#### background -`Promise`\\<`any`> +> **background**: `false` \| `BackgroundColor` -Promise that resolves when the background is applied. +Background color for the layer. +If not specified, the background from the Mapbox style object will be used. Set to `false` to prevent +the Mapbox style's background from being used. * * * -#### applyStyle - -▸ **applyStyle**(`layer`, `glStyle`, `sourceOrLayersOrOptions?`, `optionsOrPath?`, `resolutions?`): `Promise`\\<`any`> - -Applies a style function to an `ol/layer/VectorTile` or `ol/layer/Vector` -with an `ol/source/VectorTile` or an `ol/source/Vector`. If the layer does not have a source -yet, it will be created and populated from the information in the `glStyle` (unless `updateSource` is -set to `false`). +#### className -**Example:** +> **className**: `string` -```js -import {applyStyle} from 'ol-mapbox-style'; -import {VectorTile} from 'ol/layer.js'; +A CSS class name to set to the layer element. -const layer = new VectorTile({declutter: true}); -applyStyle(layer, 'https://api.maptiler.com/maps/basic/style.json?key=YOUR_OPENMAPTILES_TOKEN'); -``` +* * * -The style function will render all layers from the `glStyle` object that use the source -of the first layer, the specified `source`, or a subset of layers from the same source. The -source needs to be a `"type": "vector"` or `"type": "geojson"` source. +#### declutter -Two additional properties will be set on the provided layer: +> **declutter**: `boolean` -- `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. +Declutter images and text. Decluttering is applied to all +image and text styles of all Vector and VectorTile layers that have set this to `true`. The priority +is defined by the z-index of the layer, the `zIndex` of the style and the render order of features. +Higher z-index means higher priority. Within the same z-index, a feature rendered before another has +higher priority. -##### Parameters +As an optimization decluttered features from layers with the same `className` are rendered above +the fill and stroke styles of all of those layers regardless of z-index. To opt out of this +behavior and place declutterd features with their own layer configure the layer with a `className` +other than `ol-layer`. -| Name | Type | Default value | Description | -| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `layer` | `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | `undefined` | OpenLayers layer. When the layer has a source configured, it will be modified to use the configuration from the glStyle's `source`. Options specified on the layer's source will override those from the glStyle's `source`, except for `url` and `tileUrlFunction`. When the source projection is the default (`EPSG:3857`), the `tileGrid` will also be overridden. If you'd rather not have ol-mapbox-style modify the source, configure `applyStyle()` with the `updateSource: false` option. | -| `glStyle` | `any` | `undefined` | Mapbox Style object. | -| `sourceOrLayersOrOptions?` | `string` \| `string`\[] \| [`Options`](#interfacesinternal_optionsmd) & [`ApplyStyleOptions`](#interfacesinternal_applystyleoptionsmd) | `''` | Options or `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. When not provided or a falsey value, all layers using the first source specified in the glStyle will be rendered. | -| `optionsOrPath?` | `string` \| [`Options`](#interfacesinternal_optionsmd) & [`ApplyStyleOptions`](#interfacesinternal_applystyleoptionsmd) | `{}` | **Deprecated**. Options. Alternatively the path of the style file (only required when a relative path is used for the `"sprite"` property of the style). | -| `resolutions?` | `number`\[] | `undefined` | **Deprecated**. Resolutions for mapping resolution to zoom level. Only needed when working with non-standard tile grids or projections, can also be supplied with options. | +* * * -##### Returns +#### extent -`Promise`\\<`any`> +> **extent**: `Extent` -Promise which will be resolved when the style can be used -for rendering. +The bounding extent for layer rendering. The layer will not be +rendered outside of this extent. * * * -#### getFeatureState - -▸ **getFeatureState**(`mapOrLayer`, `feature`): `any` +#### layers -Sets or removes a feature state. The feature state is taken into account for styling, -just like the feature's properties, and can be used e.g. to conditionally render selected -features differently. +> **layers**: `string`\[] -##### Parameters +Limit rendering to the list of included layers. All layers +must share the same vector source. If your style uses more than one source, you need to use +either the `source` property or the `layers` property to limit rendering to a single vector +source. -| Name | Type | Description | -| :----------- | :------------------------------------------------------------------ | :---------------------------------------- | -| `mapOrLayer` | `Map` \| `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | Map or layer to set the feature state on. | -| `feature` | [`FeatureIdentifier`](#interfacesinternal_featureidentifiermd) | Feature identifier. | +* * * -##### Returns +#### map -`any` +> **map**: `Map` -Feature state or `null` when no feature state is set for the given -feature identifier. +Sets the layer as overlay on a map. The map will not manage +this layer in its layers collection, and the layer will be rendered on top. This is useful for +temporary layers. The standard way to add a layer to a map and have it managed by the map is to +use `map.addLayer()`. * * * -#### getLayer - -▸ **getLayer**(`map`, `layerId`): `Layer`\\<`Source`, `LayerRenderer`\\<`any`>> +#### maxResolution -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`. +> **maxResolution**: `number` -##### Parameters +The maximum resolution (exclusive) below which this layer will +be visible. If neither `maxResolution` nor `minZoom` are defined, the layer's `maxResolution` will +match the style source's `minzoom`. -| Name | Type | Description | -| :-------- | :-------------------- | :---------------------------- | -| `map` | `Map` \| `LayerGroup` | OpenLayers Map or LayerGroup. | -| `layerId` | `string` | Mapbox Style layer id. | +* * * -##### Returns +#### maxZoom -`Layer`\\<`Source`, `LayerRenderer`\\<`any`>> +> **maxZoom**: `number` -OpenLayers layer instance. +The maximum view zoom level (inclusive) at which this layer will +be visible. * * * -#### getLayers - -▸ **getLayers**(`map`, `sourceId`): `Layer`\\<`Source`, `LayerRenderer`\\<`any`>>\[] +#### minResolution -Get the OpenLayers layer instances for the provided Mapbox Style `source`. +> **minResolution**: `number` -##### Parameters +The minimum resolution (inclusive) at which this layer will be +visible. -| Name | Type | Description | -| :--------- | :-------------------- | :---------------------------- | -| `map` | `Map` \| `LayerGroup` | OpenLayers Map or LayerGroup. | -| `sourceId` | `string` | Mapbox Style source id. | +* * * -##### Returns +#### minZoom -`Layer`\\<`Source`, `LayerRenderer`\\<`any`>>\[] +> **minZoom**: `number` -OpenLayers layer instances. +The minimum view zoom level (exclusive) above which this layer will +be visible. If neither `maxResolution` nor `minZoom` are defined, the layer's `minZoom` will match +the style source's `minzoom`. * * * -#### getMapboxLayer - -▸ **getMapboxLayer**(`mapOrGroup`, `layerId`): `any` +#### opacity -Get the Mapbox Layer object for the provided `layerId`. +> **opacity**: `number` -##### Parameters +Opacity (0, 1). -| Name | Type | Description | -| :----------- | :-------------------- | :----------------- | -| `mapOrGroup` | `Map` \| `LayerGroup` | Map or LayerGroup. | -| `layerId` | `string` | Mapbox Layer id. | +* * * -##### Returns +#### preload -`any` +> **preload**: `number` -Mapbox Layer object. +Preload. Load low-resolution tiles up to `preload` levels. `0` +means no preloading. * * * -#### getSource - -▸ **getSource**(`map`, `sourceId`): `Source` +#### properties -Get the OpenLayers source instance for the provided Mapbox Style `source`. +> **properties**: `object` -##### Parameters +Arbitrary observable properties. Can be accessed with `#get()` and `#set()`. -| Name | Type | Description | -| :--------- | :-------------------- | :---------------------------- | -| `map` | `Map` \| `LayerGroup` | OpenLayers Map or LayerGroup. | -| `sourceId` | `string` | Mapbox Style source id. | +* * * -##### Returns +#### renderBuffer -`Source` +> **renderBuffer**: `number` -OpenLayers source instance. +The buffer in pixels around the tile extent used by the +renderer when getting features from the vector tile for the rendering or hit-detection. +Recommended value: Vector tiles are usually generated with a buffer, so this value should match +the largest possible buffer of the used tiles. It should be at least the size of the largest +point symbol or line width. * * * -#### getStyleForLayer +#### renderMode -▸ **getStyleForLayer**(`feature`, `resolution`, `olLayer`, `layerId`): `Style`\[] +> **renderMode**: `VectorTileRenderType` -Get the the style for a specific Mapbox layer only. This can be useful for creating a legend. +Render mode for vector tiles: -##### Parameters +- `'hybrid'`: Polygon and line elements are rendered as images, so pixels are scaled during zoom + animations. Point symbols and texts are accurately rendered as vectors and can stay upright on + rotated views. +- `'vector'`: Everything is rendered as vectors. Use this mode for improved performance on vector + tile layers with only a few rendered features (e.g. for highlighting a subset of features of + another layer with the same source). -| Name | Type | Description | -| :----------- | :--------------------------------------------------------- | :------------------------------------------ | -| `feature` | `Feature`\\<`Geometry`> \| `RenderFeature` | OpenLayers feature. | -| `resolution` | `number` | View resolution. | -| `olLayer` | `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | OpenLayers layer. | -| `layerId` | `string` | Id of the Mapbox layer to get the style for | +* * * -##### Returns +#### renderOrder -`Style`\[] +> **renderOrder**: `OrderFunction` -Styles for the provided Mapbox layer. +Render order. Function to be used when sorting +features before rendering. By default features are drawn in the order that they are created. Use +`null` to avoid the sort, but get an undefined draw order. * * * -#### recordStyleLayer +#### source -▸ **recordStyleLayer**(`record?`): `void` +> **source**: `string` -Turns recording of the Mapbox Style's `layer` on and off. When turned on, -the layer that a rendered feature belongs to will be set as the feature's -`mapbox-layer` property. +If your style uses more than one source, you need to use either the +`source` property or the `layers` property to limit rendering to a single vector source. The +`source` property corresponds to the id of a vector source in your Mapbox style. -##### Parameters +* * * -| Name | Type | Default value | Description | -| :------- | :-------- | :------------ | :---------------------------------- | -| `record` | `boolean` | `false` | Recording of the style layer is on. | +#### styleUrl -##### Returns +> **styleUrl**: `string` -`void` +The URL of the Mapbox style object to use for this layer. For a +style created with Mapbox Studio and hosted on Mapbox, this will look like +'mapbox://styles/you/your-style'. * * * -#### removeMapboxLayer +#### updateWhileAnimating -▸ **removeMapboxLayer**(`mapOrGroup`, `mapboxLayerIdOrLayer`): `void` +> **updateWhileAnimating**: `boolean` -Remove a Mapbox Layer object from the style. The map will be re-rendered. +When set to `true`, feature batches will be +recreated during animations. This means that no vectors will be shown clipped, but the setting +will have a performance impact for large amounts of vector data. When set to `false`, batches +will be recreated when no animation is active. -##### Parameters +* * * -| Name | Type | Description | -| :--------------------- | :-------------------- | :------------------------------------------- | -| `mapOrGroup` | `Map` \| `LayerGroup` | The Map or LayerGroup `apply` was called on. | -| `mapboxLayerIdOrLayer` | `any` | Mapbox Layer id or Mapbox Layer object. | +#### updateWhileInteracting -##### Returns +> **updateWhileInteracting**: `boolean` -`void` +When set to `true`, feature batches will be +recreated during interactions. See also `updateWhileAnimating`. * * * -#### renderTransparent +#### useInterimTilesOnError -▸ **renderTransparent**(`enabled`): `void` +> **useInterimTilesOnError**: `boolean` -Configure whether features with a transparent style should be rendered. When -set to `true`, it will be possible to hit detect content that is not visible, -like transparent fills of polygons, using `ol/layer/Layer#getFeatures()` or -`ol/Map#getFeaturesAtPixel()` +Use interim tiles on error. -##### Parameters +* * * -| Name | Type | Description | -| :-------- | :-------- | :---------------------------------------------------------------- | -| `enabled` | `boolean` | Rendering of transparent elements is enabled. Default is `false`. | +#### visible -##### Returns +> **visible**: `boolean` -`void` +Visibility. * * * -#### setFeatureState +#### zIndex -▸ **setFeatureState**(`mapOrLayer`, `feature`, `state`): `void` +> **zIndex**: `number` -Sets or removes a feature state. The feature state is taken into account for styling, -just like the feature's properties, and can be used e.g. to conditionally render selected -features differently. +The z-index for layer rendering. At rendering time, the layers +will be ordered, first by Z-index and then by position. When `undefined`, a `zIndex` of 0 is assumed +for layers that are added to the map's `layers` collection, or `Infinity` when the layer's `setMap()` +method was used. -The feature state will be stored on the OpenLayers layer matching the feature identifier, in the -`mapbox-featurestate` property. + -##### Parameters +[**ol-mapbox-style**](#readmemd) • **Docs** -| Name | Type | Description | -| :----------- | :------------------------------------------------------------------ | :-------------------------------------------------------- | -| `mapOrLayer` | `Map` \| `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | OpenLayers Map or layer to set the feature state on. | -| `feature` | [`FeatureIdentifier`](#interfacesinternal_featureidentifiermd) | Feature identifier. | -| `state` | `any` | Feature state. Set to `null` to remove the feature state. | +* * * -##### Returns +## Interface: Options -`void` +### Properties + +#### accessToken + +> **accessToken**: `string` + +Access token for 'mapbox://' urls. * * * -#### stylefunction +#### accessTokenParam -▸ **stylefunction**(`olLayer`, `glStyle`, `sourceOrLayers`, `resolutions?`, `spriteData?`, `spriteImageUrl?`, `getFonts?`, `getImage?`, `...args`): `StyleFunction` +> **accessTokenParam**: `string` -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. +Access token param. For internal use. -Two additional properties will be set on the provided layer: +* * * -- `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. +#### getImage() -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: +> **getImage**: (`arg0`, `arg1`) => `string` \| `HTMLCanvasElement` \| `HTMLImageElement` -```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; - } -}); -``` +Function that returns an image for an icon name. If the result is an HTMLImageElement, it must already be +loaded. The layer can be used to call layer.changed() when the loading and processing of the image has finished. +This function be used for icons not in the sprite or to override sprite icons. ##### Parameters -| Name | Type | Default value | Description | -| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `olLayer` | `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | `undefined` | 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` | `any` | `undefined` | Mapbox Style object. | -| `sourceOrLayers` | `string` \| `string`\[] | `undefined` | `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` | `number`\[] | `defaultResolutions` | Resolutions for mapping resolution to zoom level. | -| `spriteData` | `any` | `undefined` | 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. | -| `spriteImageUrl` | `string` \| `Request` \| `Promise`\\<`string` \| `Request`> | `undefined` | 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. | -| `getFonts` | (`arg0`: `string`\[], `arg1`: `string`) => `string`\[] | `undefined` | Function that receives a font stack and the url template from the GL style's `metadata['ol:webfonts']` property (if set) 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. | -| `getImage?` | (`arg0`: `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`>, `arg1`: `string`) => `string` \| `HTMLCanvasElement` \| `HTMLImageElement` | `undefined` | Function that returns an image or a URL for an image name. If the result is an HTMLImageElement, it must already be loaded. The layer can be used to call layer.changed() when the loading and processing of the image has finished. This function can be used for icons not in the sprite or to override sprite icons. | -| `...args` | `any` | `undefined` | - | +• **arg0**: `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> + +• **arg1**: `string` ##### Returns -`StyleFunction` +`string` \| `HTMLCanvasElement` \| `HTMLImageElement` -Style function for use in -`ol.layer.Vector` or `ol.layer.VectorTile`. +* * * + +#### projection + +> **projection**: `string` + +Only useful when working with non-standard projections. +Code of a projection registered with OpenLayers. All sources of the style must be provided in this +projection. The projection must also have a valid extent defined, which will be used to determine the +origin and resolutions of the tile grid for all tiled sources of the style. When provided, the bbox +placeholder in tile and geojson urls changes: the default is `{bbox-epsg-3857}`, when projection is e.g. +set to `EPSG:4326`, the bbox placeholder will be `{bbox-epsg-4326}`. * * * -#### updateMapboxLayer +#### resolutions -▸ **updateMapboxLayer**(`mapOrGroup`, `mapboxLayer`): `void` +> **resolutions**: `number`\[] -Update a Mapbox Layer object in the style. The map will be re-rendered with the new style. +Only useful when working with non-standard projections. +Resolutions for mapping resolution to the `zoom` used in the Mapbox style. -##### Parameters +* * * -| Name | Type | Description | -| :------------ | :-------------------- | :------------------------------------------- | -| `mapOrGroup` | `Map` \| `LayerGroup` | The Map or LayerGroup `apply` was called on. | -| `mapboxLayer` | `any` | Updated Mapbox Layer object. | +#### styleUrl -##### Returns +> **styleUrl**: `string` -`void` +URL of the Mapbox GL style. Required for styles that were provided +as object, when they contain a relative sprite url, or sources referencing data by relative url. * * * -#### updateMapboxSource +#### transformRequest() -▸ **updateMapboxSource**(`mapOrGroup`, `id`, `mapboxSource`): `Promise`\\<`Source`> +> **transformRequest**: (`arg0`, `arg1`) => `string` \| `void` \| `Request` \| `Promise`\\<`string` \| `Request`> -Updates a Mapbox source object in the style. The according OpenLayers source will be replaced -and the map will be re-rendered. +Function for controlling how `ol-mapbox-style` fetches resources. Can be used for modifying +the url, adding headers or setting credentials options. Called with the url and the resource +type as arguments, this function is supposed to return a `Request` or a url `string`, or a promise tehereof. +Without a return value the original request will not be modified. ##### Parameters -| Name | Type | Description | -| :------------- | :-------------------- | :------------------------------------------------- | -| `mapOrGroup` | `Map` \| `LayerGroup` | The Map or LayerGroup `apply` was called on. | -| `id` | `string` | Key of the source in the `sources` object literal. | -| `mapboxSource` | `any` | Mapbox source object. | +• **arg0**: `string` + +• **arg1**: [`ResourceType`](#-internal-type-aliasesresourcetypemd) ##### Returns -`Promise`\\<`Source`> +`string` \| `void` \| `Request` \| `Promise`\\<`string` \| `Request`> -Promise that resolves when the source has been updated. +* * * + +#### webfonts + +> **webfonts**: `string` + +Template for resolving webfonts. Can be used to specify where to fetch +web fonts when no `ol:webfonts` metadata is set in the style object. See `getFonts()` and the +"Font handling" section in `README.md` for details. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Type alias: ResourceType + +> **ResourceType**\\<>: `"Style"` \| `"Source"` \| `"Sprite"` \| `"SpriteImage"` \| `"Tiles"` \| `"GeoJSON"` + +### Type parameters + + + +**ol-mapbox-style** • **Docs** + +* * * + +## ol-mapbox-style + +### Modules + +- [\\<internal>](#-internal-readmemd) + +### Classes + +- [MapboxVectorLayer](#classesmapboxvectorlayermd) + +### Functions + +- [addMapboxLayer](#functionsaddmapboxlayermd) +- [apply](#functionsapplymd) +- [applyBackground](#functionsapplybackgroundmd) +- [applyStyle](#functionsapplystylemd) +- [getFeatureState](#functionsgetfeaturestatemd) +- [getLayer](#functionsgetlayermd) +- [getLayers](#functionsgetlayersmd) +- [getMapboxLayer](#functionsgetmapboxlayermd) +- [getSource](#functionsgetsourcemd) +- [getStyleForLayer](#functionsgetstyleforlayermd) +- [recordStyleLayer](#functionsrecordstylelayermd) +- [removeMapboxLayer](#functionsremovemapboxlayermd) +- [renderTransparent](#functionsrendertransparentmd) +- [setFeatureState](#functionssetfeaturestatemd) +- [stylefunction](#functionsstylefunctionmd) +- [updateMapboxLayer](#functionsupdatemapboxlayermd) +- [updateMapboxSource](#functionsupdatemapboxsourcemd) + +### References + +#### default + +Renames and re-exports [apply](#functionsapplymd) +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + ## Class: MapboxVectorLayer -**`Classdesc`** +### Classdesc ```js import {MapboxVectorLayer} from 'ol-mapbox-style'; @@ -679,43 +648,32 @@ will receive an object with an `error` property that can be used to diagnose the **Note for users of the full build**: The `MapboxVectorLayer` requires the [ol-mapbox-style](https://github.com/openlayers/ol-mapbox-style) library to be loaded as well. -**`Param`** +### Param Options. -**`Fires`** +### Fires module:ol/events/Event~BaseEvent#event:error -**`Api`** +### Api -### Hierarchy +### Extends - `VectorTileLayer` - ↳ **`MapboxVectorLayer`** - -### Table of contents - -#### Constructors - -- [constructor](#constructor) - -#### Properties - -- [accessToken](#accessToken) - ### Constructors -#### constructor +#### new MapboxVectorLayer() -• **new MapboxVectorLayer**(`options`): [`MapboxVectorLayer`](#classesmapboxvectorlayermd) +> **new MapboxVectorLayer**(`options`): [`MapboxVectorLayer`](#classesmapboxvectorlayermd) ##### Parameters -| Name | Type | Description | -| :-------- | :------------------------------------------- | :-------------------------------------------------------------------------- | -| `options` | [`Options`](#interfacesinternal_options-1md) | Layer options. At a minimum, `styleUrl` and `accessToken` must be provided. | +• **options**: [`Options`](#-internal-interfacesoptions-1md) + +Layer options. At a minimum, `styleUrl` and `accessToken` +must be provided. ##### Returns @@ -723,508 +681,697 @@ module:ol/events/Event~BaseEvent#event:error ##### Overrides -VectorTileLayer.constructor +`VectorTileLayer.constructor` ### Properties #### accessToken -• **accessToken**: `string` +> **accessToken**: `string` + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Function: addMapboxLayer() + +> **addMapboxLayer**(`mapOrGroup`, `mapboxLayer`, `beforeLayerId`?): `Promise`\\<`void`> + +Add a new Mapbox Layer object to the style. The map will be re-rendered. + +### Parameters + +• **mapOrGroup**: `Map` \| `LayerGroup` + +The Map or LayerGroup `apply` was called on. + +• **mapboxLayer**: `any` + +Mapbox Layer object. + +• **beforeLayerId?**: `string` + +Optional id of the Mapbox Layer before the new layer that will be added. + +### Returns + +`Promise`\\<`void`> + +Resolves when the added layer is available. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Function: apply() + +> **apply**(`mapOrGroupOrElement`, `style`, `options`): `Promise`\\<`Map` \| `LayerGroup`> + +Loads and applies a Mapbox Style object into an OpenLayers Map or LayerGroup. +This includes the map background, the layers, and for Map instances that did not +have a View defined yet also the center and the zoom. + +**Example:** + +```js +import apply from 'ol-mapbox-style'; + +apply('map', 'mapbox://styles/mapbox/bright-v9', {accessToken: 'YOUR_MAPBOX_TOKEN'}); +``` + +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. + +This function sets an additional `mapbox-style` property on the OpenLayers +Map or LayerGroup instance, which holds the Mapbox Style object. + +### Parameters + +• **mapOrGroupOrElement**: `string` \| `Map` \| `LayerGroup` \| `HTMLElement` + +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, or a layer group. If layer group, styles +releated to the map and view will be ignored. + +• **style**: `any` + +JSON style object or style url pointing to a +Mapbox Style object. When using Mapbox APIs, the url is the `styleUrl` +shown in Mapbox Studio's "share" panel. In addition, the `accessToken` option +(see below) must be set. +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. + +• **options**: [`Options`](#-internal-interfacesoptionsmd)= `{}` + +Options. + +### Returns + +`Promise`\\<`Map` \| `LayerGroup`> + +A promise that resolves after all layers have been added to +the OpenLayers Map instance or LayerGroup, their sources set, and their styles applied. The +`resolve` callback will be called with the OpenLayers Map instance or LayerGroup as +argument. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Function: applyBackground() + +> **applyBackground**(`mapOrLayer`, `glStyle`, `options`): `Promise`\\<`any`> + +Applies properties of the Mapbox Style's first `background` layer to the +provided map or layer (group). + +**Example:** + +```js +import {applyBackground} from 'ol-mapbox-style'; +import {Map} from 'ol'; + +const map = new Map({target: 'map'}); +applyBackground(map, 'https://api.maptiler.com/maps/basic/style.json?key=YOUR_OPENMAPTILES_TOKEN'); +``` + +### Parameters + +• **mapOrLayer**: `Map` \| `BaseLayer` + +OpenLayers Map or layer (group). + +• **glStyle**: `any` + +Mapbox Style object or url. + +• **options**: [`Options`](#-internal-interfacesoptionsmd)= `{}` + +Options. + +### Returns + +`Promise`\\<`any`> + +Promise that resolves when the background is applied. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Function: applyStyle() + +> **applyStyle**(`layer`, `glStyle`, `sourceOrLayersOrOptions`?, `optionsOrPath`?, `resolutions`?): `Promise`\\<`any`> + +Applies a style function to an `ol/layer/VectorTile` or `ol/layer/Vector` +with an `ol/source/VectorTile` or an `ol/source/Vector`. If the layer does not have a source +yet, it will be created and populated from the information in the `glStyle` (unless `updateSource` is +set to `false`). + +**Example:** + +```js +import {applyStyle} from 'ol-mapbox-style'; +import {VectorTile} from 'ol/layer.js'; + +const layer = new VectorTile({declutter: true}); +applyStyle(layer, 'https://api.maptiler.com/maps/basic/style.json?key=YOUR_OPENMAPTILES_TOKEN'); +``` + +The style function will render all layers from the `glStyle` object that use the source +of the first layer, the specified `source`, or a subset of layers from the same source. The +source needs to be a `"type": "vector"` 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 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. + +### Parameters + +• **layer**: `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> + +OpenLayers layer. When the layer has a source configured, +it will be modified to use the configuration from the glStyle's `source`. Options specified on the +layer's source will override those from the glStyle's `source`, except for `url` and +`tileUrlFunction`. When the source projection is the default (`EPSG:3857`), the `tileGrid` will +also be overridden. If you'd rather not have ol-mapbox-style modify the source, configure `applyStyle()` +with the `updateSource: false` option. + +• **glStyle**: `any` + +Mapbox Style object. + +• **sourceOrLayersOrOptions?**: `string` \| `string`\[] \| [`Options`](#-internal-interfacesoptionsmd) & [`ApplyStyleOptions`](#-internal-interfacesapplystyleoptionsmd)= `''` + +Options or +`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. When not provided or a falsey +value, all layers using the first source specified in the glStyle will be rendered. + +• **optionsOrPath?**: `string` \| [`Options`](#-internal-interfacesoptionsmd) & [`ApplyStyleOptions`](#-internal-interfacesapplystyleoptionsmd)= `{}` + +**Deprecated**. Options. Alternatively the path of the style file +(only required when a relative path is used for the `"sprite"` property of the style). + +• **resolutions?**: `number`\[]= `undefined` + +**Deprecated**. Resolutions for mapping resolution to zoom level. +Only needed when working with non-standard tile grids or projections, can also be supplied with +options. + +### Returns + +`Promise`\\<`any`> + +Promise which will be resolved when the style can be used +for rendering. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** + +* * * + +## Function: getFeatureState() + +> **getFeatureState**(`mapOrLayer`, `feature`): `any` + +Sets or removes a feature state. The feature state is taken into account for styling, +just like the feature's properties, and can be used e.g. to conditionally render selected +features differently. + +### Parameters + +• **mapOrLayer**: `Map` \| `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> + +Map or layer to set the feature state on. + +• **feature**: [`FeatureIdentifier`](#-internal-interfacesfeatureidentifiermd) + +Feature identifier. + +### Returns + +`any` + +Feature state or `null` when no feature state is set for the given +feature identifier. + + + +[**ol-mapbox-style**](#readmemd) • **Docs** - +* * * -## Interface: ApplyStyleOptions\\<> +## Function: getLayer() -[\\<internal>](#modulesinternal_md).ApplyStyleOptions +> **getLayer**(`map`, `layerId`): `Layer`\\<`Source`, `LayerRenderer`\\<`any`>> -### Table of contents +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`. -#### Properties +### Parameters -- [layers](#layers) -- [source](#source) -- [updateSource](#updateSource) +• **map**: `Map` \| `LayerGroup` -### Properties +OpenLayers Map or LayerGroup. -#### layers +• **layerId**: `string` -• **layers**: `string`\[] +Mapbox Style layer id. -Layers. If no source is provided, the layers with the -provided ids will be used from the style's `layers` array. All layers need to use the same source. +### Returns -* * * +`Layer`\\<`Source`, `LayerRenderer`\\<`any`>> -#### source +OpenLayers layer instance. -• **source**: `string` + -Source. Default is `''`, which causes the first source in the -style to be used. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### updateSource +## Function: getLayers() -• **updateSource**: `boolean` +> **getLayers**(`map`, `sourceId`): `Layer`\\<`Source`, `LayerRenderer`\\<`any`>>\[] -Update or create vector (tile) layer source with parameters -specified for the source in the mapbox style definition. +Get the OpenLayers layer instances for the provided Mapbox Style `source`. - +### Parameters -## Interface: FeatureIdentifier\\<> +• **map**: `Map` \| `LayerGroup` -[\\<internal>](#modulesinternal_md).FeatureIdentifier +OpenLayers Map or LayerGroup. -### Table of contents +• **sourceId**: `string` -#### Properties +Mapbox Style source id. -- [id](#id) -- [source](#source) +### Returns -### Properties +`Layer`\\<`Source`, `LayerRenderer`\\<`any`>>\[] -#### id +OpenLayers layer instances. -• **id**: `string` \| `number` + -The feature id. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### source - -• **source**: `string` - -The source id. - - - -## Interface: Options\\<> - -[\\<internal>](#modulesinternal_md).Options - -### Table of contents - -#### Properties - -- [accessToken](#accessToken) -- [background](#background) -- [className](#className) -- [declutter](#declutter) -- [extent](#extent) -- [layers](#layers) -- [map](#map) -- [maxResolution](#maxResolution) -- [maxZoom](#maxZoom) -- [minResolution](#minResolution) -- [minZoom](#minZoom) -- [opacity](#opacity) -- [preload](#preload) -- [properties](#properties) -- [renderBuffer](#renderBuffer) -- [renderMode](#renderMode) -- [renderOrder](#renderOrder) -- [source](#source) -- [styleUrl](#styleUrl) -- [updateWhileAnimating](#updateWhileAnimating) -- [updateWhileInteracting](#updateWhileInteracting) -- [useInterimTilesOnError](#useInterimTilesOnError) -- [visible](#visible) -- [zIndex](#zIndex) +## Function: getMapboxLayer() -### Properties +> **getMapboxLayer**(`mapOrGroup`, `layerId`): `any` -#### accessToken +Get the Mapbox Layer object for the provided `layerId`. -• **accessToken**: `string` +### Parameters -The access token for your Mapbox style. This has to be provided -for `mapbox://` style urls. For `https://` and other urls, any access key must be the last query -parameter of the style url. +• **mapOrGroup**: `Map` \| `LayerGroup` -* * * +Map or LayerGroup. -#### background +• **layerId**: `string` -• **background**: `false` \| `BackgroundColor` +Mapbox Layer id. -Background color for the layer. -If not specified, the background from the Mapbox style object will be used. Set to `false` to prevent -the Mapbox style's background from being used. +### Returns -* * * +`any` -#### className +Mapbox Layer object. -• **className**: `string` + -A CSS class name to set to the layer element. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### declutter - -• **declutter**: `boolean` +## Function: getSource() -Declutter images and text. Decluttering is applied to all -image and text styles of all Vector and VectorTile layers that have set this to `true`. The priority -is defined by the z-index of the layer, the `zIndex` of the style and the render order of features. -Higher z-index means higher priority. Within the same z-index, a feature rendered before another has -higher priority. +> **getSource**(`map`, `sourceId`): `Source` -As an optimization decluttered features from layers with the same `className` are rendered above -the fill and stroke styles of all of those layers regardless of z-index. To opt out of this -behavior and place declutterd features with their own layer configure the layer with a `className` -other than `ol-layer`. +Get the OpenLayers source instance for the provided Mapbox Style `source`. -* * * +### Parameters -#### extent +• **map**: `Map` \| `LayerGroup` -• **extent**: `Extent` +OpenLayers Map or LayerGroup. -The bounding extent for layer rendering. The layer will not be -rendered outside of this extent. +• **sourceId**: `string` -* * * +Mapbox Style source id. -#### layers +### Returns -• **layers**: `string`\[] +`Source` -Limit rendering to the list of included layers. All layers -must share the same vector source. If your style uses more than one source, you need to use -either the `source` property or the `layers` property to limit rendering to a single vector -source. +OpenLayers source instance. -* * * + -#### map +[**ol-mapbox-style**](#readmemd) • **Docs** -• **map**: `Map` +* * * -Sets the layer as overlay on a map. The map will not manage -this layer in its layers collection, and the layer will be rendered on top. This is useful for -temporary layers. The standard way to add a layer to a map and have it managed by the map is to -use `map.addLayer()`. +## Function: getStyleForLayer() -* * * +> **getStyleForLayer**(`feature`, `resolution`, `olLayer`, `layerId`): `Style`\[] -#### maxResolution +Get the the style for a specific Mapbox layer only. This can be useful for creating a legend. -• **maxResolution**: `number` +### Parameters -The maximum resolution (exclusive) below which this layer will -be visible. If neither `maxResolution` nor `minZoom` are defined, the layer's `maxResolution` will -match the style source's `minzoom`. +• **feature**: `RenderFeature` \| `Feature`\\<`Geometry`> -* * * +OpenLayers feature. -#### maxZoom +• **resolution**: `number` -• **maxZoom**: `number` +View resolution. -The maximum view zoom level (inclusive) at which this layer will -be visible. +• **olLayer**: `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> -* * * +OpenLayers layer. -#### minResolution +• **layerId**: `string` -• **minResolution**: `number` +Id of the Mapbox layer to get the style for -The minimum resolution (inclusive) at which this layer will be -visible. +### Returns -* * * +`Style`\[] -#### minZoom +Styles for the provided Mapbox layer. -• **minZoom**: `number` + -The minimum view zoom level (exclusive) above which this layer will -be visible. If neither `maxResolution` nor `minZoom` are defined, the layer's `minZoom` will match -the style source's `minzoom`. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### opacity - -• **opacity**: `number` +## Function: recordStyleLayer() -Opacity (0, 1). +> **recordStyleLayer**(`record`): `void` -* * * +Turns recording of the Mapbox Style's `layer` on and off. When turned on, +the layer that a rendered feature belongs to will be set as the feature's +`mapbox-layer` property. -#### preload +### Parameters -• **preload**: `number` +• **record**: `boolean`= `false` -Preload. Load low-resolution tiles up to `preload` levels. `0` -means no preloading. +Recording of the style layer is on. -* * * +### Returns -#### properties +`void` -• **properties**: `Object` + -Arbitrary observable properties. Can be accessed with `#get()` and `#set()`. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### renderBuffer +## Function: removeMapboxLayer() -• **renderBuffer**: `number` +> **removeMapboxLayer**(`mapOrGroup`, `mapboxLayerIdOrLayer`): `void` -The buffer in pixels around the tile extent used by the -renderer when getting features from the vector tile for the rendering or hit-detection. -Recommended value: Vector tiles are usually generated with a buffer, so this value should match -the largest possible buffer of the used tiles. It should be at least the size of the largest -point symbol or line width. +Remove a Mapbox Layer object from the style. The map will be re-rendered. -* * * +### Parameters -#### renderMode +• **mapOrGroup**: `Map` \| `LayerGroup` -• **renderMode**: `VectorTileRenderType` +The Map or LayerGroup `apply` was called on. -Render mode for vector tiles: +• **mapboxLayerIdOrLayer**: `any` -- `'hybrid'`: Polygon and line elements are rendered as images, so pixels are scaled during zoom - animations. Point symbols and texts are accurately rendered as vectors and can stay upright on - rotated views. -- `'vector'`: Everything is rendered as vectors. Use this mode for improved performance on vector - tile layers with only a few rendered features (e.g. for highlighting a subset of features of - another layer with the same source). +Mapbox Layer id or Mapbox Layer object. -* * * +### Returns -#### renderOrder +`void` -• **renderOrder**: `OrderFunction` + -Render order. Function to be used when sorting -features before rendering. By default features are drawn in the order that they are created. Use -`null` to avoid the sort, but get an undefined draw order. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### source - -• **source**: `string` +## Function: renderTransparent() -If your style uses more than one source, you need to use either the -`source` property or the `layers` property to limit rendering to a single vector source. The -`source` property corresponds to the id of a vector source in your Mapbox style. +> **renderTransparent**(`enabled`): `void` -* * * +Configure whether features with a transparent style should be rendered. When +set to `true`, it will be possible to hit detect content that is not visible, +like transparent fills of polygons, using `ol/layer/Layer#getFeatures()` or +`ol/Map#getFeaturesAtPixel()` -#### styleUrl +### Parameters -• **styleUrl**: `string` +• **enabled**: `boolean` -The URL of the Mapbox style object to use for this layer. For a -style created with Mapbox Studio and hosted on Mapbox, this will look like -'mapbox://styles/you/your-style'. +Rendering of transparent elements is enabled. +Default is `false`. -* * * +### Returns -#### updateWhileAnimating +`void` -• **updateWhileAnimating**: `boolean` + -When set to `true`, feature batches will be -recreated during animations. This means that no vectors will be shown clipped, but the setting -will have a performance impact for large amounts of vector data. When set to `false`, batches -will be recreated when no animation is active. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### updateWhileInteracting - -• **updateWhileInteracting**: `boolean` +## Function: setFeatureState() -When set to `true`, feature batches will be -recreated during interactions. See also `updateWhileAnimating`. +> **setFeatureState**(`mapOrLayer`, `feature`, `state`): `void` -* * * +Sets or removes a feature state. The feature state is taken into account for styling, +just like the feature's properties, and can be used e.g. to conditionally render selected +features differently. -#### useInterimTilesOnError +The feature state will be stored on the OpenLayers layer matching the feature identifier, in the +`mapbox-featurestate` property. -• **useInterimTilesOnError**: `boolean` +### Parameters -Use interim tiles on error. +• **mapOrLayer**: `Map` \| `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> -* * * +OpenLayers Map or layer to set the feature +state on. -#### visible +• **feature**: [`FeatureIdentifier`](#-internal-interfacesfeatureidentifiermd) -• **visible**: `boolean` +Feature identifier. -Visibility. +• **state**: `any` -* * * +Feature state. Set to `null` to remove the feature state. -#### zIndex +### Returns -• **zIndex**: `number` +`void` -The z-index for layer rendering. At rendering time, the layers -will be ordered, first by Z-index and then by position. When `undefined`, a `zIndex` of 0 is assumed -for layers that are added to the map's `layers` collection, or `Infinity` when the layer's `setMap()` -method was used. + - +[**ol-mapbox-style**](#readmemd) • **Docs** -## Interface: Options\\<> +* * * -[\\<internal>](#modulesinternal_md).Options +## Function: stylefunction() -### Table of contents +> **stylefunction**(`olLayer`, `glStyle`, `sourceOrLayers`, `resolutions`, `spriteData`, `spriteImageUrl`, `getFonts`, `getImage`?, ...`args`?): `StyleFunction` -#### Properties +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. -- [accessToken](#accessToken) -- [accessTokenParam](#accessTokenParam) -- [getImage](#getImage) -- [projection](#projection) -- [resolutions](#resolutions) -- [styleUrl](#styleUrl) -- [transformRequest](#transformRequest) -- [webfonts](#webfonts) +Two additional properties will be set on the provided layer: -### 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. -#### accessToken +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: -• **accessToken**: `string` +```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; + } +}); +``` -Access token for 'mapbox://' urls. +### Parameters -* * * +• **olLayer**: `VectorLayer`\\<`VectorSource`\\<`any`>, `any`> \| `VectorTileLayer`\\<`VectorTile`\\<`any`>, `any`> -#### accessTokenParam +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. -• **accessTokenParam**: `string` +• **glStyle**: `any` -Access token param. For internal use. +Mapbox Style object. -* * * +• **sourceOrLayers**: `string` \| `string`\[] -#### getImage +`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. -• **getImage**: (`arg0`: `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`>, `arg1`: `string`) => `string` \| `HTMLCanvasElement` \| `HTMLImageElement` +• **resolutions**: `number`\[]= `defaultResolutions` -Function that returns an image for an icon name. If the result is an HTMLImageElement, it must already be -loaded. The layer can be used to call layer.changed() when the loading and processing of the image has finished. -This function be used for icons not in the sprite or to override sprite icons. +Resolutions for mapping resolution to zoom level. -##### Type declaration +• **spriteData**: `any`= `undefined` -▸ (`arg0`, `arg1`): `string` \| `HTMLCanvasElement` \| `HTMLImageElement` +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. -###### Parameters +• **spriteImageUrl**: `string` \| `Request` \| `Promise`\\<`string` \| `Request`>= `undefined` -| Name | Type | -| :----- | :--------------------------------------------------------- | -| `arg0` | `VectorLayer`\\<`any`> \| `VectorTileLayer`\\<`any`> | -| `arg1` | `string` | +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. -###### Returns +• **getFonts**= `undefined` -`string` \| `HTMLCanvasElement` \| `HTMLImageElement` +Function that +receives a font stack and the url template from the GL style's `metadata['ol:webfonts']` +property (if set) 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. -* * * +• **getImage?**= `undefined` -#### projection +Function that returns an image or a URL for an image name. If the result is an HTMLImageElement, it must already be +loaded. The layer can be used to call layer.changed() when the loading and processing of the image has finished. +This function can be used for icons not in the sprite or to override sprite icons. -• **projection**: `string` +• ...**args?**: `any` -Only useful when working with non-standard projections. -Code of a projection registered with OpenLayers. All sources of the style must be provided in this -projection. The projection must also have a valid extent defined, which will be used to determine the -origin and resolutions of the tile grid for all tiled sources of the style. When provided, the bbox -placeholder in tile and geojson urls changes: the default is `{bbox-epsg-3857}`, when projection is e.g. -set to `EPSG:4326`, the bbox placeholder will be `{bbox-epsg-4326}`. +### Returns -* * * +`StyleFunction` -#### resolutions +Style function for use in +`ol.layer.Vector` or `ol.layer.VectorTile`. -• **resolutions**: `number`\[] + -Only useful when working with non-standard projections. -Resolutions for mapping resolution to the `zoom` used in the Mapbox style. +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### styleUrl - -• **styleUrl**: `string` +## Function: updateMapboxLayer() -URL of the Mapbox GL style. Required for styles that were provided -as object, when they contain a relative sprite url, or sources referencing data by relative url. +> **updateMapboxLayer**(`mapOrGroup`, `mapboxLayer`): `void` -* * * +Update a Mapbox Layer object in the style. The map will be re-rendered with the new style. -#### transformRequest +### Parameters -• **transformRequest**: (`arg0`: `string`, `arg1`: [`ResourceType`](#ResourceType)) => `string` \| `void` \| `Request` \| `Promise`\\<`string` \| `Request`> +• **mapOrGroup**: `Map` \| `LayerGroup` -Function for controlling how `ol-mapbox-style` fetches resources. Can be used for modifying -the url, adding headers or setting credentials options. Called with the url and the resource -type as arguments, this function is supposed to return a `Request` or a url `string`, or a promise tehereof. -Without a return value the original request will not be modified. +The Map or LayerGroup `apply` was called on. -##### Type declaration +• **mapboxLayer**: `any` -▸ (`arg0`, `arg1`): `string` \| `void` \| `Request` \| `Promise`\\<`string` \| `Request`> +Updated Mapbox Layer object. -###### Parameters +### Returns -| Name | Type | -| :----- | :------------------------------ | -| `arg0` | `string` | -| `arg1` | [`ResourceType`](#ResourceType) | +`void` -###### Returns + -`string` \| `void` \| `Request` \| `Promise`\\<`string` \| `Request`> +[**ol-mapbox-style**](#readmemd) • **Docs** * * * -#### webfonts +## Function: updateMapboxSource() -• **webfonts**: `string` +> **updateMapboxSource**(`mapOrGroup`, `id`, `mapboxSource`): `Promise`\\<`Source`> -Template for resolving webfonts. Can be used to specify where to fetch -web fonts when no `ol:webfonts` metadata is set in the style object. See `getFonts()` and the -"Font handling" section in `README.md` for details. +Updates a Mapbox source object in the style. The according OpenLayers source will be replaced +and the map will be re-rendered. - +### Parameters -## Module: \\<internal> +• **mapOrGroup**: `Map` \| `LayerGroup` -### Table of contents +The Map or LayerGroup `apply` was called on. -#### Interfaces +• **id**: `string` -- [ApplyStyleOptions](#interfacesinternal_applystyleoptionsmd) -- [FeatureIdentifier](#interfacesinternal_featureidentifiermd) -- [Options](#interfacesinternal_optionsmd) -- [Options](#interfacesinternal_options-1md) +Key of the source in the `sources` object literal. -#### Type Aliases +• **mapboxSource**: `any` -- [ResourceType](#ResourceType) +Mapbox source object. -### Type Aliases +### Returns -#### ResourceType +`Promise`\\<`Source`> -Ƭ **ResourceType**\\<>: `"Style"` \| `"Source"` \| `"Sprite"` \| `"SpriteImage"` \| `"Tiles"` \| `"GeoJSON"` +Promise that resolves when the source has been updated. diff --git a/package-lock.json b/package-lock.json index 030d266a..0e8e4cd4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "ol-mapbox-style", - "version": "12.3.4", + "version": "12.3.5", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "ol-mapbox-style", - "version": "12.3.4", + "version": "12.3.5", "license": "BSD-2-Clause", "dependencies": { "@mapbox/mapbox-gl-style-spec": "^13.23.1", diff --git a/package.json b/package.json index a11e5f3e..e2fa72c8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ol-mapbox-style", - "version": "12.3.4", + "version": "12.3.5", "description": "Create OpenLayers maps from Mapbox Style objects", "type": "module", "browser": "dist/index.js",