@nativescript/google-maps

一个允许你使用地图 SDK 访问 Google 地图功能的插件。

内容

先决条件
安装
在核心项目中使用 @nativescript/google-maps
API

先决条件

要使用 Google 地图 API，请在 Google API 控制台中注册您的应用并获取 API 密钥。
将 Google 地图 API 密钥添加到您的应用。

Android

要添加 Android 的 API 密钥，请修改 AndroidManifest.xml 文件并添加 <meta-data> 标签，其名称为 com.google.android.geo.API_KEY，其值为密钥。

xml

<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

要添加 iOS 的 API 密钥，请将 TNSGoogleMapsAPIKey 密钥和 API 密钥作为值添加到位于 App_Resources/iOS 的 Info.plist 文件中。

xml

<?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>

安装

cli

npm install @nativescript/google-maps

要在不同的 NativeScript 版本中使用该插件，请修改 main.ts 以导入并注册它。

在核心项目中使用 @nativescript/google-maps

使用页面 xmlns 属性注册插件命名空间，提供您的前缀（例如，map）。

xml

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

使用 map 前缀访问 <MapView>。

xml

<map:MapView ...

以下是前两个步骤中的完整代码

xml

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

要管理地图功能，请监听地图视图的 ready 事件，并从事件数据中获取对 GoogleMap 实例的引用。

xml

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

要在不同的 NativeScript 版本中使用该插件，请修改 main.ts 以注册它。

在 Angular 项目中使用 @nativescript/google-maps

通过将 GoogleMapsModule 添加到 app.module.ts 的 AppModule 的 imports 数组中来注册插件，如下所示

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

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

将 MapView 添加到您的标记中。

html

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

管理

html

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

要管理地图功能，请监听地图视图的 ready 事件，并从事件数据中获取对 GoogleMap 实例的引用。

在 Vue 项目中使用 @nativescript/google-maps

在 app.ts 文件中，通过将插件的引用传递给应用实例的 use() 方法来注册该插件。

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)

注意

要处理地图功能，请参阅 GoogleMap 对象 API。

将 MapView 组件添加到标记中。

html

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

注意

要处理地图功能，请参阅 GoogleMap 对象 API。

要管理地图功能，请监听地图视图的 ready 事件，并从事件数据中获取对 GoogleMap 实例的引用。

控制相机

要以编程方式更新相机位置，请在 GoogleMap 对象上调用 animateCamera() 方法，并将一个 CameraUpdate 实例传递给它。

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

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

设置地图类型

要设置地图类型，请将 mapType 属性设置为 MapType 选项之一。

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

map: GoogleMap
map.mapType = MapType.Hybrid

参阅 CameraUpdate 以获取更多可以调用并传递给 animateCamera() 方法的方法。

地图样式

您可以设置地图项目的样式，例如道路、公园、企业和其他兴趣点。

样式仅适用于 normal 地图类型。样式不会影响室内地图。

要设置您的地图样式，请使用由 Google 地图 API 样式向导生成的 JSON 文件。除了更改要素的外观之外，您还可以完全隐藏要素。

json

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

要将自定义样式应用于地图，您可以在 GoogleMap 对象上设置 mapStyle 属性

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

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

API

MapView 类

属性

以下属性可用于在初始化时调整相机视图

属性	类型	描述
`lat`	`数字`	纬度（以度为单位）
`lng`	`数字`	经度（以度为单位）
`zoom`	`数字`	缩放级别（此处有说明）
`bearing`	`数字`	方位角（以度为单位）
`tilt`	`数字`	倾斜角（以度为单位）

事件

MapView 提供以下事件

事件	描述
`ready`	当 MapView 准备好使用时触发，并提供一个 GoogleMap 实例，用于管理地图功能。
`mapTap`	当在 map 上点击坐标时触发
`mapLongPress`	当在 map 上长按坐标时触发
`markerTap`	当点击标记时触发
`myLocationTap`	当点击“我的位置”时触发
`myLocationButtonTap`	当点击“我的位置”按钮时触发
`markerDragStart`	当标记开始拖动时触发
`markerDragging`	当标记正在被拖动时触发
`markerDragEnd`	当标记结束拖动时触发
`tileRenderingStart`	当瓦片渲染开始时触发
`tileRenderingEnd`	当瓦片渲染结束时触发
`cameraPosition`	当地图视窗状态发生变化时触发，相机状态包括 `idle` \| `start` \| `moving`
`circle`	当点击圆形时触发
`polygon`	当点击多边形时触发
`polyline`	当点击折线时触发
`poi`	当点击 POI 时触发
`groundOverlay`	当点击地面覆盖层时触发
`infoWindowTap`	当点击标记的信息窗口时触发
`infoWindowLongPress`	当长按标记的信息窗口时触发
`infoWindowClose`	当关闭标记的信息窗口时触发
`markerInfoContents`	如果此方法返回一个视图，它将被放置在默认的信息窗口框架内。
`markerInfoWindow`	当标记即将被选中时调用，如果此方法返回一个视图，则提供一个可选的自定义信息窗口，用于该标记。
`activeBuilding`	当建筑物被聚焦时触发
`activeLevel`	当聚焦的建筑物的楼层发生变化时触发

GoogleMap 对象

此类提供地图功能，其实例可从 MapView 实例的 ready 事件中获得。

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

属性

属性	类型	描述
`buildingsEnabled`	`布尔值`	启用建筑物
`maxZoomLevel`	`数字`	最大缩放级别
`minZoomLevel`	`数字`	最小缩放级别
`myLocationEnabled`	`布尔值`	启用“我的位置”
`trafficEnabled`	`布尔值`	启用交通
`cameraPosition`	`CameraPosition`	参阅相机位置
`projection`	`投影`	参阅投影
`uiSettings`	`IUISettings`	参阅 UISettings 接口
`mapStyle`	Style[]	参阅地图样式
`mapType`	MapType	参阅 MapType
`native`	任何	只读：`GoogleMap` 类的平台特定实例。Android 为 `com.google.android.gms.maps.GoogleMap`，iOS 为 `GMSMapView`。

方法

方法	返回	描述
addMarker(marker: MarkerOptions)	Marker	向地图添加标记
removeMarker(marker: Marker)	`void`	从地图中移除标记
addTileOverlay(options: TileOverlayOptions)	TileOverlay	向地图添加瓦片覆盖层
removeTileOverlay(overlay: TileOverlay)	`void`	从地图中移除一个瓦片覆盖层
addCircle(circle: CircleOptions)	圆形	在地图上添加一个圆形
removeCircle(circle: Circle)	`void`	从地图中移除一个圆形
addGroundOverlay(options: GroundOverlayOptions)	地面覆盖层	在地图上添加一个地面覆盖层
removeGroundOverlay(groundOverlay: GroundOverlay)	从地图中移除一个地面覆盖层
addPolygon(options: PolygonOptions)	多边形	在地图上添加一个多边形
removePolygon(polygon: Polygon)	从地图中移除一个多边形
addPolyline(options: PolylineOptions)	折线	在地图上添加一条折线
removePolyline(polyline: Polyline)	`void`	从地图中移除一条折线
animateCamera(update: CameraUpdate)	`void`	将相机动画到一个新的位置
`snapshot()`	`Promise<ImageSource>`	返回地图当前视窗的平台特定图像
`clear()`	`void`	清除添加到地图的所有对象

原生地图对象

GoogleMap 允许您访问平台的原生地图对象 native | android | ios

有关如何使用它的详细信息，请参阅相应的 SDK 参考：iOS | Android

相机位置

地图的当前相机位置可以从 GoogleMap 对象的 cameraPosition 属性中读取。

属性	类型	描述
`目标`	坐标	相机目标是地图中心的地理位置，以 `lat` 和 `lng` 形式指定。
`bearing`	`数字`	相机指向的方向，以从北开始顺时针方向的度数衡量。
`tilt`	`数字`	相机的视角，以度数衡量。
`zoom`	`数字`	地图的比例。

CameraUpdate 类

CameraUpdate 提供多种方法来创建目标 CameraPosition。

方法	描述
`fromCoordinate(coordinate: Coordinate, zoom: number)`	从单个坐标返回一个 `CameraUpdate`。
`fromCoordinates(coordinates: Coordinate[], padding: number)`	从多个坐标返回一个 `CameraUpdate`。
`fromCoordinates(coordinates: Coordinate[], width: number, height: number, padding: number)`	从多个坐标返回一个 `CameraUpdate`，并指定高度、宽度和填充。
`fromCameraPosition(position: CameraPosition)`	从 CameraPosition 返回一个 `CameraUpdate`。
`zoomIn()`	返回一个已放大过的 `CameraUpdate`。
`zoomOut()`	返回一个已缩小过的 `CameraUpdate`。
`zoomTo(value: number)`	返回一个已缩放至指定值的 `CameraUpdate`。
`zoomBy(amount: number, point?: { x: number; y: number })`	返回一个已缩放并平移的 `CameraUpdate`。
`scrollBy(x: number, y: number)`	返回一个已平移的 `CameraUpdate`。

投影

投影用于在屏幕位置和地球表面的地理坐标之间进行转换。

方法	描述
`fromScreenLocation(point: { x: number; y: number })`	返回对应于屏幕位置的地理位置。
`getVisibleRegion()`	获取用于在屏幕坐标和地理经纬度坐标之间转换的视窗的投影。
`toScreenLocation(coordinate: Coordinate)`	返回对应于地理坐标的屏幕位置。
`containsCoordinate(coordinate: Coordinate)`	如果坐标在当前视窗中可见，则返回 true。

UISettings 接口

您可以通过配置 uiSettings 属性的以下属性来调整地图的 UI 设置。

属性	类型	描述
`compassEnabled`	`布尔值`	指南针是否启用。
`indoorLevelPickerEnabled`	`布尔值`	室内楼层选择器是否启用。
`mapToolbarEnabled`	`布尔值`	地图工具栏是否启用。
`myLocationButtonEnabled`	`布尔值`	“我的位置”按钮是否启用。
`rotateGesturesEnabled`	`布尔值`	指南针是否启用。
`scrollGesturesEnabled`	`布尔值`	地图滚动手势是否启用。
`tiltGesturesEnabled`	`布尔值`	地图倾斜手势是否启用。
`zoomGesturesEnabled`	`布尔值`	地图缩放手势是否启用。
`zoomControlsEnabled`	`布尔值`	地图缩放控件是否启用。
`scrollGesturesEnabledDuringRotateOrZoom`	`布尔值`	在旋转或缩放期间滚动手势是否启用。

MapType 枚举

Google Maps API 提供以下五种类型的地图。

类型	描述
`None`	没有瓦片。地图被渲染为一个空网格，没有加载瓦片。
`Normal`	典型的路线地图。显示道路、一些由人类建造的特征以及河流等重要自然特征。道路和特征标签也可见。
`Satellite`	卫星照片数据。道路和特征标签不可见。
`Terrain`	地形数据。地图包含颜色、等高线和标签以及透视阴影。一些道路和标签也可见。
`Hybrid`	带有路线地图的卫星照片数据。道路和特征标签也可见。

标记

添加标记

您可以使用 GoogleMap 对象的 addMarker 方法通过传递一个 MarkerOptions 对象来创建标记。

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

addMarker 返回一个 Marker

Marker 对象

它实现了 [MarkerOptions] 接口，并具有以下其他方法。

方法	返回
`hideInfoWindow()`	`void`
`showInfoWindow()`	`void`

MarkerOptions

属性	类型	描述
`位置`	坐标	标记的位置，以 `lat` 和 `lng` 形式指定。
`颜色`	`string` \| `Color`	标记的颜色，阴影不可用。
`透明度`	`数字`	标记的透明度。
`标题`	`string`	当用户点击标记时，信息窗口中显示的字符串。
`摘要`	`string`	显示在标题下方额外的文本。
`图标`	`ImageSource \| UIImage \| Bitmap`	显示在默认标记图像位置的图像。
`可拖动`	`布尔值`	如果要允许用户移动标记，请将其设置为 `true`。默认值为 `false`。
`平面`	`布尔值`	默认情况下，标记针对屏幕定向，并且不会随相机旋转或倾斜。平面标记针对地球表面定向，并且会随相机旋转和倾斜。
`旋转`	`布尔值`	标记的方向，以顺时针方向的度数指定。
`anchorU`	`数字`	水平图标相对于标记位置的偏移量。
`anchorV`	`数字`	垂直图标相对于标记位置的偏移量。
`userData`	`任何`	分配给标记的附加信息。
`zIndex`	`数字`	标记的 z 索引。

坐标

属性	类型
`lat`	`数字`
`lng`	`数字`

移除标记

要从地图中移除标记，请在 GoogleMap 实例上调用 removeMarker() 方法，并将要移除的标记传递给它。

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

圆形

添加圆形

要在地图上添加圆形，请调用 addCircle() 方法并使用 CircleOptions 对象指定其属性。

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

CircleOptions

属性	类型
`中心`	坐标
`填充色`	`Color` \| `string`
`半径`	`数字`
`描边色`	`Color` \| `string`
`描边图案`	PatternItem & Partial<NativeObject>[]
`描边宽度`	`数字`
`可点击`	`布尔值`
`可见`	`布尔值`
`zIndex`	`数字`
`userData`	`{ [key: string]: any }`

移除圆形

您可以使用 GoogleMap 的 removeCircle() 方法移除圆形。

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

多边形

添加多边形

您可以使用 GoogleMap 对象的 addPolygon() 方法通过传入指定的 PolygonOptions 来创建多边形。

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

PolygonOptions

属性	类型
`点`	坐标[]
`孔`	坐标[]
`可点击`	`布尔值`
`描边宽度`	`数字`
`描边色`	Color \| string
`填充色`	Color \| string
`描边图案`	PatternItem & Partial<NativeObject>[]
`zIndex`	`数字`
`大地线`	`布尔值`
`strokeJointType`	JointType
`可见`	`布尔值`
`userData`	`{ [key: string]: any }`

移除多边形

您可以使用 GoogleMap 的 removePolygon 函数移除多边形，如下所示。

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

折线

添加折线

您可以使用 GoogleMap 对象的 addPolyline 函数通过传递一个 PolylineOptions 对象来创建折线。

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

PolylineOptions

属性	类型
`宽度`	`数字`
`点`	坐标[]
`可点击`	`布尔值`
`大地线`	`布尔值`
`可见`	`布尔值`
`zIndex`	`数字`
`jointType`	JointType
`图案`	PatternItem & Partial<NativeObject>[]
`颜色`	Color \| string
`startCap`	Cap & Partial<NativeObject>
`endCap`	Cap & Partial<NativeObject>
`userData`	`{ [key: string]: any }`

移除折线

您可以使用 GoogleMap 的 removePolyline 函数移除折线，如下所示。

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

地面覆盖层

添加地面覆盖层

您可以使用 GoogleMap 对象的 addGroundOverlay 函数通过传入指定的 GroundOverlay Options 来创建地面覆盖层。

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

GroundOverlayOptions

属性	类型
`zIndex`	`数字`
`可见`	`布尔值`
`透明度`	`数字`
`位置`	坐标
`边界`	CoordinateBounds
`可点击`	`布尔值`
`bearing`	`数字`
`图像`	ImageSource
`userData`	任何
`宽度`	`数字`
`高度`	`数字`
`anchorU`	`数字`
`anchorV`	`数字`

移除地面覆盖层

您可以使用 GoogleMap 的 removeGroundOverlay 函数移除地面覆盖层，如下所示。

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

瓦片覆盖层

添加瓦片覆盖层

您可以使用 GoogleMap 对象的 addTileOverlay 函数通过传入指定的瓦片覆盖层选项来创建瓦片覆盖层。

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

瓦片覆盖层选项

属性	类型
`fadeIn`	`布尔值`
`透明度`	`数字`
`可见`	`布尔值`
`tileProvider`	瓦片提供者 & Partial<NativeObject>
`zIndex`	`数字`
`clearTileCache()`	`void`

在瓦片覆盖层添加到地图后设置瓦片覆盖层选项可能对瓦片覆盖层没有影响。要更新瓦片覆盖层，您可能需要调用 clearTileCache()。

移除瓦片覆盖层

您可以使用 GoogleMap 对象的 removeTileOverlay 函数来移除瓦片覆盖层，如下所示

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

瓦片提供者

瓦片提供者是提供用于瓦片覆盖层的瓦片的对象。

提供者	描述
`TileProvider`	瓦片提供者的基类
`UrlTileProvider`	从 URL 返回瓦片的瓦片提供者

例如，可以像这样创建一个 UrlTileProvider

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

许可证

Apache 许可证 2.0 版

@nativescript/google-maps ​

内容 ​

先决条件 ​

安装 ​

在核心项目中使用 @nativescript/google-maps ​

在 Angular 项目中使用 @nativescript/google-maps ​

在 Vue 项目中使用 @nativescript/google-maps ​

Vue ​

控制相机 ​

设置地图类型 ​

地图样式 ​

API ​

MapView 类 ​

属性 ​

事件 ​

GoogleMap 对象 ​

属性 ​

方法 ​

原生地图对象 ​

相机位置 ​

CameraUpdate 类 ​

投影 ​

UISettings 接口 ​

MapType 枚举 ​

标记 ​

添加标记 ​

Marker 对象 ​

MarkerOptions ​

坐标 ​

移除标记 ​

圆形 ​

添加圆形 ​

CircleOptions ​

移除圆形 ​

多边形 ​

添加多边形 ​

PolygonOptions ​

移除多边形 ​

折线 ​

添加折线 ​

PolylineOptions ​

移除折线 ​

地面覆盖层 ​

添加地面覆盖层 ​

GroundOverlayOptions ​

移除地面覆盖层 ​

瓦片覆盖层 ​

添加瓦片覆盖层 ​

瓦片覆盖层选项 ​

移除瓦片覆盖层 ​

瓦片提供者 ​

许可证 ​

贡献者

@nativescript/google-maps

内容

先决条件

安装

在核心项目中使用 @nativescript/google-maps

在 Angular 项目中使用 @nativescript/google-maps

在 Vue 项目中使用 @nativescript/google-maps

Vue

控制相机

设置地图类型

地图样式

API

MapView 类

属性

事件

GoogleMap 对象

属性

方法

原生地图对象

相机位置

CameraUpdate 类

投影

UISettings 接口

MapType 枚举

标记

添加标记

Marker 对象

MarkerOptions

坐标

移除标记

圆形

添加圆形

CircleOptions

移除圆形

多边形

添加多边形

PolygonOptions

移除多边形

折线

添加折线

PolylineOptions

移除折线

地面覆盖层

添加地面覆盖层

GroundOverlayOptions

移除地面覆盖层

瓦片覆盖层

添加瓦片覆盖层

瓦片覆盖层选项

移除瓦片覆盖层

瓦片提供者

许可证