一切就绪!

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

激活 Google Maps Android API

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

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

图块叠层

图块叠层有时称作图块层,是显示在基础地图图块之上的图像集合。

代码示例

GitHub 上的 ApiDemos 存储区包含一个示例,展示了图块叠层功能:

简介

TileOverlay 定义的是在基础地图图块之上添加的图像集。

您需要为您想支持的每个缩放比例提供图块。如果您在多个缩放比例都有足够的图块,便可为整个地图补充 Google 的地图数据。

如果您想向地图添加大量图像(通常覆盖大片地域),就需要使用图块叠层。与此相反,如果您想将单个图像固定在地图上的某一区域,则需使用底面叠层

您也可以在图块叠层上以编程方式设置透明度系数或者提供透明图块图像,使用透明的图块叠层向地图添加更多特征。

图块坐标和缩放比例

Google Maps API 将各缩放比例的图像分解成一组以网格形式排列的方形地图图块。当地图移至新位置,或者切换到新的缩放比例时,Maps API 会确定需要哪些图块,并将该信息转换为需要检索的一组图块。

坐标为 (0,0) 的图块始终位于地图的西北角,x 值从西向东增加,y 值从北向南增加。利用基于该原点的 x,y 坐标为图块建立索引。

缩放比例为 0 时,整个世界使用单个图块渲染。缩放比例每增加 1,放大 2 倍。因此,缩放比例为 1 时,地图将渲染为一个 2x2 图块网格。缩放比例为 2 时,则渲染为 4x4 网格。缩放比例为 3 时,渲染为 8x8 网格,依此类推。

例如,缩放比例为 2 时,地球分成 16 个图块。每个图块都可通过唯一的 x, y 和缩放比例组合进行引用:

为图块层创建图像时,您需要为您想支持的每个缩放比例下的每个图块都创建一幅图像。Google 地图以 256dp(设备无关像素)为目标显示图块。对于高分辨率设备,建议返回高 dpi 图块(512x512 像素)。请参阅 Android 开发者文档,了解有关支持不同屏幕尺寸和密度的信息。

注:摄像头支持的缩放比例取决于各种因素,与您的图块支持的缩放比例无关。

  1. GoogleMap.getMaxZoomLevel() 返回当前摄像头位置可实现的最大缩放比例。这已将当前正在使用的地图类型考虑在内。例如,卫星地图或地形地图图块的最大缩放比例可能低于基础地图图块。
  2. GoogleMap.getMinZoomLevel() 返回最小缩放比例,每个位置的最小缩放比例均相同(不同于最大缩放比例),但不同设备和地图尺寸之间可能有所差异。

添加图块叠层

最简单也是最常见的图块叠层创建方法是,提供指向相关图块图像的网址。UrlTileProvider 是对 TileProvider 的部分实现,后者基于网址提供图像图块。该类要求所有图像都具有相同的尺寸。

您需要实现 UrlTileProvider.getTileUrl(),它接受图块坐标 (x, y, 缩放比例),并且返回的 URL 指向用于图块的图像。如果给定 x, y 和缩放比例没有对应的图块,该方法应返回空值。URL 可指向 Web 资源、Android 资源或本地磁盘上的文件。

在服务器上建立您的图块图像库,您需要为您计划支持的所有 x,y 坐标和缩放比例定义相应的图块图像。然后添加图块叠层:

  1. 定义用于提供图块图像的 UrlTileProvider
  2. 重写 getTileUrl() 以构建每个图块图像的 URL。
  3. 提供带有相关选项的 TileOverlayOptions 对象:
    • fadeIn:布尔值。指定图块是否应淡入。默认值为 true。您可能会发现,关闭淡入有助于在图块叠层间快速切换。如需了解有关透明度和淡入之间关系的详细信息,请参阅下面的透明度部分。
    • tileProvider:用于此叠层的 TileProvider
    • transparency:浮点型。设置图块图像的透明度系数。值必须在 [0.0f, 1.0f] 范围内,其中 0.0f 表示全不透明(默认),1.0f 表示全透明。请参阅下面的透明度部分,了解代码示例和透明度与淡入之间的关系。
    • visible:布尔值。指定图块叠层的可见性。不可见的图块叠层(值为 false)不会绘制在地图上,但会保持其所有其他属性。默认值为 true
    • zIndex:确定图块叠层相对于其他叠层的绘制顺序,其他叠层包括底面叠层圆、多段线以及多边形。Z-顺序较高的叠层绘制在 Z-顺序较低的叠层之上。Z-顺序相同的叠层可按任意顺序绘制。默认 Z-顺序为 0。请注意,无论其他叠层的 Z-顺序如何,标记始终在其他叠层之上绘制。
  4. 调用 GoogleMap.addTileOverlay() 以向地图添加叠层。
private GoogleMap mMap;

TileProvider tileProvider = new UrlTileProvider(256, 256) {
  @Override
  public URL getTileUrl(int x, int y, int zoom) {

    /* Define the URL pattern for the tile images */
    String s = String.format("http://my.image.server/images/%d/%d/%d.png",
        zoom, x, y);

    if (!checkTileExists(x, y, zoom)) {
      return null;
    }

    try {
      return new URL(s);
    } catch (MalformedURLException e) {
        throw new AssertionError(e);
    }
  }

  /*
   * Check that the tile server supports the requested x, y and zoom.
   * Complete this stub according to the tile range you support.
   * If you support a limited range of tiles at different zoom levels, then you
   * need to define the supported x, y range at each zoom level.
   */
  private boolean checkTileExists(int x, int y, int zoom) {
    int minZoom = 12;
    int maxZoom = 16;

    if ((zoom < minZoom || zoom > maxZoom)) {
      return false;
    }

    return true;
  }
};

TileOverlay tileOverlay = mMap.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));

如需查看 UrlTileProvider 的实际应用示例,请参阅 Google Play 服务 SDK 附带示例代码中的 TileOverlayDemoActivity

设置图块叠层的透明度

在地图上叠加透明图块很有用,这样用户就可以看到叠加的图块下面的基础地图。您可以通过提供自己的透明图块或在图块叠层上以编程方式设置透明度系数来执行这一操作。

下面的代码示例可以在 0.5f0.0f 之间切换图块叠层的透明度:

private TileOverlay mTileOverlay;

@Override
public void onMapReady(GoogleMap map) {
    mTileOverlay = map.addTileOverlay(new TileOverlayOptions()
            .tileProvider(new UrlTileProvider() {...})
            .transparency(0.5f));
}

public void updateTileOverlayTransparency() {
    if (mTileOverlay != null) {
        // Switch between 0.0f and 0.5f transparency.
        mTileOverlay.setTransparency(0.5f - mTileOverlay.getTransparency());
    }
}

透明度作为图块图像的 alpha 通道值来实现。要设置图块叠层的透明度,需要提供一个 TileOverlayOptions 对象,其中 transparency 应位于 [0.0f, 1.0f] 的范围内,如上文示例所示。值 0.0f 表示图块叠层完全不透明,1.0f 表示完全透明。默认值为 0.0f(不透明)。

您可以通过调用 TileOverlay.getTransparency() 获取图块叠层的透明度,可以通过调用 TileOverlay.setTransparency() 对其进行更改。

透明度、动画和淡入

更改透明度时没有动画。透明度选项搭配 fadeIn 选项使用。

淡入会在加载图块时提供透明度动画。如果您设置透明度值,图块将从完全透明淡入到定义的透明度值。如果您在淡入期间更改透明度,动画会随着新的目标透明度设置而继续。

删除图块叠层

您可以通过 TileOverlay.remove() 方法删除图块叠层。

tileOverlay.remove();

清除过时图块

如果图块叠层提供的图块变得“过时”,您可以调用 clearTileCache() 进行强制刷新。这会使该叠层上的所有图块重新加载。例如,如果 TileProvider 提供的图块发生变化,您必须在之后调用 clearTileCache(),以确保不再渲染旧图块。

tileOverlay.clearTileCache();

发送以下问题的反馈:

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