@nativescript/google-maps

A plugin that allows you to use the Maps SDK to access Google Maps features.

Contents

• Prerequisites

• Installation

• Use @nativescript/google-maps with Core

  • Use @nativescript/google-maps with Angular
  • Use @nativescript/google-maps with Vue

• API

  • MapView Class

    • Events
    • Properties

  • GoogleMap Object

    • Properties
    • Methods

  • Control the camera

    • Camera Position
    • Projection

  • Map Customization

    • UISettings
    • Setting the map type
    • MapType enum
    • Styling The Map

  • Markers

    • Adding Markers
    • Marker Object
    • MarkerOptions
    • Removing Markers

  • Circles

    • Adding Circles
    • CircleOptions
    • Removing Circles

  • Polygons

    • Adding Polygons
    • PolygonOptions
    • Removing Polygons

  • Polylines

    • Adding Polylines
    • PolylineOptions
    • Removing Polylines

  • Ground Overlays

    • Adding Ground Overlays
    • GroundOverlayOptions
    • Removing Ground Overlays

  • Tile Overlays

    • Adding Tile Overlays
    • TileOverlayOptions
    • Removing Tile Overlays
    • Tile Providers

Prerequisites

1. To use the Google Maps API, register your app in the Google API Console and obtain an API key.

2. Add the Google Maps API key to your app.

Android

To add the API key for Android, modify the AndroidManifest.xml file and add the <meta-data> tag with the com.google.android.geo.API_KEY as its name and the key as the value.

<application
  android:name="com.tns.NativeScriptApplication"
  android:allowBackup="true"
  android:icon="@mipmap/ic_launcher"
  android:label="@string/app_name"
  android:theme="@style/AppTheme"
  android:hardwareAccelerated="true">

  <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="yourKey"/>
</application>

iOS

To add the API key for iOS, add the TNSGoogleMapsAPIKey key and the API key as the value to the Info.plist file, located at App_Resources/iOS.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>TNSGoogleMapsAPIKey</key>
    <string>yourKey</string>
  </dict>
</plist>

Installation

npm install @nativescript/google-maps

To use the plugin in the different NativeScript flavors, modify the main.ts to import and then register it.

Use @nativescript/google-maps with core

1. Register the plugin namespace with Page's xmlns attribute providing your prefix( map, for example).

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:map="@nativescript/google-maps">

2. Access the <MapView> using the the map prefix.

<map:MapView ...

Below is the complete code from the 2 preceding steps:

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:map="@nativescript/google-maps">
    <map:MapView
        lat="{{lat}}"
        lng="{{lng}}"
        zoom="{{zoom}}"
        bearing="{{bearing}}"
        tilt="{{tilt}}"
        mapTap="{{onTap}}"
        mapLongPress="{{onLongPress}}"
        markerTap="{{onMarkerTap}}"
    />
</Page>

3. To manage the mapping features, listen to the map view's ready event and get the reference to the GoogleMap instance from the event data.

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:map="@nativescript/google-maps">
    <map:MapView
        lat="{{lat}}"
        lng="{{lng}}"
        zoom="{{zoom}}"
        bearing="{{bearing}}"
        tilt="{{tilt}}"

        ready="{{onReady}}" 👈

        mapTap="{{onTap}}"
        mapLongPress="{{onLongPress}}"
        markerTap="{{onMarkerTap}}"
    />
</Page>

To use the plugin in the different NativeScript flavors, modify the main.ts to register it.

Use @nativescript/google-maps with Angular

1. Register the plugin by adding the GoogleMapsModule to the imports array of the AppModule, in app.module.ts as follows:

import { GoogleMapsModule } from '@nativescript/google-maps/angular';

// Registering
@NgModule({
    imports: [
      GoogleMapsModule
    ],
    declarations: [
      AppComponent
    ],
    bootstrap: [AppComponent]
})

2. Add MapView to your markup.

<MapView
    (ready)="onReady($event)" 
    (mapTap)="onTap($event)"
    (mapLongPress)="onLongPress($event)"
    (markerTap)="onMarkerTap($event)"
>
</MapView>

3. To manage the mapping features, listen to the map view's ready event and get the reference to the GoogleMap instance from the event data.

Use @nativescript/google-maps with Vue

1. In the app.ts file, register the plugin by passing its reference to the use() method to the app instance.

Vue

import { createApp,registerElement } from 'nativescript-vue';
import GoogleMaps from '@nativescript/google-maps/vue'

import Home from './components/Home.vue';

const app = createApp(Home)
app.use(GoogleMaps)

Note To handle the map features, see the GoogleMap object API.

2. Add the MapView component to the markup.

<MapView
    @ready="onReady"
    @mapTap="onTap"
    @mapLongPress="onLongPress"
    @markerTap="onMarkerTap"

/>

Note To handle the map features, see the GoogleMap object API.

3. To manage the mapping features, listen to the map view's ready event and get the reference to the GoogleMap instance from the event data.

API

MapView Class

Properties

The following properties are available for adjusting the camera view on initialization:

Events

MapView provides the following events:

GoogleMap Object

This class encapsulates the core, cross-platform mapping features. Its instance is made available when the MapView fires the ready event, and this is where you'll perform the majority of your mapping tasks.

function onReady(event: MapReadyEvent) {
    const map: GoogleMap = event.map;
}

Properties

Methods

Native Map Object

GoogleMap gives you access to the platforms native map objects native | android | ios

consult the appropriate SDK reference on how to use it: iOS | Android

Control the camera

To programmatically update the camera position, call the animateCamera() method on the GoogleMap object and pass it a CameraUpdate instance.

import { CameraUpdate } from '@nativescript/google-maps';

googleMap.animateCamera(
    CameraUpdate.fromCoordinate({
            lat: -32.1234,
            lng: 125.1234
        },
        googleMap.cameraPosition.zoom
    )
);

See CameraUpdate for more methods you can call and pass to the animateCamera() method.

Camera Position

The map's current camera position can be read from the cameraPosition property of a GoogleMap object.

CameraUpdate Class

CameraUpdate provides multiple methods to create a target CameraPosition.

Projection

A projection is used to translate between on screen location and geographic coordinates on the surface of the Earth.

Map Customization

UISettings Interface

You can adjust the maps UI settings from the GoogleMap object by configuring the following properties of the uiSettings property:

Setting the map type

To set the map type, set the mapType property to one of the MapType options.

import { GoogleMap, MapType } from '@nativescript/google-maps';

map: GoogleMap;
map.mapType = MapType.Hybrid;

MapType enum

The Google Maps API offers the following five types of maps:

Styling the map

You can style the map's items, such as roads, parks, businesses, and other points of interest.

Styling works only on the normal map type. Styling does not affect indoor maps.

To style your map, use a JSON file generated by the Google Maps APIs Styling Wizard. In addition to changing the appearance of features, you can also hide features completely.

[
  {
    "featureType": "all",
    "stylers": [
      { "color": "#C0C0C0" }
    ]
  },{
    "featureType": "road.arterial",
    "elementType": "geometry",
    "stylers": [
      { "color": "#CCFFFF" }
    ]
  },{
    "featureType": "landscape",
    "elementType": "labels",
    "stylers": [
      { "visibility": "off" }
    ]
  }
]

To apply a custom style to your map you can set the mapStyle property on your GoogleMap object:

import { GoogleMap } from '@nativescript/google-maps';

map: GoogleMap;
map.mapStyle = [{
    "featureType": "landscape",
    "elementType": "labels",
    "stylers": [
        { "visibility": "off" }
    ]
}];

Markers

Adding Markers

You can create markers using the GoogleMap's object addMarker method by passing it a MarkerOptions object.

function addMarker(map: GoogleMap, markerOptions: MarkerOptions): Marker {
    return map.addMarker(markerOptions);
}

addMarker returns a Marker

Marker Object

It implements the [MarkerOptions] interface and has the following additional methods.

MarkerOptions

Coordinate

Removing Markers

To remove a marker from the map, call the removeMarker() method on the GoogleMap instance and pass it the marker to be removed.

function removeMarker(map: GoogleMap, marker: Marker) {
    map.removeMarker(marker);
}

Circles

Adding Circles

To add a circle to the map, call the addCircle() method and specify its properties with a CircleOptions object.

function addCircle(map: GoogleMap, circleOptions: CircleOptions): Circle {
    return map.addCircle(circleOptions);
}

CircleOptions

Removing Circles

You can remove a circle using the GoogleMap's removeCircle() method.

function removeCircle(map: GoogleMap, circle: Circle) {
    map.removeCircle(circle);
}

Polygons

Adding Polygons

You can create polygons using the GoogleMap's object addPolygon() method by passing in the specified PolygonOptions.

function addPolygon(map: GoogleMap, polygonOptions: PolygonOptions): Polygon {
    return map.addPolygon(polygonOptions);
}

PolygonOptions

Removing Polygons

You can remove a Polygon using the GoogleMap's removePolygon function, like so:

function removePolygon(map: GoogleMap, polygon: Polygon) {
    map.removePolygon(polygon);
}

Polylines

Adding Polylines

You can create Polylines using the GoogleMap's object addPolyline function by passing it a PolylineOptions object.

function addPolyline(map: GoogleMap, polylineOptions: PolylineOptions): Polyline {
    return map.addPolyline(polylineOptions);
}

PolylineOptions

Removing Polylines

You can remove a Polyline using the GoogleMap's removePolyline function, like so:

function removePolyline(map: GoogleMap, polyline: Polyline) {
    map.removePolyline(polyline);
}

Ground Overlays

Adding Ground Overlays

You can create Ground Overlays using the GoogleMap's object addGroundOverlay function by passing in the specified GroundOverlay Options.

function addGroundOverlay(map: GoogleMap, groundOverlayOptions: GroundOverlayOptions): GroundOverlay {
    return map.addGroundOverlay(groundOverlayOptions);
}

GroundOverlayOptions

Removing Ground Overlays

You can remove a GroundOverlay using the GoogleMap's removeGroundOverlay function, like so:

function removeGroundOverlay(map: GoogleMap, groundOverlay: GroundOverlay) {
    map.removeGroundOverlay(groundOverlay);
}

Tile Overlays

Adding Tile Overlays

You can create Tile Overlays using the GoogleMap's object addTileOverlay function by passing in the specified TileOverlay Options.

function addTileOverlay(map: GoogleMap, tileOverlayOptions: TileOverlayOptions): TileOverlay {
    return map.addTileOverlay(tileOverlayOptions);
}

TileOverlayOptions

Setting tile overlay options after the tile overlay has been added to the map can have no effect on the tile overlay. To update the tile overlay, you may need to call clearTileCache().

Removing Tile Overlays

You can remove a TileOverlay using the GoogleMap's removeTileOverlay function, like so:

function removeTileOverlay(map: GoogleMap, tileOverlay: TileOverlay) {
    map.removeTileOverlay(tileOverlay);
}

Tile Providers

Tile providers are objects that provide tiles to be used in a Tile Overlay.

For example a UrlTileProvider can be created like so:

const tileProvider = new UrlTileProvider((x, y, z) => {
    return `https://tiles.example.com/${z}/${x}/${y}.png`;
});

License

Apache License Version 2.0