构建地图注点应用

本部分详细介绍您可以使用库的哪些不同功能来实现地图注点 (POI) 应用的功能。

在清单中声明类别支持

应用需要在其 CarAppService 的 intent 过滤器中声明 androidx.car.app.category.POI 汽车应用类别

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.POI"/>
      </intent-filter>
    </service>
    ...
<application>

访问地图模板

应用可以访问 PlaceListMapTemplate,该模板专门用于在由主机渲染的地图上显示一系列感兴趣的地点。

为了能够访问此模板,应用需要在其 AndroidManifest.xml 中声明 androidx.car.app.MAP_TEMPLATES 权限:

<uses-permission android:name="androidx.car.app.MAP_TEMPLATES"/>

刷新 PlaceListMapTemplate 内容

您可以允许驾驶员在浏览使用 PlaceListMapTemplate 构建的地点列表时通过点按按钮来刷新内容。实现 OnContentRefreshListener 接口的 onContentRefreshRequested 方法并使用 PlaceListMapTemplate.Builder.setOnContentRefreshListener 在模板上设置监听器,即可启用列表刷新功能。

以下代码段展示了如何在模板上设置监听器:

Kotlin

PlaceListMapTemplate.Builder()
    ...
    .setOnContentRefreshListener {
        // Execute any desired logic
        ...
        // Then call invalidate() so onGetTemplate() is called again
        invalidate()
    }
    .build()

Java

new PlaceListMapTemplate.Builder()
        ...
        .setOnContentRefreshListener(() -> {
            // Execute any desired logic
            ...
            // Then call invalidate() so onGetTemplate() is called again
            invalidate();
        })
        .build();

仅当监听器具有值时,PlaceListMapTemplate 的标头中才会显示刷新按钮。

当驾驶员点击刷新按钮时,系统会调用您的 OnContentRefreshListener 实现的 onContentRefreshRequested 方法。在 onContentRefreshRequested 中,调用 Screen.invalidate 方法。主机随后回调应用的 Screen.onGetTemplate 方法,以检索包含已刷新内容的模板。如需详细了解如何刷新模板,请参阅刷新模板的内容。只要 onGetTemplate 返回的下一个模板属于同一类型,系统就会将其视为一次刷新,而不会将其计入模板配额。

使用与应用有关的 Action 与 Google 助理相集成

与应用有关的 Action 让用户可以使用 Google 助理通过语音启动和控制 Android 应用。您可以通过添加与应用有关的 Action 功能,将 Google 助理与地图注点应用相集成。功能是应用相关功能的表达,包含内置 intent (BII) 及其执行方式。例如,如果用户说出“Ok Google,在 ExampleApp 上查找街道停车位”,您的应用就可以打开应用中的相应屏幕。

限制

与应用有关的 Action 存在以下限制:

  • 仅适用于在地图注点类别中使用汽车应用库的应用。
  • 语音支持仅适用于停车充电内置 intent。
  • 与应用有关的 Action 执行方式只能通过深层链接完成。

集成步骤

  1. AndroidManifest.xml 文件的 <application> 元素中添加以下 <meta-data> 元素:

     <meta-data
         android:name="android.app.shortcuts"
         android:resource="@xml/shortcuts" />
    
  2. 如要让 Google 助理通过深层链接链接到您应用的内容,您需要在 AndroidManifest.xml 文件中添加 <intent-filter> 元素。

    • 对于 Android Auto,intent-filter 与您的移动应用相同。

    • 对于 Android Automotive OS 执行方式,与应用有关的 Action 由 CarAppService 会话触发。要允许会话触发深层链接,您必须在 AndroidManifest.xml 文件的 <activity> 元素中指定 intent 过滤器。

    <activity
      ...
      android:name="androidx.car.app.activity.CarAppActivity">
      …
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data
            android:scheme="YOUR_SCHEME"
            android:host="YOUR_HOST" />
      </intent-filter>
    </activity>
    
  3. 在应用项目的 res/xml 目录中创建一个具有恰当功能的 shortcuts.xml 文件:

    <?xml version="1.0" encoding="utf-8"?>
    <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
      <!-- Your Capability definitions will go here -->
    </shortcuts>
    

    如要了解停车充电功能的相关信息,请参阅如下的“功能”部分。

  4. 更新您的应用,以处理某个会话的执行方式。

    以下是 Session.onCreateScreenSession.onNewIntent 的 intent 处理示例

    onCreateScreen

    Kotlin

    @Override
    fun onCreateScreen(@NonNull intent: Intent): Screen {
      if (intent.getData() != null) {
          val uri: Uri = intent.getData()
          // uri = "YOUR_SCHEME://YOUR_HOST?name=Levis%20center"
          // Build your Templates with parsed uri parameters
      ...
     }
    }
    

    Java

    @Override
    public Screen onCreateScreen(@NonNull Intent intent) {
     if (intent.getData() != null) {
       Uri uri = intent.getData();
       // uri = "YOUR_SCHEME://YOUR_HOST?name=Levis%20center"
       // Build your Templates with parsed uri parameters
      …
     }
    }
    

    onNewIntent

    Kotlin

    @Override
    fun onNewIntent(@NonNull intent: Intent): Screen {
      if (intent.getData() != null) {
          val uri: Uri = intent.getData()
          // uri = "YOUR_SCHEME://YOUR_HOST?name=Levis%20center"
          // Build your Templates with parsed uri parameters
          …
      }
    }
    

    Java

    @Override
    public void onNewIntent(@NonNull Intent intent) {
     if (intent.getData() != null) {
       Uri uri = intent.getData();
       // uri = "YOUR_SCHEME://YOUR_HOST?name=Levis%20center"
       // Build your Templates with parsed uri parameters
       …
     }
    }
    

功能

与应用有关的 Action 支持以下功能:

停车

操作 IDactions.intent.GET_PARKING_FACILITY

说明:获取停车设施信息。可以指定停车类型、应用名称和位置。

语言区域支持:en-US

参数

  • parkingFacility.disambiguatingDescription - 停车类型的描述符,例如“免费停车”、“代客停车”或“街道停车”。您可以使用此参数过滤停车设施的类型。
  • 以下参数可以帮助您确定用户请求的停车设施的位置。如果这些都不存在,您应返回距离用户当前位置最近的设施。
    • parkingFacility.name - 设施位置的名称,例如“东城区”
    • parkingFacility.address - 设施所在位置的地址,例如“北京市东城区王府井大街 19 号”
    • parkingFacility.geo.latitude - 设施的纬度,例如“37.3861”
    • parkingFacility.geo.longitude - 设施的经度,例如“-122.084”

capability 定义示例

<?xml version="1.0" encoding="utf-8"?>
<!-- This is a sample shortcuts.xml -->
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">

  <capability android:name="actions.intent.GET_PARKING_FACILITY">
    <intent>
      <url-template
       android:value="YOUR_SCHEME://YOUR_HOST{?name,address,disambiguatingDescription,latitude,longitude}">

      <!-- Eg. name = "Googleplex" -->
      <parameter
        android:name="parkingFacility.name"
        android:key="name"/>
      <!-- Eg. address = "1600 Amphitheatre Pkwy, Mountain View, CA 94043" -->
      <parameter
        android:name="parkingFacility.address"
        android:key="address"/>
      <!-- Eg. disambiguatingDescription = "valet" -->
      <parameter
        android:name="parkingFacility.disambiguatingDescription"
        android:key="disambiguatingDescription"/>
      <!-- Eg. latitude = "37.3861" -->
      <parameter
        android:name="parkingFacility.geo.latitude"
        android:key="latitude"/>
      <!-- Eg. longitude = "-122.084" -->
      <parameter
        android:name="parkingFacility.geo.longitude"
        android:key="longitude"/>
    </intent>
  </capability>
</shortcuts>

充电

操作 IDactions.intent.GET_CHARGING_STATION

说明:获取充电站信息。可指定应用名称或位置。

语言区域支持:en-US

参数

  • chargingStation.disambiguatingDescription - 充电站类型描述符,例如“免费”、“付费”。您可以使用此参数过滤充电站的类型。
  • 以下参数可以帮助您确定用户请求的充电站的位置。如果这些都不存在,您应返回距离用户当前位置最近的充电站。
    • chargingStation.name - 充电站位置的名称,例如“东城区”
    • chargingStation.address - 充电站所在位置的地址,例如“北京市东城区王府井大街 19 号”
    • chargingStation.geo.latitude - 充电站的纬度,例如“37.3861”
    • chargingStation.geo.longitude - 充电站的经度,例如“-122.084”

capability 定义示例

<?xml version="1.0" encoding="utf-8"?>
<!-- This is a sample shortcuts.xml -->
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.GET_CHARGING_STATION">
    <intent>
      <url-template
       android:value="YOUR_SCHEME://YOUR_HOST{?name,address,latitude,longitude,type}">

      <!-- Eg. name = "Googleplex" -->
      <parameter
        android:name="chargingStation.name"
        android:key="name"/>
      <!-- Eg. address = "1600 Amphitheatre Pkwy, Mountain View, CA 94043" -->
      <parameter
        android:name="chargingStation.address"
        android:key="address"/>
      <!-- Eg. latitude = "37.3861" -->
      <parameter
        android:name="chargingStation.geo.latitude"
        android:key="latitude"/>
      <!-- Eg. longitude = "-122.084" -->
      <parameter
        android:name="chargingStation.geo.longitude"
        android:key="longitude"/>
    </intent>
  </capability>
</shortcuts>