Skip to content

Latest commit

 

History

History
721 lines (582 loc) · 25.6 KB

README.md

File metadata and controls

721 lines (582 loc) · 25.6 KB
Raw

@nativescript/google-maps

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

Contents

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">
  1. 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>
  1. 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]
})
  1. Add MapView to your markup.
<MapView
	(mapTap)="onTap($event)"
	(mapLongPress)="onLongPress($event)"
	(markerTap)="onMarkerTap($event)"
>
</MapView>
  1. Manage
<MapView
	(ready)="onReady($event)" 
	(mapTap)="onTap($event)"
	(mapLongPress)="onLongPress($event)"
	(markerTap)="onMarkerTap($event)"
>
</MapView>
  1. 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.

  1. 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.

  1. 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.

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
	)
);

Set 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;

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

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" }
	]
}];

API

MapView Class

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

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

GoogleMap Object

This class provides the mapping features and its instance is available from the MapView instance's ready event:

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<ImageSource> Returns a platform-specific image of the map's current viewport
clear() void Clears all objects added to the map

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

Camera Position

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

CameraUpdate Class

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

Projection

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.

UISettings Interface

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

MapType enum

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.

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.

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

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

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

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

Property Type
points Coordinate[]
holes Coordinate[]
tappable boolean
strokeWidth number
strokeColor Color | string
fillColor Color | string
strokePattern PatternItem & Partial<NativeObject>[]
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:

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

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

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

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

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

Property Type
fadeIn boolean
transparency number
visible boolean
tileProvider TileProvider & Partial<NativeObject>
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().

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.

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:

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

License

Apache License Version 2.0