@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 tag with the com.google.android.geo.API_KEY as its name and the key as the value.

``xml
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">

android:name="com.google.android.geo.API_KEY"
android:value="yourKey"/>

`

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




TNSGoogleMapsAPIKey
yourKey


`

Installation


`cli
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).

`xml
xmlns:map="@nativescript/google-maps">
`

2. Access the \<MapView\> using the the map prefix.
`xml
`

Below is the complete code from the 2 preceding steps:

`xml
xmlns:map="@nativescript/google-maps">
lat="{{lat}}"
lng="{{lng}}"
zoom="{{zoom}}"
bearing="{{bearing}}"
tilt="{{tilt}}"
mapTap="{{onTap}}"
mapLongPress="{{onLongPress}}"
markerTap="{{onMarkerTap}}"
/>

`

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.

`xml
xmlns:map="@nativescript/google-maps">
lat="{{lat}}"
lng="{{lng}}"
zoom="{{zoom}}"
bearing="{{bearing}}"
tilt="{{tilt}}"

ready="{{onReady}}" 👈

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

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

$3

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

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

// Registering
@NgModule({
imports: [
GoogleMapsModule
],
declarations: [
AppComponent
],
bootstrap: [AppComponent]
})
`
2. Add MapView to your markup.

`html
(ready)="onReady($event)"
(mapTap)="onTap($event)"
(mapLongPress)="onLongPress($event)"
(markerTap)="onMarkerTap($event)"
>

`

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.

---


$3

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

---


$3


`ts
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.

`html
@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

$3

#### Properties

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

| Property | Type | Description
:------------- |:-----| :---------------------------------
lat | number | Latitude, in degrees
lng | number | Longitude, in degrees
zoom | number | Zoom level (described here)
bearing | number | Bearing, in degrees
tilt | number | Tilt, in degrees
preventDefaultMarkerTapBehavior | boolean | Prevents the default marker event handling (panning/info windows) done by Google Maps

#### Events

MapView provides the following events:

| Event | Description
:------------- | :---------------------------------
ready | Fires when the MapView is ready for use and provides a GoogleMap instance for managing mapping featurees.
mapTap | Fires when a coordinate is tapped on the map
mapLongPress | Fires when a coordinate is long-pressed on the map
markerTap | Fires when a marker is tapped
myLocationTap | Fires when 'My Location' is tapped
myLocationButtonTap | Fires when the 'My Location' button is tapped
markerDragStart | Fires when a marker begins dragging
markerDragging | Fires while a marker is being dragged
markerDragEnd | Fires when a marker ends dragging
tileRenderingStart | Fires when tile rendering begins
tileRenderingEnd | Fires when tile rendering ends
cameraPosition | Fires when the map viewport state changes, camera states include idle \| start \| moving
circle | Fires when a circle is tapped
polygon | Fires when a polygon is tapped
polyline | Fires when a polyline is tapped
poi | Fires when a POI is tapped
groundOverlay | Fires when a ground overlay is tapped
infoWindowTap | Fires when a marker's info window is tapped
infoWindowLongPress | Fires when a marker's info window is long-pressed
infoWindowClose | Fires when a marker's info window is closed
markerInfoContents | If this method returns a view, it will be placed within the default info window frame.
markerInfoWindow | Called when a marker is about to become selected, and provides an optional custom info window to use for that marker if this method returns a view.
activeBuilding | Fires when a building is focused on
activeLevel | Fires when the level of the focused building changes

$3

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.

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

#### Properties
| Property | Type |Description
:--------------- |:-----|:---------------------------------
buildingsEnabled | boolean | Enables Buildings
maxZoomLevel | number | Maximum level of zoom
minZoomLevel | number | Minimum level of zoom
myLocationEnabled | boolean | Enables "My Location"
trafficEnabled | boolean | Enables traffic
cameraPosition | CameraPosition | See Camera Position
projection | Projection | See Projection
uiSettings | IUISettings | See UISettings Interface
mapStyle | Style[] | See Map Styles
mapType | MapType | See MapType
native | any | _readonly_: Platform-specific instance of the GoogleMap class. com.google.android.gms.maps.GoogleMap for Android and GMSMapView for iOS.

#### Methods
| Method | Returns |Description
:--------------- |:------------- |:---------------------------------
addMarker(marker: MarkerOptions)| Marker |Adds a marker to the map
removeMarker(marker: Marker)| void | Removes a marker from the map
addTileOverlay(options: TileOverlayOptions)| TileOverlay | Adds a tile overlay to the map
removeTileOverlay(overlay: TileOverlay)| void | Removes a tile overlay from the map
addCircle(circle: CircleOptions)| Circle | Adds a circle to the map
removeCircle(circle: Circle)| void | Removes a circle from the map
addGroundOverlay(options: GroundOverlayOptions) | GroundOverlay | Adds a ground overlay to the map
removeGroundOverlay(groundOverlay: GroundOverlay) | Removes a ground overlay from the map
addPolygon(options: PolygonOptions) | Polygon | Adds a polygon to the map
removePolygon(polygon: Polygon) | Removes a polygon from the map
addPolyline(options: PolylineOptions) | Polyline | Adds a polyline to the map
removePolyline(polyline: Polyline)| void | Removes a polyline from the map
animateCamera(update: CameraUpdate)| void | Animates camera to a new position
snapshot()| Promise | Returns a platform-specific image of the map's current viewport
clear()| void | Clears all objects added to the map

$3

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.
`ts
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.




$3

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

| Property | Type | Description
:--------------- |:---- |:---------------------------------
target | Coordinate | The camera target is the location of the center of the map, specified as lat and lng.
bearing | number | The direction in which the camera points measured in degrees clockwise from north.
tilt | number | The viewing angle of the camera measured in degrees
zoom | number | The scale of the map

$3


CameraUpdate provides multiple methods to create a target CameraPosition.

| Method | Description
|:-------|:-----------
| fromCoordinate(coordinate: Coordinate, zoom: number) | Returns a CameraUpdate from a single coordinate
| fromCoordinates(coordinates: Coordinate[], padding: number) | Returns a CameraUpdate from multiple coordinates
| fromCoordinates(coordinates: Coordinate[], width: number, height: number, padding: number) | Returns a CameraUpdate from multiple coordinates with specified height, width and padding
| fromCameraPosition(position: CameraPosition) | Returns a CameraUpdate from a CameraPosition
| zoomIn() | Returns a CameraUpdate that has zoomed in
| zoomOut() | Returns a CameraUpdate that has zoomed out
| zoomTo(value: number) | Returns a CameraUpdate that has zoomed to a value
| zoomBy(amount: number, point?: { x: number; y: number }) | Returns a CameraUpdate that has zoomed and panned
| scrollBy(x: number, y: number) | Returns a panned CameraUpdate

$3

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

| Method | Description
|:-------|:-----------
| fromScreenLocation(point: { x: number; y: number }) | Returns the geographic location that corresponds to a screen location.
| getVisibleRegion() | Gets a projection of the viewing frustum for converting between screen coordinates and geo-latitude/longitude coordinates.
| toScreenLocation(coordinate: Coordinate) | Returns a screen location that corresponds to a geographical coordinate.
| containsCoordinate(coordinate: Coordinate) | Returns true if the coordinate is visible in the current viewport.

Map Customization

$3

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

| Property | Type | Description
|:-------------- |:-----|:---------------------------------
| compassEnabled | boolean | Whether the compass is enabled or not
| indoorLevelPickerEnabled | boolean | Whether the indoor level picker is enabled or not
| mapToolbarEnabled | boolean | Whether the map toolbar is enabled or not
| myLocationButtonEnabled | boolean | Whether the 'My Location' button is enabled or not
| rotateGesturesEnabled | boolean | Whether the compass is enabled or not
| scrollGesturesEnabled | boolean | Whether map scroll gestures are enabled or not
| tiltGesturesEnabled | boolean | Whether map tilt gestures are enabled or not
| zoomGesturesEnabled | boolean | Whether map zoom gestures are enabled or not
| zoomControlsEnabled | boolean | Whether map zoom controls are enabled or not
| scrollGesturesEnabledDuringRotateOrZoom | boolean | Whether scroll gestures are enabled while rotating or zooming

$3

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

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

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

$3

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

| Type | Description
:------|:-----------
| None | No tiles. The map is rendered as an empty grid with no tiles loaded.
| Normal | Typical road map. Shows roads, some features built by humans, and important natural features such as rivers. Road and feature labels are also visible.
| Satellite | Satellite photograph data. Road and feature labels are not visible.
| Terrain | Topographic data. The map includes colors, contour lines and labels, and perspective shading. Some roads and labels are also visible.
| Hybrid | Satellite photograph data with road maps added. Road and feature labels are also visible.

$3

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.
`json
[
{
"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:
`ts
import { GoogleMap } from '@nativescript/google-maps';

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

Markers

$3

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

`ts
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.

| Method | Returns
|:-------|:-------
| hideInfoWindow()| void
| showInfoWindow()| void

#### MarkerOptions

| Property | Type | Description
|:---------|:-----|:-----------
| position | Coordinate | The position of the marker, specified as lat and lng
| color | string \| Color | Color of the marker, shades are unavailable.
| opacity | number | Opacity of the marker.
| title | string | A string that's displayed in the info window when the user taps the marker
| snippet | string | Additional text that's displayed below the title
| icon | ImageSource \| UIImage \| Bitmap | A image that's displayed in place of the default marker image
| draggable | boolean | Set to true if you want to allow the user to move the marker. Defaults to false
| flat | boolean | By default, markers are oriented against the screen, and will not rotate or tilt with the camera. Flat markers are oriented against the surface of the earth, and will rotate and tilt with the camera
| rotation | boolean | The orientation of the marker, specified in degrees clockwise
| anchorU | number | Horizontal icon offset from the marker position
| anchorV | number | Vertical icon offset from the marker position
| userData | any | Additional information assigned to the marker
| zIndex | number | Z-index of the marker

#### Coordinate
| Property | Type
|:---------|:----
| lat | number
| lng | number

$3

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

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

Circles

$3

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

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

#### CircleOptions

| Property | Type
|:---------|:-----
center | Coordinate |
fillColor | Color \| string |
radius | number |
strokeColor | Color \| string |
strokePattern | PatternItem & Partial\[] |
strokeWidth | number |
tappable | boolean |
visible | boolean |
zIndex | number |
userData | { [key: string]: any } |

$3

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

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


Polygons

$3

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

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

| Property | Type
|:---------|:-----
| points | Coordinate[] |
| holes | Coordinate[] |
| tappable | boolean |
| strokeWidth | number |
| strokeColor | Color \| string |
| fillColor | Color \| string |
| strokePattern | PatternItem & Partial\[] |
| zIndex | number |
| geodesic | boolean |
| strokeJointType | JointType |
| visible | boolean |
| userData | { [key: string]: any } |

Removing Polygons

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

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

Polylines

$3

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

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

| Property | Type
|:---------|:-----
| width | number |
| points | Coordinate[] |
| tappable | boolean |
| geodesic | boolean |
| visible | boolean |
| zIndex | number |
| jointType | JointType |
| pattern | PatternItem & Partial\[] |
| color | Color \| string |
| startCap | Cap & Partial\ |
| endCap | Cap & Partial\ |
| userData | { [key: string]: any } |

$3

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

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

Ground Overlays

$3

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

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

| Property | Type
|:---------|:-----
zIndex | number |
visible | boolean |
transparency | number |
position | Coordinate |
bounds | CoordinateBounds |
tappable | boolean |
bearing | number |
image | ImageSource |
userData | any |
width | number |
height | number |
anchorU | number |
anchorV | number |

$3

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

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




Tile Overlays

$3

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

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

| Property | Type
|:---------|:-----
| fadeIn | boolean |
| transparency | number |
| visible | boolean |
| tileProvider | TileProvider & Partial\ |
| zIndex | number |
| clearTileCache() | void |

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().

$3

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

`ts
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.

| Provider | Description |
|:---------|:------------|
| TileProvider | Base class for tile providers |
| UrlTileProvider | Tile provider that returns a tile from a URL |


For example a UrlTileProvider can be created like so:

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

---

License

Apache License Version 2.0