@maptiler/sdk

import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions } from 'maplibre-gl'; import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client'; import { SdkConfig } from './config'; import { LanguageInfo } from './language'; import { MinimapOptionsInput } from './controls/Minimap'; import { Telemetry } from './Telemetry'; import { CubemapDefinition, CubemapLayer, CubemapLayerConstructorOptions } from './custom-layers/CubemapLayer'; import { GradientDefinition, RadialGradientLayer, RadialGradientLayerConstructorOptions } from './custom-layers/RadialGradientLayer'; import { StyleSpecificationWithMetaData } from './custom-layers/extractCustomLayerStyle'; export type LoadWithTerrainEvent = { type: "loadWithTerrain"; target: Map; terrain: { source: string; exaggeration: number; }; }; export declare const GeolocationType: { POINT: "POINT"; COUNTRY: "COUNTRY"; }; /** * The type of projection, `undefined` means it's decided by the style and if the style does not contain any projection info, * if falls back to the default Mercator */ export type ProjectionTypes = "mercator" | "globe" | undefined; /** * Options to provide to the `Map` constructor */ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & { /** * Style of the map. Can be: * - a full style URL (possibly with API key) * - a shorthand with only the MapTIler style name (eg. `"streets-v2"`) * - a longer form with the prefix `"maptiler://"` (eg. `"maptiler://streets-v2"`) */ style?: ReferenceMapStyle | MapStyleVariant | StyleSpecification | string; /** * Define the language of the map. This can be done directly with a language ISO code (eg. "en"), * the ISO code prepended with the OSM flag (eg. "name:en" or even just "name"), * or with a built-in shorthand (eg. Language.ENGLISH). * Note that this is equivalent to setting the `config.primaryLanguage` and will overwrite it. */ language?: LanguageInfo | string; /** * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting * `config.apiKey` and will overwrite it. */ apiKey?: string; /** * Shows or hides the MapTiler logo in the bottom left corner. * * For paid plans: * - `true` shows MapTiler logo * - `false` hodes MapTiler logo * - default: `false` (hide) * * For free plans: MapTiler logo always shows, regardless of the value. */ maptilerLogo?: boolean; /** * Attribution text to show in an {@link AttributionControl}. */ customAttribution?: string | Array<string>; /** * Enables 3D terrain if `true`. (default: `false`) */ terrain?: boolean; /** * Exaggeration factor of the terrain. (default: `1`, no exaggeration) */ terrainExaggeration?: number; /** * Show the navigation control. (default: `true`, will hide if `false`) */ navigationControl?: boolean | ControlPosition; /** * Show the terrain control. (default: `false`, will show if `true`) */ terrainControl?: boolean | ControlPosition; /** * Show the geolocate control. (default: `true`, will hide if `false`) */ geolocateControl?: boolean | ControlPosition; /** * Show the scale control. (default: `false`, will show if `true`) */ scaleControl?: boolean | ControlPosition; /** * Show the full screen control. (default: `false`, will show if `true`) */ fullscreenControl?: boolean | ControlPosition; /** * Detect custom external controls. (default: `false`, will detect automatically if `true`) */ customControls?: boolean | string; /** * Display a minimap in a user defined corner of the map. (default: `bottom-left` corner) * If set to true, the map will assume it is a minimap and forego the attribution control. */ minimap?: boolean | ControlPosition | MinimapOptionsInput; /** * attributionControl */ forceNoAttributionControl?: boolean; /** * Method to position the map at a given geolocation. Only if: * - `hash` is `false` * - `center` is not provided * * If the value is `true` of `"POINT"` (given by `GeolocationType.POINT`) then the positionning uses the MapTiler Cloud * Geolocation to find the non-GPS location point. * The zoom level can be provided in the `Map` constructor with the `zoom` option or will be `13` if not provided. * * If the value is `"COUNTRY"` (given by `GeolocationType.COUNTRY`) then the map is centered around the bounding box of the country. * In this case, the `zoom` option will be ignored. * * If the value is `false`, no geolocation is performed and the map centering and zooming depends on other options or on * the built-in defaults. * * If this option is non-false and the options `center` is also provided, then `center` prevails. * * Default: `false` */ geolocate?: (typeof GeolocationType)[keyof typeof GeolocationType] | boolean; /** * Show the projection control. (default: `false`, will show if `true`) */ projectionControl?: boolean | ControlPosition; /** * Whether the projection should be "mercator" or "globe". * If not provided, the style takes precedence. If provided, overwrite the style. */ projection?: ProjectionTypes; /** * Turn on/off spacebox. * * Default: { color: "#1D29F1" } */ space?: CubemapLayerConstructorOptions | boolean; halo?: RadialGradientLayerConstructorOptions | boolean; }; /** * The Map class can be instanciated to display a map in a `<div>` */ export declare class Map extends maplibregl.Map { readonly telemetry: Telemetry; private space?; private halo?; getSpace(): CubemapLayer | undefined; /** * Sets the space for the map. * @param {CubemapDefinition} space the `CubemapDefinition` options to set. * @remarks This method, at present, ** overwrites ** the current config. * If an option is not set it will internally revert to the default option * unless explicitly set when calling. */ setSpace(space: CubemapDefinition | boolean): void; /** * Enables the animations for the space layer. */ enableSpaceAnimations(): void; /** * Disables the animations for the space layer. */ disableSpaceAnimations(): void; /** * Enables the animations for the halo layer. */ enableHaloAnimations(): void; /** * Disables the animations for the halo layer. */ disableHaloAnimations(): void; /** * Sets whether the halo layer should be animated in and out. * @param active - Whether the animation should be active. */ setHaloAnimationActive(active: boolean): void; /** * Sets whether the space layer should be animated in and out. * @param active - Whether the animation should be active. */ setSpaceAnimationActive(active: boolean): void; private setSpaceFromStyle; private setHaloFromStyle; private initSpace; private initHalo; getHalo(): RadialGradientLayer | undefined; setHalo(halo: GradientDefinition): void; private options; private isTerrainEnabled; private terrainExaggeration; private primaryLanguage; private terrainGrowing; private terrainFlattening; private minimap?; private forceLanguageUpdate; private languageAlwaysBeenStyle; private isReady; private terrainAnimationDuration; private monitoredStyleUrls; private styleInProcess; private curentProjection; private originalLabelStyle; private isStyleLocalized; private languageIsUpdated; constructor(options: MapOptions); /** * Recreates the map instance with the same options. * Useful for WebGL context loss. */ recreate(): void; /** * Set the duration (millisec) of the terrain animation for growing or flattening. * Must be positive. (Built-in default: `1000` milliseconds) */ setTerrainAnimationDuration(d: number): void; /** * Awaits for _this_ Map instance to be "loaded" and returns a Promise to the Map. * If _this_ Map instance is already loaded, the Promise is resolved directly, * otherwise, it is resolved as a result of the "load" event. * @returns */ onLoadAsync(): Promise<Map>; /** * Awaits for _this_ Map instance to be "ready" and returns a Promise to the Map. * If _this_ Map instance is already ready, the Promise is resolved directly, * otherwise, it is resolved as a result of the "ready" event. * A map instance is "ready" when all the controls that can be managed by the contructor are * dealt with. This happens after the "load" event, due to the asynchronous nature * of some built-in controls. */ onReadyAsync(): Promise<Map>; /** * Awaits for _this_ Map instance to be "loaded" as well as with terrain being non-null for the first time * and returns a Promise to the Map. * If _this_ Map instance is already loaded with terrain, the Promise is resolved directly, * otherwise, it is resolved as a result of the "loadWithTerrain" event. * @returns */ onLoadWithTerrainAsync(): Promise<Map>; private monitorStyleUrl; /** * Update the style of the map. * Can be: * - a full style URL (possibly with API key) * - a shorthand with only the MapTIler style name (eg. `"streets-v2"`) * - a longer form with the prefix `"maptiler://"` (eg. `"maptiler://streets-v2"`) */ setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | StyleSpecificationWithMetaData | string, options?: StyleSwapOptions & StyleOptions): this; private spaceboxLoadingState; /** * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers) * to the map's style. * * A layer defines how data from a specified source will be styled. Read more about layer types * and available paint and layout properties in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/layers). * * @param layer - The layer to add, * conforming to either the MapLibre Style Specification's [layer definition](https://maplibre.org/maplibre-style-spec/layers) or, * less commonly, the {@link CustomLayerInterface} specification. * The MapLibre Style Specification's layer definition is appropriate for most layers. * * @param beforeId - The ID of an existing layer to insert the new layer before, * resulting in the new layer appearing visually beneath the existing layer. * If this argument is not specified, the layer will be appended to the end of the layers array * and appear visually above all other layers. * * @returns `this` */ addLayer(layer: (LayerSpecification & { source?: string | SourceSpecification; }) | CustomLayerInterface, beforeId?: string): this; /** * Moves a layer to a different z-position. * * @param id - The ID of the layer to move. * @param beforeId - The ID of an existing layer to insert the new layer before. When viewing the map, the `id` layer will appear beneath the `beforeId` layer. If `beforeId` is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map. * @returns `this` * * @example * Move a layer with ID 'polygon' before the layer with ID 'country-label'. The `polygon` layer will appear beneath the `country-label` layer on the map. * ```ts * map.moveLayer('polygon', 'country-label'); * ``` */ moveLayer(id: string, beforeId?: string): this; /** * Removes the layer with the given ID from the map's style. * * An {@link ErrorEvent} will be fired if the image parameter is invald. * * @param id - The ID of the layer to remove * @returns `this` * * @example * If a layer with ID 'state-data' exists, remove it. * ```ts * if (map.getLayer('state-data')) map.removeLayer('state-data'); * ``` */ removeLayer(id: string): this; /** * Sets the zoom extent for the specified style layer. The zoom extent includes the * [minimum zoom level](https://maplibre.org/maplibre-style-spec/layers/#minzoom) * and [maximum zoom level](https://maplibre.org/maplibre-style-spec/layers/#maxzoom)) * at which the layer will be rendered. * * Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the * minimum zoom level of the _source layer_ because the data does not exist at those zoom levels. If the minimum * zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style * layer will not be rendered at all zoom levels in the zoom range. */ setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number): this; /** * Sets the filter for the specified style layer. * * Filters control which features a style layer renders from its source. * Any feature for which the filter expression evaluates to `true` will be * rendered on the map. Those that are false will be hidden. * * Use `setFilter` to show a subset of your source data. * * To clear the filter, pass `null` or `undefined` as the second parameter. */ setFilter(layerId: string, filter?: FilterSpecification | null, options?: StyleSetterOptions): this; /** * Sets the value of a paint property in the specified style layer. * * @param layerId - The ID of the layer to set the paint property in. * @param name - The name of the paint property to set. * @param value - The value of the paint property to set. * Must be of a type appropriate for the property, as defined in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/). * @param options - Options object. * @returns `this` * @example * ```ts * map.setPaintProperty('my-layer', 'fill-color', '#faafee'); * ``` */ setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this; /** * Sets the value of a layout property in the specified style layer. * Layout properties define how the layer is styled. * Layout properties for layers of the same type are documented together. * Layers of different types have different layout properties. * See the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/) for the complete list of layout properties. * @param layerId - The ID of the layer to set the layout property in. * @param name - The name of the layout property to set. * @param value - The value of the layout property to set. * Must be of a type appropriate for the property, as defined in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/). * @param options - Options object. * @returns `this` */ setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this; /** * Sets the value of the style's glyphs property. * * @param glyphsUrl - Glyph URL to set. Must conform to the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/glyphs/). * @param options - Options object. * @returns `this` * @example * ```ts * map.setGlyphs('https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf'); * ``` */ setGlyphs(glyphsUrl: string | null, options?: StyleSetterOptions): this; private getStyleLanguage; /** * Define the primary language of the map. Note that not all the languages shorthands provided are available. */ setLanguage(language: LanguageInfo | string): void; /** * Define the primary language of the map. Note that not all the languages shorthands provided are available. */ private setPrimaryLanguage; /** * Get the primary language * @returns */ getPrimaryLanguage(): LanguageInfo; /** * Get the exaggeration factor applied to the terrain * @returns */ getTerrainExaggeration(): number; /** * Know if terrian is enabled or not * @returns */ hasTerrain(): boolean; private growTerrain; /** * Enables the 3D terrain visualization */ enableTerrain(exaggeration?: number): void; /** * Disable the 3D terrain visualization */ disableTerrain(): void; /** * Sets the 3D terrain exageration factor. * If the terrain was not enabled prior to the call of this method, * the method `.enableTerrain()` will be called. * If `animate` is `true`, the terrain transformation will be animated in the span of 1 second. * If `animate` is `false`, no animated transition to the newly defined exaggeration. */ setTerrainExaggeration(exaggeration: number, animate?: boolean): void; /** * Perform an action when the style is ready. It could be at the moment of calling this method * or later. */ private onStyleReady; fitToIpBounds(): Promise<void>; centerOnIpPoint(zoom: number | undefined): Promise<void>; getCameraHash(): string; /** * Get the SDK config object. * This is convenient to dispatch the SDK configuration to externally built layers * that do not directly have access to the SDK configuration but do have access to a Map instance. */ getSdkConfig(): SdkConfig; /** * Get the MapTiler session ID. Convenient to dispatch to externaly built component * that do not directly have access to the SDK configuration but do have access to a Map instance. * @returns */ getMaptilerSessionId(): string; /** * Updates the requestManager's transform request with a new function. * * @param transformRequest A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests. * Expected to return an object with a `url` property and optionally `headers` and `credentials` properties * * @returns {Map} `this` * * @example * map.setTransformRequest((url: string, resourceType: string) => {}); */ setTransformRequest(transformRequest: RequestTransformFunction): this; /** * Returns whether a globe projection is currently being used */ isGlobeProjection(): boolean; /** * Activate the globe projection. */ enableGlobeProjection(): void; /** * Activate the mercator projection. */ enableMercatorProjection(): void; /** * Returns `true` is the language was ever updated, meaning changed * from what is delivered in the style. * Returns `false` if language in use is the language from the style * and has never been changed. */ isLanguageUpdated(): boolean; }