ng-azure-maps

ng-azure-maps is an Angular library, mostly HTML driven wrapper of the azure-maps-controls package allowing to easilly integrate its functionalities into an Angular application.

Install the package

The package is available on npm. You need to install the dependencies to the azure-maps-* packages by yourself.

npm i --save azure-maps-control azure-maps-drawing-tools azure-maps-rest ng-azure-maps

Register the module

An AzureMapsModule can be imported from the ng-azure-maps namespace. This class exposes a forRoot method which can be called by your angular module and where the configuration of the library can be given.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';
import { AzureMapsModule } from 'ng-azure-maps';
import { environment } from '../environments/environment';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AzureMapsModule.forRoot({
      authOptions: environment.authOptions
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

AAD and SubscriptionKey authentication are supported.

How to

Please note that all the directives can be used either as html tag or applied to an html element as an attribute tag. For example, the map can be displayed using <azure-map></azure-map> or <div azure-map></div>.

Display a map

Use the azure-map directive to display a map.

<azure-map></azure-map>

You can specify different inputs on the azure-map directive to customize your display. Please refer to the Azure Maps Web SDK Documentation for more information.

<azure-map [center]="[11.47, 48.18]" mapStyle='grayscale_dark'></azure-map>

NB: To avoid conflict with the style html tag, the style to apply to the map can be found under mapStyle instead. The same applied to the type of camera which has been renamed to cameraType.

<azure-map [center]="[11.47, 48.18]" mapStyle='grayscale_dark' [zoom]="10"></azure-map>

For now, only the ready and error events are available as Output of the azure-map directive.

React to events on the map

The map events are supported on the azure-map directive. In order to avoid conflicts with the names of some input (like pitch or zoom), every event starts with on and is followed by the key of the event in PascalCase. A parameter containing the map and the event is given to the method.

The events and their description are defined on the following table.

Native event key	azure-map event	Description
`boxzoomend`	`onBoxZoomEnd`	Fired when a "box zoom" interaction ends.
`boxzoomstart`	`onBoxZoomStart`	Fired when a "box zoom" interaction starts.
`click`	`onClick`	Fired when a pointing device is pressed and released at the same point on the map.
`contextmenu`	`onContextMenu`	Fired when the right button of the mouse is clicked.
`data`	`onData`	Fired when any map data loads or changes.
`dblclick`	`onDblClick`	Fired when a pointing device is clicked twice at the same point on the map.
`drag`	`onDrag`	Fired repeatedly during a "drag to pan" interaction on the map, popup, or HTML marker.
`dragend`	`onDragEnd`	Fired when a "drag to pan" interaction ends on the map, popup, or HTML marker.
`dragstart`	`onDragStart`	Fired when a "drag to pan" interaction starts on the map, popup, or HTML marker.
`error`	`onError`	Fired when an error occurs.
`idle`	`onIdle`	Fired after the last frame rendered before the map enters an "idle" state: No camera transitions are in progress. All currently requested tiles have loaded. All fade/transition animations have completed.
`layeradded`	`onLayerAdded`	Fired after a layer has been added to the map
`layerremoved`	`onLayerRemoved`	Fired after a layer has been removed from the map
`load`	`onLoad`	Fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.
`mousedown`	`onMouseDown`	Fired when a pointing device is pressed within the map or when on top of an element.
`mouseleave`	`onMouseLeave`	Fired when a pointing device is moved out the map or an element.
`mousemove`	`onMouseMove`	Fired when a pointing device is moved within the map or an element.
`mouseout`	`onMouseOut`	Fired when a point device leaves the map's canvas our leaves an element.
`mouseover`	`onMouseOver`	Fired when a pointing device is moved over the map or an element.
`mouseup`	`onMouseUp`	Fired when a pointing device is released within the map or when on top of an element.
`move`	`onMove`	Fired repeatedly during an animated transition from one view to another, as the result of either user interaction or methods.
`moveend`	`onMoveEnd`	Fired just after the map completes a transition from one view to another, as the result of either user interaction or methods.
`movestart`	`onMoveStart`	Fired just before the map begins a transition from one view to another, as the result of either user interaction or methods.
`pitch`	`onPitch`	Fired whenever the map's pitch (tilt) changes as the result of either user interaction or methods.
`pitchend`	`onPitchEnd`	Fired immediately after the map's pitch (tilt) finishes changing as the result of either user interaction or methods.
`pitchstart`	`onPitchStart`	Fired whenever the map's pitch (tilt) begins a change as the result of either user interaction or methods.
`render`	`onRender`	Fired whenever the map is drawn to the screen, as the result of: A change to the map's position, zoom, pitch, or bearing. A change to the map's style. A change to a `DataSource` source. The loading of a vector tile, GeoJSON file, glyph, or sprite.
`ready`	`onReady`	Fired when the minimum required map resources are loaded before the map is ready to be programmatically interacted with.
`render`	`onRender`	Fired whenever the map is drawn to the screen, as the result of:
`resize`	`onResize`	Fired immediately after the map has been resized.
`rotate`	`onRotate`	Fired repeatedly during a "drag to rotate" interaction.
`rotateend`	`onRotateEnd`	Fired when a "drag to rotate" interaction ends.
`rotatestart`	`onRotateStart`	Fired when a "drag to rotate" interaction starts.
`sourcedata`	`onSourceData`	Fired when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes.
`sourceadded`	`onSourceAdded`	Fired when a DataSource or VectorTileSource is added to the map.
`sourceremoved`	`onSourceRemoved`	Fired when a DataSource or VectorTileSource is removed from the map.
`styledata`	`onStyleData`	Fired when the map's style loads or changes.
`styleimagemissing`	`onStyleImageMissing`	Fired when a layer tries to load an image from the image sprite that doesn't exist
`tokenacquired`	`onTokenAcquired`	Fired when an AAD access token is obtained.
`touchcancel`	`onTouchCancel`	Fired when a touchcancel event occurs within the map.
`touchend`	`onTouchEnd`	Fired when a touchend event occurs within the map.
`touchmove`	`onTouchMove`	Fired when a touchmove event occurs within the map.
`touchstart`	`onTouchStart`	Fired when a touchstart event occurs within the map.
`wheel`	`onWheel`	Fired when a mouse wheel event occurs within the map.
`zoom`	`onZoom`	Fired repeatedly during an animated transition from one zoom level to another, as the result of either user interaction or methods.
`zoomend`	`onZoomEnd`	Fired just after the map completes a transition from one zoom level to another, as the result of either user interaction or methods.
`zoomstart`	`onZoomStart`	Fired just before the map begins a transition from one zoom level to another, as the result of either user interaction or methods.

Add controls

Compass, pitch, style and zoom controls have their own directive, each of them accepting a position binding.

<azure-map>
  <map-zoom-control position='top-left'></map-zoom-control>
  <map-pitch-control position="top-right"></map-pitch-control>
  <map-compass-control position="bottom-left"></map-compass-control>
  <map-style-control position="bottom-right"></map-style-control>
</azure-map>

Traffic

Traffic options can be given to the azure-map using the trafficOptions input. Please refer to the Azure Maps Documentation concerning the traffic options.

import { Component } from '@angular/core';
import * as atlas from 'azure-maps-control';

@Component({
  selector: 'app-root',
  template: '<azure-map [center]="[11.47, 48.18]" [zoom]="10" mapStyle="grayscale_light" [trafficOptions]="trafficOptions"></azure-map>',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  trafficOptions: atlas.TrafficOptions = {
    flow: "relative",
    incidents: true
  };

}

HtmlMarkers

You can add HTML Markers to the map using the map-html-marker directive. Please refer to the Azure Maps Documentation concerning the available options. The map and the HTML Markers listen to the changes on the provided markers and will update them accordingly.

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: '<azure-map (onReady)="mapReady()">' +
    '<map-html-marker *ngFor="let markerPosition of markerPositions" [position]="markerPosition" [draggable]="true" (onDrag)="reverseMove($event)">' +
    '</map-html-marker>' +
    '</azure-map>',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  public markerPositions: [number, number][] = [];

  mapReady() {
    for (let i = 0; i < 10; i++) {
      this.markerPositions.push([i * 5, i * 5]);
    }
  }
  
  public reverseMove(markerEvent: IMarkerEvent) {
    markerEvent.marker.setOptions({
      position: [-markerEvent.event.target.options.position[0],-markerEvent.event.target.options.position[1]]
    });
  }
}

React to events on HTMLMarkers

The HTMLMarkers events are supported on the map-html-marker directive. Every event starts with on and is followed by the key of the event in PascalCase. A parameter containing the htmlMarker and the event is given to the method.

Dragging events are triggered only if the HTMLMarker is set to draggable: true.

The events and their description are defined on the following table.

Native event key	HTMLMarker event	Description
`click`	`onClick`	Fired when a pointing device is pressed and released at the same point on the marker.
`contextmenu`	`onContextMenu`	Fired when the right button of the mouse is clicked on the marker.
`dblclick`	`onDblClick`	Fired when a pointing device is clicked twice at the same point on the marker.
`drag`	`onDrag`	Fired repeatedly during a "drag to pan" interaction on the HTML marker.
`dragend`	`onDragEnd`	Fired when a "drag to pan" interaction ends on the HTML marker.
`dragstart`	`onDragStart`	Fired when a "drag to pan" interaction starts on the HTML marker.
`keydown`	`onKeyDown`	Fired when key is pressed down on the HTML marker.
`keypress`	`onKeyPress`	Fired when key is pressed on the HTML marker.
`keyup`	`onKeyUp`	Fired when key is pressed up on the HTML marker.
`mousedown`	`onMouseDown`	Fired when a pointing device is pressed within the HTML marker or when on top of an element.
`mouseenter`	`onMouseEnter`	Fired when a pointing device is initially moved over the HTML marker or an element.
`mouseleave`	`onMouseLeave`	Fired when a pointing device is moved out the HTML marker or an element.
`mousemove`	`onMouseMove`	Fired when a pointing device is moved within the HTML marker or an element.
`mouseout`	`onMouseOut`	Fired when a point device leaves the HTML marker's canvas our leaves an element.
`mouseover`	`onMouseOver`	Fired when a pointing device is moved over the HTML marker or an element.
`mouseup`	`onMouseUp`	Fired when a pointing device is released within the HTML Marker or when on top of an element.

Drawing toolbar

The drawing toolbar can be added using the map-drawing-toolbar directive.

The drawingChanged, drawingChanging, drawingComplete, drawingModeChanged and drawingStarted events are available as Output of the directive.

<azure-map>
  <map-drawing-toolbar position="top-right" toolbarStyle="dark"></map-drawing-toolbar>
</azure-map>

NB: To avoid conflict with the style html tag, the style to apply to the toolbar can be found under toolbarStyle instead.

Please refer to the Azure Maps Documentation for customization and events.

Layers

The layers are directly linked to the map and one of its datasources. A data source can be added directly as a binding on the azure-map directive.

<azure-map [dataSources]="[dataSource, dataSourceRed]"></azure-map>

Symbol Layers

A symbol layer can be added using the map-symbol-layer directive. The id of the data source to display on the layer can be specified on the dataSourceId binding on the directive.