构建地图注点应用

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

在清单 (manifest) 中声明类别支持

应用需要在其 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 功能 (capability),将 Google 助理与地图注点应用相集成。功能 (capability) 是应用相关功能的表达,包含内置 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>