一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps Android API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps Android API
  3. 创建相应密钥
继续

形状

Google Maps API for Android 提供了一些简单的方法,让您可以方便地向地图添加形状,以针对您的应用对地图进行定制。

  • Polyline 是一系列相连的线段,可组成您想要的任何形状,并可用于在地图上标记路径和路线

  • Polygon 是一种封闭形状,可用于在地图上标记区域

  • Circle 是投影在绘制于地图上的地球表面上地理位置准确的圆圈

对于所有上述形状,您都可以通过改变若干属性来定制其外观。

代码示例

GitHub 上的 ApiDemos 存储区包含相关示例,展示如何使用形状及其特征:

多段线

Polyline 类在地图上定义一组相连的线段。 Polyline 对象包含一组 LatLng 位置,它创建的一系列线段以有序方式将这些位置连接起来。

以下这段视频就如何利用多段线在地图上绘制路径来帮助您的用户到达目的地提供了一些思路。

如需创建多段线,请先创建一个 PolylineOptions 对象并为其添加点。 点代表地球表面上的某个地点,以 LatLng 对象形式表示。 按照您向

PolylineOptions 对象添加点的顺序在各点之间绘制线段。 如需向 PolylineOptions 对象添加点,请调用 PolylineOptions.add()。 请注意, 该方法带有可变数量的参数, 因此您可以一次添加多个点(如果点已存在于列表中,您还可以调用“PolylineOptions.addAll(Iterable)”。

然后,您就可以通过调用 GoogleMap.addPolyline(PolylineOptions) 向地图添加多段线。 该方法会返回一个 Polyline 对象,您稍后可利用该对象对多段线作出改动。

下面这段代码说明了如何向地图添加矩形:

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

如需在添加多段线后改变其形状,您可以调用 Polyline.setPoints() 并为多段线提供一个新的点列表。

在向地图添加多段线之前和之后,您都可以对其外观进行定制。 如需了解更多详情,请参阅下文有关 定制外观的部分。

多段线事件

默认情况下,多段线无法点击。 您可以通过调用 Polyline.setClickable(boolean) 启用和停用可点击性。

使用 OnPolylineClickListener 侦听可点击多段线上的点击事件。 如需在地图上设置该侦听器,请调用 GoogleMap.setOnPolylineClickListener(OnPolylineClickListener)

当用户点击某个多段线时,您将收到一个 onPolylineClick(Polyline) 回调。

多边形

Polygon 对象与 Polyline 对象类似,因为它们都包含一系列有序的坐标。 不过,多边形并不是开放式的,它们设计用于定义闭环内进行了内部填充的区域。

您可以按添加 Polyline 的相同方法向地图添加 Polygon。 先创建一个 PolygonOptions 对象并为其添加一些点。 这些点将形成多边形的轮廓。 然后通过调用返回 Polygon 对象的 GoogleMap.addPolygon(PolygonOptions) 向地图添加多边形。

以下代码段的作用是向地图添加一个矩形(请注意, 由于我们尚未定义填充色,并且默认填充色是透明, 因此这段代码生成的多段线与上文代码段所生成的多段线外观完全相同):

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

如需在添加多边形后改变其形状,您可以调用 Polygon.setPoints() 并为多边形的轮廓提供一个新的点列表。

在向地图添加多边形之前和之后,您都可以对其外观进行定制。 如需了解更多详情,请参阅下文有关 定制外观的部分。

多边形自动完成

上例中的多边形包含五个坐标,但请注意第一个坐标和最后一个坐标位置相同,它们用于定义闭环。

但在实践中,由于多边形定义的是封闭区域,因此您无需定义最后一个坐标。 如果最后一个坐标不同于第一坐标,API 将通过在坐标顺序的末尾追加第一个坐标来自动“封闭”多边形。

以下两个多边形是等效的,针对其中一个多边形调用 polygon.getPoints() 将返回所有 4 个点。

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

创建一个空心多边形

可通过在单个 Polygon 对象中合并多个路径来创建复杂形状,如填充环,或“甜甜圈”(其中的多边形区域在多边形内呈“岛状”)。 复杂形状总是由多个更简单的路径组成。

两个路径必须在同一区域中定义。 两个区域中的较大者定义填充区域,它是一个没有附加选项的简单多边形。

然后,将第二个路径传递给 addHole() 方法。 当较小的第二个路径被较大路径完全封闭时, 就会产生好像多边形的一部分被去掉的效果。 如果该孔与多边形轮廓相交,多边形渲染时将不做任何填充。

以下代码段将创建单个矩形,具有较小的矩形孔。

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

多边形事件

默认情况下,多边形无法点击。 您可以通过调用 Polygon.setClickable(boolean) 启用和停用可点击性。

使用 OnPolygonClickListener 侦听可点击多边形上的点击事件。 如需在地图上设置该侦听器,请调用 GoogleMap.setOnPolygonClickListener(OnPolygonClickListener)

当用户点击某个多边形时,您将收到一个 onPolygonClick(Polygon) 回调。

除了 Polygon 泛型类外,Maps API 还提供了特定的 Circle 对象类,用以简化其构建过程。

如需建构圆,您必须指定以下两个属性:

  • center 作为 LatLng
  • radius(单位:米)。

然后便可将圆定义为地球表面上所有与给定 center 的距离为 radius 米的点的集合。 由于 Maps API 使用的墨卡托投影法在平面上呈现球形所用方式的缘故,在地图上靠近赤道的位置,呈现的将是近乎完美的圆,而随着圆的位置远离赤道,则愈发(在屏幕上)呈现为非圆形状。

以下这段代码通过构建一个 CircleOptions 对象并调用 GoogleMap.addCircle(CircleOptions),向地图添加了一个圆:

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

如需在添加圆后改变其形状,您可以调用 Circle.setRadius()Circle.setCenter() 并提供新值。

在向地图添加圆之前和之后,您都可以对其外观进行定制。 如需了解更多详情,请参阅下文有关 定制外观的部分。

圆形事件

默认情况下,圆形无法点击。 您可以通过调用具有 CircleOptions.clickable(boolean)GoogleMap.addCircle() 或通过调用 Circle.setClickable(boolean) 启用和停用可点击性。

使用 OnCircleClickListener 侦听可点击圆形上的点击事件。 如需在地图上设置该侦听器,请调用 GoogleMap.setOnCircleClickListener(OnCircleClickListener)

当用户点击某个圆形时,您将收到一个 onCircleClick(Circle) 回调,如以下代码示例所示:

public class MyActivity extends FragmentActivity
        implements OnMapReadyCallback {

        private GoogleMap mMap;
        private Circle circle;

        @Override
        public void onMapReady(GoogleMap map) {
            mMap = map;

            circle = mMap.addCircle(new CircleOptions()
                .center(new LatLng(37.4, -122.1))
                .radius(1000)
                .strokeWidth(10)
                .strokeColor(Color.GREEN)
                .fillColor(Color.argb(128, 255, 0, 0))
                .clickable(true);

            map.setOnCircleClickListener(new OnCircleClickListener() {

                @Override
                public void onCircleClick(Circle circle) {
                    // Flip the r, g and b components of the circle's
                    // stroke color.
                    int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                    circle.setStrokeColor(strokeColor);
                }
            });
        }
}

定制外观

在向地图添加形状之前和之后, 您都可以改变其外观,其中前者是通过在 options 对象上指定所需属性来实现。 此外, 还公开了所有属性的 getter 方法,以便您轻松地获取形状的当前状态。

以下这段代码的作用是,添加一条蓝色的粗多段线,其中包含从墨尔本至珀斯的测地线段。 下文将对这些属性做更详尽的说明。

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

注:尽管可将以上大多数属性应用于所述的任何一种形状, 但其中的部分属性对特定形状可能不具有任何意义(例如, 多段线不能有填充色,因为它是空心的)。

描边颜色

描边颜色是一个 32 位 Alpha-红-绿-蓝 (ARGB) 整数,用于指定形状描边的不透明度和颜色。 可通过调用 *Options.strokeColor()(如果是多段线,则是调用 PolylineOptions.color())在形状的 options 对象上设置此属性。 如果未指定,则默认描边颜色为黑色 (Color.BLACK)。

向地图添加形状后,可通过调用 getStrokeColor()(对于多段线,则是调用 getColor())获取描边颜色,并可通过调用 setStrokeColor() (setColor() for a polyline) 更改描边颜色。

填充颜色

填充颜色只适用于多边形和圆, 不适用于多段线,因为多段线未定义内部。 对于多边形, 其孔内的区域不属于多边形内部,因此在设置了填充颜色时将不会为其着色。

填充颜色是一个 32 位 Alpha-红-绿-蓝 (ARGB) 整数,用于指定形状内部的不透明度和颜色。 可通过调用 *Options.fillColor() 在形状的 options 对象上设置此属性。 如果未指定,则默认描边颜色为透明 (Color.TRANSPARENT)。

向地图添加形状后,可通过调用 getFillColor()获取填充颜色,并可通过调用 setFillColor() 更改填充颜色。

描边宽度

线条描边的宽度,以浮点 pixels (px) 表示。 该宽度不会随地图的缩放而缩放(即,形状在所有缩放比例下的描边宽度均相同)。 可通过调用 *Options.strokeWidth()(对于多段线,则是调用 PolylineOptions.width())在形状的 option 对象上设置此属性。 如果未指定,则默认描边宽度为 10 像素。

向地图添加形状后,可通过调用 getStrokeWidth()(对于多段线,则是调用 getWidth())获取描边宽度,并可通过调用 setStrokeWidth() (setWidth() for a polyline) 更改描边宽度。

测地线段

测地设置只适用于多段线和多边形。 它不适用于圆,因为按照定义圆并非线段的集合。

测地设置决定多段线/多边形连续顶点之间线段的绘制方式。 测地线段是指沿地球表面(球面)依循最短路径的线段, 在采用墨卡托投影法的地图上经常以曲线形式出现。 非测地线段在地图上绘制为直线。

可通过调用 *Options.geodesic() 在形状的 option 对象上设置此属性,true 表示应将线段绘制为测地线段,false 表示应将线段绘制为直线。 如果未指定,则默认绘制非测地线段 (false)。

向地图添加形状后,可通过调用 isGeodesic() 获取测地设置,并可通过调用 setGeodesic() 更改测地设置。

Z-顺序

Z-顺序指定该形状相对于地图上其他叠层(其他形状、底面叠层和图块叠层)的叠放顺序。

Z-顺序较高的叠层在 Z-顺序较低的叠层之上绘制。 Z-顺序相同的两个叠层按任意顺序绘制。

请注意,标记始终在其他叠层之上绘制,而不考虑其他叠层的 Z-顺序。

可通过调用 *Options.zIndex() 在形状的 options 对象上设置此属性。 如果未指定,则默认 Z-顺序为 0。 向地图添加形状后,可通过调用 getZIndex() 获取 Z-顺序,并可通过调用 setZIndex() 更改 Z-顺序。

可见性

可见性指定是否应在地图上绘制形状, true 表示应绘制形状,false 表示不应绘制形状。 您可以利用它在地图上暂时不显示某个形状。 如需从地图上永久性地删除形状, 请在该形状上调用 remove()

可通过调用 *Options.visible() 在形状的 options 对象上设置此属性。 如果未指定,则默认可见性为 true。 向地图添加形状后,可通过调用 isVisible() 获取可见性,并可通过调用 setVisible() 更改可见性。

发送以下问题的反馈:

此网页
Google Maps Android API
Google Maps Android API
需要帮助?请访问我们的支持页面