Skip to content

Latest commit

 

History

History
252 lines (223 loc) · 45 KB

mapview.md

File metadata and controls

252 lines (223 loc) · 45 KB
Raw

<MapView /> Component API

Props

Prop Type Default Note
provider string The map framework to use.

Either "google" for GoogleMaps, otherwise null or undefined to use the native map framework (MapKit in iOS and GoogleMaps in android).
region Region The region to be displayed by the map.

The region is defined by the center coordinates and the span of coordinates to display.
initialRegion Region The initial region to be displayed by the map. Use this prop instead of region only if you don't want to control the viewport of the map besides the initial region.

Changing this prop after the component has mounted will not result in a region change.

This is similar to the initialValue prop of a text input.
camera Camera The camera view the map should display. If you use this, the region property is ignored.
initialCamera Camera Like initialRegion, use this prop instead of camera only if you don't want to control the viewport of the map besides the initial camera setting.

Changing this prop after the component has mounted will not result in a region change.

This is similar to the initialValue prop of a text input.
mapPadding EdgePadding Adds custom padding to each side of the map. Useful when map elements/markers are obscured.
paddingAdjustmentBehavior 'always' | 'automatic' | 'never' 'never' Indicates how/when to affect padding with safe area insets (GoogleMaps in iOS only)
liteMode Boolean false Enable lite mode. Note: Android only.
mapType String "standard" The map type to be displayed.

- standard: standard road map (default)
- none: no map Note Not available on MapKit
- satellite: satellite view
- hybrid: satellite view with roads and points of interest overlayed
- terrain: topographic view
- mutedStandard: more subtle, makes markers/lines pop more (iOS 11.0+ only)
- satelliteFlyover: 3D globe with sattelite view (iOS 13.0+ Apple Maps only)
- hybridFlyover: 3D globe with hybrid view (iOS 13.0+ Apple Maps only)
customMapStyle Array Adds custom styling to the map component. See README for more information.
userInterfaceStyle 'light' | 'dark' Sets the map to the style selected. Default is whatever the system settings is. Note: iOS Maps only (aka MapKit).
showsUserLocation Boolean false If true the users location will be shown on the map. NOTE: You need runtime location permissions prior to setting this to true, otherwise it is going to fail silently! Checkout the excellent react-native-permissions for this.
userLocationPriority 'balanced'|'high'|'low'|'passive' 'high' Set power priority of user location tracking. See Google APIs documentation. Note: Android only.
userLocationUpdateInterval Number 5000 Interval of user location updates in milliseconds. See Google APIs documentation. Note: Android only.
userLocationFastestInterval Number 5000 Fastest interval the application will actively acquire locations. See Google APIs documentation. Note: Android only.
userLocationAnnotationTitle String The title of the annotation for current user location. This only works if showsUserLocation is true. There is a default value My Location set by MapView. Note: iOS only.
followsUserLocation Boolean false If true the map will focus on the user's location. This only works if showsUserLocation is true and the user has shared their location. Note: Apple Maps only.
userLocationCalloutEnabled Boolean false If true clicking user location will show the default callout for userLocation annotation. Note: Apple Maps only.
showsMyLocationButton Boolean true If false hide the button to move map to the current user's location.
showsPointsOfInterest Boolean true If false points of interest won't be displayed on the map. Note: Apple Maps only.
showsCompass Boolean true If false compass won't be displayed on the map.
showsScale Boolean true A Boolean indicating whether the map shows scale information. Note: Apple Maps only.
showsBuildings Boolean true A Boolean indicating whether the map displays extruded building information.
showsTraffic Boolean false A Boolean value indicating whether the map displays traffic information.
showsIndoors Boolean true A Boolean indicating whether indoor maps should be enabled.
showsIndoorLevelPicker Boolean false A Boolean indicating whether indoor level picker should be enabled. Note: Google Maps only (either Android or iOS with PROVIDER_GOOGLE).
zoomEnabled Boolean true If false the user won't be able to pinch/zoom the map.
zoomTapEnabled Boolean true If false the user won't be able to double tap to zoom the map. Note: But it will greatly decrease delay of tap gesture recognition. Note: Google Maps on iOS only
zoomControlEnabled Boolean true If false the zoom control at the bottom right of the map won't be visible Note: Android only.
minZoomLevel Number 0 Minimum zoom value for the map, must be between 0 and 20. Note: Deprecated on Apple Maps. Use cameraZoomRange instead.
maxZoomLevel Number 20 Maximum zoom value for the map, must be between 0 and 20. Note: Deprecated on Apple Maps. Use cameraZoomRange instead.
rotateEnabled Boolean true If false the user won't be able to pinch/rotate the map.
scrollEnabled Boolean true If false the user won't be able to change the map region being displayed.
scrollDuringRotateOrZoomEnabled Boolean true If false the map will stay centered while rotating or zooming. Note: Google Maps only
pitchEnabled Boolean true If false the user won't be able to adjust the camera’s pitch angle.
toolbarEnabled Boolean true Android only If false will hide 'Navigate' and 'Open in Maps' buttons on marker press. If you enable the toolbar, make sure to edit your AndroidManifest.xml
cacheEnabled Boolean false If true map will be cached and displayed as an image instead of being interactable, for performance usage. Note: Apple Maps only
loadingEnabled Boolean false If true a loading indicator will show while the map is loading.
loadingIndicatorColor Color #606060 Sets loading indicator color, default to #606060.
loadingBackgroundColor Color #FFFFFF Sets loading background color, default to #FFFFFF.
tintColor  color null Sets the tint color of the map. (Changes the color of the position indicator) Defaults to system blue. Note: iOS (Apple maps) only.
moveOnMarkerPress Boolean true Android only If false the map won't move when a marker is pressed.
legalLabelInsets EdgeInsets If set, changes the position of the "Legal" label link from the OS default. Note: iOS only.
kmlSrc string The URL from KML file. Note: Google Maps and Markers only (either Android or iOS with PROVIDER_GOOGLE).
compassOffset Point If set, changes the position of the compass. Note: iOS Maps only.
isAccessibilityElement Boolean false Determines whether the MapView captures VoiceOver touches or forwards them to children. When true, map markers are not visible to VoiceOver. Note: iOS Maps only.
cameraZoomRange CameraZoomRange Map camera distance limits. minCenterCoordinateDistance for minimum distance, maxCenterCoordinateDistance for maximum, animated for animated zoom range changes. Takes precedence if conflicting with minZoomLevel, maxZoomLevel. Note: iOS 13.0+ only.

Events

To access event data, you will need to use e.nativeEvent. For example, onPress={e => console.log(e.nativeEvent)} will log the entire event object to your console.

Event Name Returns Notes
onMapReady Callback that is called once the map is fully loaded.
onKmlReady KmlContainer Callback that is called once the kml is fully loaded.
onRegionChange (Region, {isGesture: boolean}) Callback that is called continuously when the region changes, such as when a user is dragging the map. The second parameter is an object containing more details about the move. isGesture property indicates if the move was from the user (true) or an animation (false). Note: isGesture is supported by Google Maps only.
onRegionChangeComplete (Region, {isGesture: boolean}) Callback that is called once when the region changes, such as when the user is done moving the map. The second parameter is an object containing more details about the move. isGesture property indicates if the move was from the user (true) or an animation (false). Note: isGesture is supported by Google Maps only.
onUserLocationChange { coordinate: Location } Callback that is called when the underlying map figures our users current location (coordinate also includes isFromMockProvider value for Android API 18 and above). Make sure showsUserLocation is set to true.
onPress { coordinate: LatLng, position: Point } Callback that is called when user taps on the map.
onDoublePress { coordinate: LatLng, position: Point } Callback that is called when user double taps on the map. NOTE: Not supported on Google Maps iOS
onPanDrag { coordinate: LatLng, position: Point, numberOfTouches: number, } Callback that is called when user presses and drags the map. NOTE numberOfTouches is iOS only
onPoiClick { coordinate: LatLng, position: Point, placeId: string, name: string } Callback that is called when user click on a POI.
onLongPress { coordinate: LatLng, position: Point } Callback that is called when user makes a "long press" somewhere on the map.
onMarkerPress Callback that is called when a marker on the map is tapped by the user.
onMarkerSelect Callback that is called when a marker on the map becomes selected. This will be called when the callout for that marker is about to be shown.
onMarkerDeselect Callback that is called when a marker on the map becomes deselected. This will be called when the callout for that marker is about to be hidden.
onCalloutPress Callback that is called when a callout is tapped by the user.
onMarkerDragStart { coordinate: LatLng, position: Point } Callback that is called when the user initiates a drag on a marker (if it is draggable)
onMarkerDrag { coordinate: LatLng, position: Point } Callback called continuously as a marker is dragged
onMarkerDragEnd { coordinate: LatLng, position: Point } Callback that is called when a drag on a marker finishes. This is usually the point you will want to setState on the marker's coordinate again
onIndoorLevelActivated IndoorLevel Callback that is called when a level on indoor building is activated
onIndoorBuildingFocused IndoorBuilding Callback that is called when a indoor building is focused/unfocused

Methods

Method Name Arguments Notes
getCamera Returns a Promise<Camera> structure indicating the current camera configuration.
animateCamera camera: Camera, { duration: Number } Animate the camera to a new view. You can pass a partial camera object here; any property not given will remain unmodified.
setCamera camera: Camera, { duration: Number } Like animateCamera, but sets the new view instantly, without an animation.
animateToRegion region: Region, duration: Number
getMapBoundaries Promise<{northEast: LatLng, southWest: LatLng}>
setMapBoundaries northEast: LatLng, southWest: LatLng The boundary is defined by the map's center coordinates, not the device's viewport itself. Note: Google Maps only.
setIndoorActiveLevelIndex levelIndex: Number
fitToElements options: { edgePadding: EdgePadding, animated: Boolean } Note edgePadding is Google Maps only
fitToSuppliedMarkers markerIDs: String[], options: { edgePadding: EdgePadding, animated: Boolean } If you need to use this in ComponentDidMount, make sure you put it in a timeout or it will cause performance problems. Note edgePadding is Google Maps only
fitToCoordinates coordinates: Array<LatLng>, options: { edgePadding: EdgePadding, animated: Boolean } If called in ComponentDidMount in android, it will cause an exception. It is recommended to call it from the MapView onLayout event.
addressForCoordinate coordinate: LatLng Converts a map coordinate to a address (Address). Returns a Promise<Address> Note Not supported on Google Maps for iOS.
pointForCoordinate coordinate: LatLng Converts a map coordinate to a view coordinate (Point). Returns a Promise<Point>.
coordinateForPoint point: Point Converts a view coordinate (Point) to a map coordinate. Returns a Promise<Coordinate>.
getMarkersFrames onlyVisible: Boolean Get markers' centers and frames in view coordinates. Returns a Promise<{ "markerID" : { point: Point, frame: Frame } }>. Note: iOS only.

Types

type Region {
  latitude: Number,
  longitude: Number,
  latitudeDelta: Number,
  longitudeDelta: Number,
}

type Camera = {
    center: {
       latitude: number,
       longitude: number,
   },
   pitch: number,
   heading: number,

   // Only on iOS MapKit, in meters. The property is ignored by Google Maps.
   altitude: number,

   // Only when using Google Maps.
   zoom: number
}

Latitude and longitude are self explanatory while latitudeDelta and longitudeDelta may not. On the developer.apple.com website this is how the "latitudeDelta" property is explained:

The amount of north-to-south distance (measured in degrees) to display on the map. Unlike longitudinal distances, which vary based on the latitude, one degree of latitude is always approximately 111 kilometers (69 miles).

If this is not enough, you can find a visual explanation on stackoverflow.

Note that when using the Camera, MapKit on iOS and Google Maps differ in how the height is specified. For a cross-platform app, it is necessary to specify both the zoom level and the altitude separately.

type LatLng {
  latitude: Number,
  longitude: Number,
}

type Location {
  latitude: Number,
  longitude: Number,
  altitude: Number,
  timestamp: Number, //Milliseconds since Unix epoch
  accuracy: Number,
  altitudeAccuracy: Number,
  speed: Number,
}

type Point {
  x: Number,
  y: Number,
}

type Frame {
  x: Number,
  y: Number,
  width: Number,
  height: Number,
}

enum MapType : String {
  "standard",
  "satellite",
  "hybrid",
  "terrain" //Android only
}

type EdgePadding {
  top: Number,
  right: Number,
  bottom: Number,
  left: Number
}

type EdgeInsets {
  top: Number,
  left: Number,
  bottom: Number,
  right: Number
}

type Marker {
  id: String,
  coordinate: LatLng,
  title: String,
  description: String
}

type KmlContainer {
  markers: [Marker]
}

type IndoorBuilding {
  underground: boolean,
  activeLevelIndex: Number,
  levels: Array<IndoorLevel>,
}

type IndoorLevel {
  index: Number,
  name: String,
  shortName: String,
}

type Address {
  name: String,
  thoroughfare: String,
  subThoroughfare: String,
  locality: String,
  subLocality: String,
  administrativeArea: String,
  subAdministrativeArea: String,
  postalCode: String,
  countryCode: String,
  country: String,
}

type CameraZoomRange = {
  minCenterCoordinateDistance?: number;
  maxCenterCoordinateDistance?: number;
  animated?: boolean;
};