Classdesc

The map is the core component of OpenLayers. For a map to render, a view, one or more layers, and a target container are needed:

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import OSM from 'ol/source/OSM.js';

const map = new Map({
view: new View({
center: [0, 0],
zoom: 1,
}),
layers: [
new TileLayer({
source: new OSM(),
}),
],
target: 'map',
});

The above snippet creates a map using a module:ol/layer/TileTileLayer to display module:ol/source/OSMOSM OSM data and render it to a DOM element with the id map.

The constructor places a viewport container (with CSS class name ol-viewport) in the target element (see getViewport()), and then two further elements within the viewport: one with CSS class name ol-overlaycontainer-stopevent for controls and some overlays, and one with CSS class name ol-overlaycontainer for other overlays (see the stopEvent option of module:ol/Overlay~Overlay for the difference). The map itself is placed in a further element within the viewport.

Layers are stored as a module:ol/CollectionCollection in layerGroups. A top-level group is provided by the library. This is what is accessed by getLayerGroup and setLayerGroup. Layers entered in the options are added to this group, and addLayer and removeLayer change the layer collection in the group. getLayers is a convenience function for getLayerGroup().getLayers(). Note that module:ol/layer/GroupLayerGroup is a subclass of module:ol/layer/Base~BaseLayer, so layers entered in the options or added with addLayer can be groups, which can contain further groups, and so on.

Fires

import("./MapBrowserEvent.js").MapBrowserEvent

Fires

import("./MapEvent.js").MapEvent

Fires

import("./render/Event.js").default#precompose

Fires

import("./render/Event.js").default#postcompose

Fires

import("./render/Event.js").default#rendercomplete

Api

Hierarchy (view full)

Constructors

Properties

controls: Collection<Control>
disposed: boolean

The object has already been disposed.

interactions: Collection<Interaction>
on: MapEventHandler<EventsKey>
once: MapEventHandler<EventsKey>
resizeObserver_: ResizeObserver
un: MapEventHandler<void>

Methods

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

  • Add the given control to the map.

    Parameters

    • control: Control

      Control.

    Returns void

    Api

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

  • Add the given interaction to the map. If you want to add an interaction at another point of the collection use getInteractions() and the methods available on module:ol/Collection~Collection. This can be used to stop the event propagation from the handleEvent function. The interactions get to handle the events in the reverse order of this collection.

    Parameters

    • interaction: Interaction

      Interaction to add.

    Returns void

    Api

  • Adds the given layer to the top of this map. If you want to add a layer elsewhere in the stack, use getLayers() and the methods available on module:ol/Collection~Collection.

    Parameters

    • layer: BaseLayer

      Layer.

    Returns void

    Api

  • Add the given overlay to the map.

    Parameters

    Returns void

    Api

  • Protected

    Apply any properties from another object without triggering events.

    Parameters

    • source: Object

      The source object.

    Returns void

  • Increases the revision counter and dispatches a 'change' event.

    Returns void

    Api

  • Dispatches an event and calls all listeners listening for events of this type. The event parameter can either be a string or an Object with a type property.

    Parameters

    • event: string | BaseEvent

      Event object.

    Returns undefined | boolean

    false if anyone called preventDefault on the event object or if any of the listeners returned false.

    Api

  • Clean up.

    Returns void

  • Protected

    Extension point for disposable objects.

    Returns void

  • This method is meant to be called in a layer's prerender listener. It causes all collected declutter items to be decluttered and rendered on the map immediately. This is useful for layers that need to appear entirely above the decluttered items of layers lower in the layer stack.

    Returns void

    Api

  • Detect features that intersect a pixel on the viewport, and execute a callback with each intersecting feature. Layers included in the detection can be configured through the layerFilter option in options.

    Type Parameters

    • T

    Parameters

    • pixel: Pixel

      Pixel.

    • callback: ((arg0, arg1, arg2) => T)

      Feature callback. The callback will be called with two arguments. The first argument is one module:ol/FeatureFeature feature or module:ol/render/FeatureRenderFeature render feature at the pixel, the second is the module:ol/layer/Layer~Layer layer of the feature and will be null for unmanaged layers. To stop detection, callback functions can return a truthy value.

    • Optional options: AtPixelOptions

      Optional options.

    Returns undefined | T

    Callback result, i.e. the return value of last callback execution, or the first truthy callback return value.

    Api

  • Gets a value.

    Parameters

    • key: string

      Key name.

    Returns any

    Value.

    Api

  • Get all layers from all layer groups.

    Returns Layer<external.olsource.Source, LayerRenderer<any>>[]

    Layers.

    Api

  • Get the map controls. Modifying this collection changes the controls associated with the map.

    Returns Collection<Control>

    Controls.

    Api

  • Get the coordinate for a given pixel. This returns a coordinate in the user projection.

    Parameters

    • pixel: Pixel

      Pixel position in the map viewport.

    Returns Coordinate

    The coordinate for the pixel position.

    Api

  • Get the coordinate for a given pixel. This returns a coordinate in the map view projection.

    Parameters

    • pixel: Pixel

      Pixel position in the map viewport.

    Returns Coordinate

    The coordinate for the pixel position.

  • Returns the coordinate in user projection for a browser event.

    Parameters

    • event: MouseEvent

      Event.

    Returns Coordinate

    Coordinate.

    Api

  • Returns the coordinate in view projection for a browser event.

    Parameters

    • event: MouseEvent

      Event.

    Returns Coordinate

    Coordinate.

  • Returns the map pixel position for a browser event relative to the viewport.

    Parameters

    • event: UIEvent | {
          clientX: number;
          clientY: number;
      }

      Event.

    Returns Pixel

    Pixel.

    Api

  • Get all features that intersect a pixel on the viewport.

    Parameters

    • pixel: Pixel

      Pixel.

    • Optional options: AtPixelOptions

      Optional options.

    Returns FeatureLike[]

    The detected features or an empty array if none were found.

    Api

  • Get the map interactions. Modifying this collection changes the interactions associated with the map.

    Interactions are used for e.g. pan, zoom and rotate.

    Returns Collection<Interaction>

    Interactions.

    Api

  • Get a list of object property names.

    Returns string[]

    List of property names.

    Api

  • Get the layergroup associated with this map.

    Returns LayerGroup

    A layer group containing the layers in this map.

    Observable

    Api

  • Get the collection of layers associated with this map.

    Returns Collection<BaseLayer>

    Layers.

    Api

  • Get the listeners for a specified event type. Listeners are returned in the order that they will be called in.

    Parameters

    • type: string

      Type.

    Returns undefined | Listener[]

    Listeners.

  • Returns boolean

    Layers have sources that are still loading.

  • Get an overlay by its identifier (the value returned by overlay.getId()). Note that the index treats string and numeric identifiers as the same. So map.getOverlayById(2) will return an overlay with id '2' or 2.

    Parameters

    • id: string | number

      Overlay identifier.

    Returns Overlay

    Overlay.

    Api

  • Get the element that serves as the container for overlays. Elements added to this container will let mousedown and touchstart events through to the map, so clicks and gestures on an overlay will trigger module:ol/MapBrowserEvent~MapBrowserEvent events.

    Returns HTMLElement

    The map's overlay container.

  • Get the element that serves as a container for overlays that don't allow event propagation. Elements added to this container won't let mousedown and touchstart events through to the map, so clicks and gestures on an overlay don't trigger any module:ol/MapBrowserEvent~MapBrowserEvent.

    Returns HTMLElement

    The map's overlay container that stops events.

  • Get the map overlays. Modifying this collection changes the overlays associated with the map.

    Returns Collection<Overlay>

    Overlays.

    Api

  • Returns Document

    The document where the map is displayed.

  • Get the pixel for a coordinate. This takes a coordinate in the user projection and returns the corresponding pixel.

    Parameters

    • coordinate: Coordinate

      A map coordinate.

    Returns Pixel

    A pixel position in the map viewport.

    Api

  • Get the pixel for a coordinate. This takes a coordinate in the map view projection and returns the corresponding pixel.

    Parameters

    • coordinate: Coordinate

      A map coordinate.

    Returns Pixel

    A pixel position in the map viewport.

  • Get an object of all property names and values.

    Returns {
        [x: string]: any;
    }

    Object.

    • [x: string]: any

    Api

  • Get an object of all property names and values.

    Returns null | {
        [x: string]: any;
    }

    Object.

  • Get the map renderer.

    Returns null | MapRenderer

    Renderer

  • Get the version number for this object. Each time the object is modified, its version number will be incremented.

    Returns number

    Revision.

    Api

  • Get the size of this map.

    Returns undefined | Size

    The size in pixels of the map in the DOM.

    Observable

    Api

  • Get the target in which this map is rendered. Note that this returns what is entered as an option or in setTarget: if that was an element, it returns an element; if a string, it returns that.

    Returns undefined | string | HTMLElement

    The Element or id of the Element that the map is rendered in.

    Observable

    Api

  • Get the DOM element into which this map is rendered. In contrast to getTarget this method always return an Element, or null if the map has no target.

    Returns HTMLElement

    The element that the map is rendered in.

    Api

  • Parameters

    • tile: external.ol.Tile

      Tile.

    • tileSourceKey: string

      Tile source key.

    • tileCenter: Coordinate

      Tile center.

    • tileResolution: number

      Tile resolution.

    Returns number

    Tile priority.

  • Get the view associated with this map. A view manages properties such as center and resolution.

    Returns external.ol.View

    The view that controls this map.

    Observable

    Api

  • Get the element that serves as the map viewport.

    Returns HTMLElement

    Viewport.

    Api

  • Parameters

    • browserEvent: UIEvent

      Browser event.

    • Optional type: string

      Type.

    Returns void

  • Parameters

    Returns void

  • Protected

    Returns void

  • Detect if features intersect a pixel on the viewport. Layers included in the detection can be configured through the layerFilter option.

    Parameters

    • pixel: Pixel

      Pixel.

    • Optional options: AtPixelOptions

      Optional options.

    Returns boolean

    Is there a feature at the given pixel?

    Api

  • Parameters

    • Optional type: string

      Type. If not provided, true will be returned if this event target has any listeners.

    Returns boolean

    Has listeners.

  • Returns boolean

    The object has properties.

  • Returns boolean

    Is rendered.

  • Parameters

    • key: string

      Key name.

    • oldValue: any

      Old value.

    Returns void

  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

  • Redraws all text after new fonts have loaded

    Returns void

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

  • Remove the given control from the map.

    Parameters

    • control: Control

      Control.

    Returns undefined | Control

    The removed control (or undefined if the control was not found).

    Api

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

  • Remove the given interaction from the map.

    Parameters

    • interaction: Interaction

      Interaction to remove.

    Returns undefined | Interaction

    The removed interaction (or undefined if the interaction was not found).

    Api

  • Removes the given layer from the map.

    Parameters

    • layer: BaseLayer

      Layer.

    Returns undefined | BaseLayer

    The removed layer (or undefined if the layer was not found).

    Api

  • Remove the given overlay from the map.

    Parameters

    Returns undefined | Overlay

    The removed overlay (or undefined if the overlay was not found).

    Api

  • Request a map rendering (at the next animation frame).

    Returns void

    Api

  • Requests an immediate render in a synchronous manner.

    Returns void

    Api

  • Sets a value.

    Parameters

    • key: string

      Key name.

    • value: any

      Value.

    • Optional silent: boolean

      Update without triggering an event.

    Returns void

    Api

  • Sets the layergroup of this map.

    Parameters

    • layerGroup: LayerGroup

      A layer group containing the layers in this map.

    Returns void

    Observable

    Api

  • Clear any existing layers and add layers to the map.

    Parameters

    • layers: BaseLayer[] | Collection<BaseLayer>

      The layers to be added to the map.

    Returns void

    Api

  • Sets a collection of key-value pairs. Note that this changes any existing properties and adds new ones (it does not remove any existing properties).

    Parameters

    • values: {
          [x: string]: any;
      }

      Values.

      • [x: string]: any
    • Optional silent: boolean

      Update without triggering an event.

    Returns void

    Api

  • Set the size of this map.

    Parameters

    • size: undefined | Size

      The size in pixels of the map in the DOM.

    Returns void

    Observable

    Api

  • Set the target element to render this map into.

    Parameters

    • Optional target: string | HTMLElement

      The Element or id of the Element that the map is rendered in.

    Returns void

    Observable

    Api

  • Set the view for this map.

    Parameters

    • view: external.ol.View | Promise<ViewOptions>

      The view that controls this map. It is also possible to pass a promise that resolves to options for constructing a view. This alternative allows view properties to be resolved by sources or other components that load view-related metadata.

    Returns void

    Observable

    Api

  • Protected

    Unlisten for a certain type of event.

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns void

  • Unsets a property.

    Parameters

    • key: string

      Key name.

    • Optional silent: boolean

      Unset without triggering an event.

    Returns void

    Api

  • Force a recalculation of the map viewport size. This should be called when third-party code changes the size of the map viewport.

    Returns void

    Api