Package com.vaadin.flow.component.map

Class Map

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.map.MapBase
com.vaadin.flow.component.map.Map
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasSize, HasStyle, HasTheme, HasThemeVariant<MapVariant>, Serializable
@Tag("vaadin-map") @NpmPackage(value="@vaadin/map",version="24.3.22") @NpmPackage(value="proj4",version="2.9.2") @JsModule("@vaadin/map/src/vaadin-map.js") @JsModule("./vaadin-map/mapConnector.js") public class Map extends MapBase
Map is a component for displaying geographic maps from various sources. It supports multiple layers, tiled and full image sources, adding markers, and interaction through events.

Each map consists of one or more Layers that display geographical data. Each layer has a Source that provides that data. The Map component provides several types of layers (for example TileLayer, VectorLayer, ImageLayer), as well as several types of sources that can be used with each type of layer (for example OSMSource, XYZSource, VectorSource).

The map component comes pre-configured with a background layer, which by default is a TileLayer using an OSMSource, which means that it displays tiled image data from the OpenStreeMap service. The background layer of the map can be replaced using setBackgroundLayer(Layer). The component is also pre-configured with a FeatureLayer, accessible with getFeatureLayer(), that allows to quickly display geographical features, such as markers (see MarkerFeature), on top of a map. Custom layers can be added or removed using addLayer(Layer) and removeLayer(Layer).

The viewport of the map is controlled through a View, which allows setting the center, zoom level and rotation. The map's view can be accessed through MapBase.getView().

The default projection, or coordinate system, for all coordinates passed to, or returned from the public API is EPSG:4326, also referred to as GPS coordinates. This is called the user projection. Internally the component converts all coordinates into the projection that is used by the map's View, which is referred to as the view projection. The user projection can be changed using setUserProjection(String). Out of the box, the map component has support for the EPSG:4326 and EPSG:3857 projections. Custom coordinate projections can be defined using defineProjection(String, String).

See Also:

  • Constructor Details

    • Map

      public Map()

  • Method Details

    • setUserProjection

      public static void setUserProjection(String projection)
      Sets the projection (or coordinate system) to use for all coordinates. That means that all coordinates passed to, or returned from the public API, must be in this projection. Internally the coordinates will be converted into the projection that is used by the map's View.

      By default, the user projection is set to EPSG:4326, also known as latitude / longitude, or GPS coordinates.

      This setting affects all maps in the current UI, currently it is not possible to configure this per map instance. This method may only be invoked inside of UI threads, and will throw otherwise. This setting being scoped to the current UI means that it will stay active when navigating between pages using the Vaadin router, but not when doing a "hard" location change, or when reloading the page. As such it is recommended to apply this setting on every page that displays maps. Note that when using the preserve on refresh feature, a view's constructor is not called. In that case this setting can be applied in an attach listener.

      This method should be called before creating any maps. Changing this setting does not affect existing maps, specifically the component does not convert coordinates configured in an existing map into the new projection. Instead, existing maps should be recreated after changing this setting.

      Parameters:
      projection - the user projection to use for all public facing API

    • defineProjection

      public static void defineProjection(String projectionName, String wksDefinition)
      Defines a custom coordinate projection that can then be used as user projection or view projection. Defining a projection requires a name, which is then used to reference it when setting a user or view projection, as well as a projection definition in the Well Known Text (WKS) format. A handy resource for looking up WKS definitions is epsg.io, which allows to search for projections, get coordinates from a map, as well as transform coordinates between projections.

      This definition is valid for the lifetime of the current UI. This method may only be invoked inside of UI threads, and will throw otherwise. This definition being scoped to the current UI means that it will stay active when navigating between pages using the Vaadin router, but not when doing a "hard" location change, or when reloading the page. As such it is recommended to apply this definition on every page that displays maps. Note that when using the preserve on refresh feature, a view's constructor is not called. In that case this definition can be applied in an attach listener.

      This method should be called before creating any maps that want to make use of this projection, and before setting it as a custom user projection.

      Parameters:
      projectionName - the name of the projection that can be referenced when setting a user or view projection
      wksDefinition - the Well Known Text (WKS) definition of the projection
      See Also:

    • getRawConfiguration

      public Configuration getRawConfiguration()

    • getBackgroundLayer

      public Layer getBackgroundLayer()
      Background layer of the map. Every new instance of a Map is initialized with a background layer. By default, the background layer will be a TileLayer using an OSMSource, which means it will display tiled map data from the official OpenStreetMap server.
      Returns:
      the background layer of the map

    • setBackgroundLayer

      public void setBackgroundLayer(Layer backgroundLayer)
      Sets the background layer of the map. The layer will be prepended before all other layers, which means it will be rendered in the background by default. The background layer is not intended to be removed, and thus can not be set to null. For use-cases where you want to use a dynamic set of layers, consider setting the first layer as background layer, and then adding the remaining layers using addLayer(Layer).
      Parameters:
      backgroundLayer - the new background layer, not null

    • getFeatureLayer

      public FeatureLayer getFeatureLayer()
      The feature layer of the map. Every new instance of a Map has a pre-configured FeatureLayer for convenience, to allow quickly adding geographical features without requiring to set up a layer. Note that it is possible to add additional feature layers with addLayer(Layer) if splitting up features into different layers is beneficial for a use-case.
      Returns:
      the feature layer of the map

    • addLayer

      public void addLayer(Layer layer)
      Adds a layer to the map. The layer will be appended to the list of layers, meaning that it will be rendered last / on top of previously added layers by default. For more fine-grained control of the layer rendering order, use Layer.setzIndex(Integer).
      Parameters:
      layer - the layer to be added

    • removeLayer

      public void removeLayer(Layer layer)
      Remove a layer from the map
      Parameters:
      layer - the layer to be removed

    • getCenter

      public Coordinate getCenter()
      Gets center coordinates of the map's viewport

      This is a convenience method that delegates to the map's internal View. See MapBase.getView() for accessing other properties of the view.

      Returns:
      current center of the viewport

    • setCenter

      public void setCenter(Coordinate center)
      Sets the center of the map's viewport. Coordinates must be specified in the map's user projection, which by default is EPSG:4326, also referred to as GPS coordinates. If the user projection has been changed using setUserProjection(String), then coordinates must be specified in that projection instead.

      This is a convenience method that delegates to the map's internal View. See MapBase.getView() for accessing other properties of the view.

      Note that the user projection is a different concept than the view projection set in the map's View. The view projection affects how map data is interpreted and rendered, while the user projection defines the coordinate system that all coordinates passed to, or returned from the public API must be in.

      Parameters:
      center - new center of the viewport

    • getZoom

      public double getZoom()
      Gets zoom level of the map's viewport, defaults to 0

      This is a convenience method that delegates to the map's internal View. See MapBase.getView() for accessing other properties of the view.

      Returns:
      current zoom level

    • setZoom

      public void setZoom(double zoom)
      Sets the zoom level of the map's viewport. The zoom level is a decimal value that starts at 0 as the most zoomed-out level, and then continually increases to zoom further in. By default, the maximum zoom level is currently restricted to 28. In practical terms, the level of detail of the map data that a map service provides determines how useful higher zoom levels are.

      This is a convenience method that delegates to the map's internal View. See MapBase.getView() for accessing other properties of the view.

      Parameters:
      zoom - new zoom level