一切就绪!

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

激活 Google Maps Android API

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

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

街景

Google 街景提供其整个覆盖区域内以指定道路为中心的 360 度全景视图。

这段视频展示了如何利用街景服务让您的用户身临其境地体验地图上的地址,从而为他们提供有关其目的地或所关注的任何地点的有意义背景信息。

通过 Google Maps Android API v2 提供的覆盖范围与您的 Android 设备上 Google 地图应用的覆盖范围相同。

您可以在关于街景处阅读更多有关街景的内容以及查看交互地图上的支持区域。

StreetViewPanorama 类可在您的应用中为街景全景图建模。 在您的 UI 内,全景图由 StreetViewPanoramaFragment 对象或 StreetViewPanoramaView 对象表示。

代码示例

GitHub 上的 ApiDemos 存储区包含相关示例,展示如何使用街景:

StreetViewPanoramaEventsDemoActivity: 侦听事件 StreetViewPanoramaNavigationDemoActivity: 以编程方式控制街景全景图

StreetViewPanoramaOptionsDemoActivity: 更改 UI 和手势选项*

StreetViewPanoramaViewDemoActivity: 使用 StreetViewPanoramaView(而不是 Fragment)

Google Maps Android API 中的街景概览

Google Maps Android API 提供了用于对 Google街景中使用的图像进行获取和操纵的街景服务。 图像以全景图形式返回。

每张街景全景图都是一幅图像或一组图像,提供以单个位置为中心的 360 度全视图。 图像遵照等距柱状 (Plate Carrée) 投影,包含 360 度水平视图(全包围)和 180 度垂直视图(从直上至直下)。

生成的 360 度全景图定义的是一个球面投影,其图像包绕在球面的二维表面上。

StreetViewPanorama 提供了一个查看器,通过中心位置的摄像头将全景图渲染为一个球面。 您可以通过操纵 StreetViewPanoramaCamera 来控制摄像头的缩放比例和朝向(倾斜角度和方位)。

入门指南

按照入门指南建立一个 Google Maps Android API 项目。 然后按下文所述添加街景全景图。

Google Play 服务 SDK 客户端内容库提供了几个街景示例应用,您可以将它们导入项目,以其为基础开发应用。 请参阅简介,获得有关导入示例应用的指导。

使用 API

按照以下说明向 Android Fragment 添加街景全景图。 这是向您的应用添加街景的最简单方法。 然后阅读更多有关 Fragment、视图和定制全景图的内容。

添加街景全景图

步骤简述:

  1. 向将用于处理街景全景图的 Activity 添加一个 Fragment 对象。 最简单的实现方式是,向 Activity 的布局文件添加一个 <fragment> 元素。

  2. 实现 OnStreetViewPanoramaReadyCallback 接口,并使用 onStreetViewPanoramaReady(StreetViewPanorama) 回调方法获取 StreetViewPanorama 对象的句柄。

  3. 调用 Fragment 上的 getStreetViewPanoramaAsync() 以注册回调。

以下是有关各步骤的更多详情。

添加 Fragment

向 Activity 的布局文件添加 <fragment> 元素,以定义 Fragment 对象。 在该元素中,将 class 属性设置为 com.google.android.gms.maps.StreetViewPanoramaFragment(或 SupportStreetViewPanoramaFragment)。

以下是一个布局文件中的 Fragment 示例:

<fragment
    android:name="com.google.android.gms.maps.StreetViewPanoramaFragment"
    android:id="@+id/streetviewpanorama"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

添加街景代码

如需在您的应用内使用街景全景图,您需要实现 OnStreetViewPanoramaReadyCallback 接口,并在 StreetViewPanoramaFragment 对象或 StreetViewPanoramaView 对象上设置回调实例。

本教程使用的是 StreetViewPanoramaFragment,因为这是向您的应用添加街景 的最简单方法。

第一步是实现回调接口:

public class MainActivity extends FragmentActivity
    implements OnStreetViewPanoramaReadyCallback {
...
}

在您的 ActivityonCreate() 方法中,将布局文件设置为内容视图。 例如,如果布局文件的名称是 main.xml,请使用以下代码:

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

通过调用 FragmentManager.findFragmentById(), 将您的 <fragment> 元素的资源 ID 传递给它,来获取 Fragment 的句柄。 请注意,当您生成布局文件时,Android 项目中会自动添加资源 ID R.id.streetviewpanorama

然后使用 getStreetViewPanoramaAsync() 设置 Fragment 上的回调。

StreetViewPanoramaFragment streetViewPanoramaFragment =
    (StreetViewPanoramaFragment) getFragmentManager()
        .findFragmentById(R.id.streetviewpanorama);
streetViewPanoramaFragment.getStreetViewPanoramaAsync(this);

注:必须从主线程调用 getStreetViewPanoramaAsync(),回调将在主线程中执行。 如果用户设备上未安装 Google Play 服务,则用户安装 Play 服务后才会触发回调。

使用 onStreetViewPanoramaReady(StreetViewPanorama) 回调方法来检索已做好使用准备的 StreetViewPanorama 非空实例。

@Override
public void onStreetViewPanoramaReady(StreetViewPanorama panorama) {
    panorama.setPosition(new LatLng(-33.87365, 151.20689));
}

有关配置初始状态的更多信息

与使用地图时不同,无法通过 XML 来配置街景全景图的初始状态。 不过,您可以通过传入包含所指定选项的 StreetViewPanoramaOptions 对象,以编程方式配置全景图。

mSvpView = new StreetViewPanoramaView(this,
    new StreetViewPanoramaOptions().position(SAN_FRAN));

有关 StreetViewPanoramaFragment 的更多信息

StreetViewPanoramaFragmentAndroid Fragment 类的一个子类,用于在 Android Fragment 中放置街景全景图。

StreetViewPanoramaFragment 对象充当全景图容器,并提供对 StreetViewPanorama 对象的访问权。

注:Google Maps Android API 需要 API 级别 12 或更高级别,才能支持 StreetViewPanoramaFragment 对象。 如果您的目标是低于 API 级别 12 的应用,可通过 SupportStreetViewPanoramaFragment 类访问同一功能。

您还需要提供 Android 支持库

注:Google Maps Android API 不支持在一个 Activity 中包含多个 StreetViewPanoramaFragment 对象。

StreetViewPanoramaView

StreetViewPanoramaView 是 Android View 类的一个子类,用于在 Android View 中放置街景全景图。

View 表示屏幕的某个矩形区域,是 Android 应用和小工具的基本构建基块。

StreetViewPanoramaViewStreetViewPanoramaFragment 很相似,它也充当全景图容器,通过 StreetViewPanorama 对象公开核心全景图功能。

此类的用户必须将所有 Activity 生命周期方法(如 onCreate()onDestroy()onResume()onPause()))都转发给 StreetViewPanoramaView 类中的相应方法。

注:Google Maps Android API 不支持在一个 Activity 中包含多个 StreetViewPanoramaView 对象。

定制用户控制功能

默认情况下,用户在查看街景全景图时可使用以下功能:平移、缩放和前往相邻全景图。

您可以通过 StreetViewPanorama 上的方法启用和禁用用户控制手势。 禁用手势时,仍可通过编程做出更改。

setPanningGesturesEnabled()
决定用户是否能通过拖动来调整摄像头的朝向。
      mSvp.setPanningGesturesEnabled(false);
setUserNavigationEnabled()
决定用户是否能移至另一幅全景图。 用户可以通过单次点按导航链接或者两次点按视图,移至新的全景图。
      mSvp.setUserNavigationEnabled(false);
setZoomGesturesEnabled()
决定用户是否能通过捏合手指进行缩放。
      mSvp.setZoomGesturesEnabled(false);

此外,您还可以决定是否为用户显示街道名称:

setStreetNamesEnabled()
决定用户是否能看到显示在地面上的街道名称。
      mSvp.setStreetNamesEnabled(false);

设置全景图的位置

如需设置街景全景图的位置,请调用 StreetViewPanorama.setPosition() 以传递 LatLng

您还可以传递 radius 作为可选参数。 如果您想扩大或缩小街景寻找匹配全景图的区域,就可以使用半径。 半径为 0 意味着必须将全景图链接到指定 LatLng 所在的确切位置。

默认半径为 50。如果匹配区域中有多幅全景图,API 将返回匹配度最高的全景图。

private static final LatLng SAN_FRAN = new LatLng(37.765927, -122.449972);
mSvp.setPosition(SAN_FRAN);

此外,您还可以通过向 StreetViewPanorama.setPosition() 传递 panoId,根据全景图 ID 设置位置。

如需检索相邻全景图的全景图 ID,请先使用 getLocation() 检索 StreetViewPanoramaLocation

该对象包含当前全景图的 ID 和一个 StreetViewPanoramaLink 对象数组,其中的每个对象都包含与当前全景图相连的全景图的 ID。

StreetViewPanoramaLocation location = mSvp.getLocation();
if (location != null && location.links != null) {
    mSvp.setPosition(location.links[0].panoId);
}

放大和缩小

您可以通过设置 StreetViewPanoramaCamera.zoom 以编程方式更改缩放比例。

将缩放比例设置为 1.0 将把图像放大 2 倍。

下面这段代码使用 StreetViewPanoramaCamera.Builder() 构建一个新的摄像头,该摄像头具有现有摄像头的倾斜角度和方位,但将缩放比例增加了 50%。

private static final float ZOOM_BY = 0.5f;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom + ZOOM_BY)
    .tilt(mSvp.getPanoramaCamera().tilt)
    .bearing(mSvp.getPanoramaCamera().bearing)
    .build();

设置摄像头朝向(视角)

您可以通过在 StreetViewPanoramaCamera 上设置方位和倾斜角度来确定街景摄像头的朝向。

方位
摄像头指向的方向,以与摄像头所在地周围正北方所呈顺时针角度表示。 正北方为 0,东方为 90,南方为 180,西方为 270。
倾斜角度
Y 轴上倾或下倾角度。 范围是 -90 至 0 至 90,-90 为垂直俯视,0 为水平居中,90 为垂直仰视。 方差的测量根据是摄像头的初始默认间距,该间距通常(但并不总是)水平间距。 例如,在小山上拍摄的图像的默认间距多半不是水平间距。

下面这段代码使用 StreetViewPanoramaCamera.Builder() 构建一个新的摄像头,该摄像头具有现有摄像头的缩放比例和倾斜角度,但将方位向左调整了 30 度。

private static final int PAN_BY = 30;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom)
    .tilt(mSvp.getPanoramaCamera().tilt)
    .bearing(mSvp.getPanoramaCamera().bearing - PAN_BY)
    .build();

下面这段代码可使摄像头向上倾斜 30 度。

float tilt = mSvp.getPanoramaCamera().tilt + 30;
tilt = (tilt > 90) ? 90 : tilt;

StreetViewPanoramaCamera previous = mSvp.getPanoramaCamera();

StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder(previous)
    .tilt(tilt)
    .build();

以动画形式呈现摄像头切换

如需以动画形式呈现摄像头切换,请调用 StreetViewPanorama.animateTo()

动画在摄像头当前属性与摄像头新属性之间插入。 如果您想直接完成摄像头切换而不使用动画,可以将持续时间设置为 0。

// Set the tilt to zero, keeping the zoom and bearing at current values.
// Animate over a duration of 500 milliseconds.
long duration = 500;
float tilt = 0;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom)
    .bearing(mSvp.getPanoramaCamera().bearing)
    .tilt(tilt)
    .build();

mSvp.animateTo(camera, duration);

发送以下问题的反馈:

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