汽车应用

汽车应用

用户指南 代码示例

API 参考文档
androidx.car.app
androidx.car.app.model
androidx.car.app.navigation
androidx.car.app.notification
androidx.car.app.serialization
androidx.car.app.validation
androidx.car.app.versioning

构建 Android Auto 导航、停车和收费应用。

最近更新时间	稳定版	候选版本	Beta 版	Alpha 版
2022 年 7 月 27 日	1.1.0	1.2.0-rc01	-	1.3.0-alpha01

声明依赖项

如需添加对汽车应用库的依赖关系，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.car.app:app:1.1.0"

    // For Android Auto specific functionality
    implementation "androidx.car.app:app-projected:1.1.0"

    // For Android Automotive specific functionality
    implementation "androidx.car.app:app-automotive:1.1.0"

    // For testing
    testImplementation "androidx.car.app:app-testing:1.3.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.car.app:app:1.1.0")

    // For Android Auto specific functionality
    implementation("androidx.car.app:app-projected:1.1.0")

    // For Android Automotive specific functionality
    implementation("androidx.car.app:app-automotive:1.1.0")

    // For testing
    testImplementation("androidx.car.app:app-testing:1.3.0-alpha01")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库的改进有自己的见解，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.3

版本 1.3.0-alpha01

2022 年 7 月 27 日

发布了 androidx.car.app:app-*:1.3.0-alpha01。版本 1.3.0-alpha01 中包含这些提交内容。

新功能

• 包括诸多功能，例如 Voice Access、警报器、地图窗格模板详情视图、响应式翻转卡片、点按地图、非地点内容导航模板内的列表、地图注点和路线预览上的地图互动（缩放和平移）、PlaceListNavigationTemplate 和 PlaceListMapTemplate 上的内容刷新（含减速带）。

API 变更

• 在 ServiceConnection 中支持多会话绑定（内部更改）(I8e041)
• 添加了新的 API SuggestionManager#updateSuggestions，用于向汽车主机分享建议 (I5c103)
• 支持在达到超时后警报器的默认操作 (I5ad70)
• CarAppService#onCreateSession() 现在会抛出异常，指出应改为实现 #onCreateSession(SessionInfo) (I33a17)
• 添加了 CarAppService#CATEGORY_FEATURE_CLUSTER，这是用于在应用的 AndroidManifest.xml 中声明集群支持的常量 (Id468d)
• 添加了 CarAppService#onCreateSession(SessionInfo) 并废弃了旧的 CarAppService#onCreateSession()。(I2db53)
• 添加了 SessionInfo#getSupportedTemplates (I96985)
• 将一个实验性的类的 getter 标记为实验性。(Ib6e6a)
• 应用将使用 API 访问汽车温控系统 (Ib628b)
• 向 TravelEstimate 新 API 添加了 RequiresCarApi 注解 (Ic620d)
• 将新的头文件元素添加到其他导航模板 (I30e6a)
• 将 CarZone 作为实验性 API 添加到 androidx。(I99097)
• 为 Toggle、Action 和 Row 添加了停用状态 (Id8a09)
• 在 MapTemplate 中添加了对 ItemList 的支持 (If44b8)
• 创建了对检索车载麦克风输入的支持。(I5e71a)
• 移除了汽车应用 API 级别为 5 的 API 的实验性 API (If1a92)
• 添加了地图注点作为启用地图注点应用的类别 (I59da1)
• 更新了 TravelEstimateCard 以允许 mis. 数据/图像。(Idcc6d)
• 将汽车应用 API 级别更新为 5 (I26b8e)
• 在 CarAppLibrary 中添加了一个新的 API，用于启用应用内提醒。(I163a7)
• 添加了允许添加地图注点用例的通用模板 (If5826)

bug 修复

• 添加了对 PaneTemplate 标题中 CarIconSpan 的支持 (Ia1ee0)
• 将 Cristian 和 David 添加到所有者 (Ib66ba)
• 将 PaneTemplate 图片大小调整规则更新为方形边界框 (Idd72e)
• 重构了 CarAppService 中的汽车应用服务绑定 (Ic7e04)
• 修复了在 State.DESTROYED 之后修改屏幕堆栈时发生的异常。(I3c8eb)
• 移除了实验性 API 的项目依赖项 (Iac362)
• 为 AutomotiveCarClimate 添加了注册/取消注册 API。(If2dd3)

版本 1.2

版本 1.2.0-rc01

2022 年 3 月 23 日

发布了 androidx.car.app:app-*:1.2.0-rc01。版本 1.2.0-rc01 中包含这些提交内容。

• 这是一个稳定版本，与 v1.2.0-beta02 相比，API 没有变化。新增了专为未来的 Android Auto 和 Android Automotive 版本设计的实验性功能（API 级别 5）。

bug 修复

• 修复了在 State.DESTROYED 之后修改屏幕堆栈时发生的异常。(I3c8eb)
• 更新了 CarSensors API 以表明未针对 AAOS 实现这些 API (Idd57b)
• 更新了 PlaceListMapTempalte.Builder#setCurrentLocationEnabled 以表明 ACCESS_COARSE_LOCATION 足以满足未来的需求 (I510c2)
• 将 Maneuver 类型 roundabout-with-angle 的出口编号设为可选属性 (Ife7d1)

版本 1.2.0-beta02

2022 年 1 月 26 日

发布了 androidx.car.app:app-*:1.2.0-beta02。版本 1.2.0-beta02 中包含这些提交内容。

使用此库版本构建的针对 Android Automotive OS 平台的汽车应用现在可以发布到 Play 商店开放式测试渠道。如需了解详情，请参阅开发指南。

带有 API 级别 4 及更低级别注解的功能与 Android Auto 7.2 及更高版本和新的 Android Automotive OS 平台兼容。如需了解注意事项，请参阅下文的“Known Issues”部分。

API 变更

• 向 POI 模板添加了实验性 setOnContentRefreshListener API (I6bf22)

bug 修复

• 修复了汽车主机取消绑定时 CarAppService 中发生内存泄漏的问题。（I5c9ca、b/203594731）
• 更新了 CarAppActivity javadoc，在其中添加了关于 singleTask 启动模式的要求 (Id2f95)
• 减少了恢复时的视觉小故障。(Iff7e0)

已知问题

• PlaceListNavigationTemplate 和 RoutePreviewNavigateTemplate 中的地图 ActionStrip 将在 Android Auto 和 Android Automotive OS 的下个版本中开始可用。

版本 1.2.0-alpha02

2021 年 12 月 15 日

发布了 androidx.car.app:app-*:1.2.0-alpha02。版本 1.2.0-alpha02 中包含这些提交内容。

带有 API 级别 4 注解的功能已从实验性功能升级为稳定功能，包括 PlaceListNavigationTemplate 和 RoutePreviewNavigateTemplate 中的地图 ActionStrip、Pane 中的 CarIcon 图像、QRCodeSignInMethod，以及能够在 Action 中设置渲染提示（例如标记）。

新功能

• 在 Android Auto 7.1 及更高版本中，Pane 的项目数量上限已从 2 提高至 4。

API 变更

• 向 CarUnit 中添加了实验性 toString() 方法 (I36a3b)

bug 修复

• 修复了回调无效后在 CarAppPermissionActivity 中发生崩溃的问题 (If9823)
• 将 Pane 的默认列表上限更改为了 4 (I0068b)

版本 1.2.0-alpha01

2021 年 11 月 3 日

发布了 androidx.car.app:app-*:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

所有新的 v1.2.0 功能（API 4 及更高级别）目前都处于实验阶段，将会面向未来的 Android Auto 和 Android Automotive OS 版本发布。如需了解详情，请参阅开发指南。

API 变更

• 将 AutomotiveCarInfo API 变为了实验性 API。(Ia13e5)
• 添加了 Car App Library API 级别 4 (I2a2e7)
• API 级别 4：现在支持在 Pane 中设置 CarIcon (Ifcc12)
• API 级别 4：添加了二维码登录方法 (Ib623e)
• API 级别 4：向 Action 添加了 set/getFlags (Ic03ab)
• API 级别 4：在 PlaceListNavigationTemplate 和 RoutePreviewNavigationTemplate 中添加了对平移和缩放的支持 (I9d8a3)

bug 修复

• API 级别 4：添加了允许应用向汽车主机发送位置信息更新的机制 (I3bad3)
• 修复了主机验证逻辑无法正确找到 MODEL_RENDERER 权限的问题 (I62618)

版本 1.1.0

版本 1.1.0

2021 年 12 月 15 日

发布了 androidx.car.app:app-*:1.1.0。版本 1.1.0 中包含这些提交内容。

这是一个稳定版本，与 v1.1.0-rc01 相比没有变化。另请参阅 v1.2.0-alpha02 的版本说明，详细了解汽车应用库的新功能。

自 1.0.0 以来的重要变更

• API 级别 2：新增了 SignInTemplate 和 LongMessageTemplate，可用于车辆停好后的登录流程
• API 级别 2：NavigationTemplate 内新增了地图互动支持
• API 级别 2：新增了对多个文本长度的支持，使应用能够提供多个版本的字符串，以根据车载显示屏的尺寸显示相应版本。
• API 级别 3：添加了 CarHardwareManager，可用于查询车辆的硬件数据，如型号和品牌、油位以及其他传感器。

版本 1.1.0-rc01

2021 年 11 月 3 日

发布了 androidx.car.app:app-*:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

这是一个稳定版本，与 v1.1.0-beta01 相比，API 没有变化。新增了专为未来的 Android Auto 版本设计的实验性功能（API 级别 4）。如需详细了解实验性 API，请参阅 v1.2.0-alpha01 的版本说明。

版本 1.1.0-beta01

2021 年 9 月 1 日

发布了 androidx.car.app:app-*:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

所有 v1.1.0 功能（API 2 及更高级别）都与 Android Auto 6.7 及更高版本完全兼容。如需了解详情，请参阅开发指南。

API 变更

• 移除了作为公共接口的 Manager (Ie381b)
• 添加了为权限请求设置自定义品牌背景的功能 (I74b76)
• 添加了 ScreenManager.getStackSize (I0b16a)
• 移除了显式获取 TestCarContext 的 ScreenController 构造函数 (Iefebc)

bug 修复

• 添加了创建 CarHardwareManager 时的 API 级别检查 (I48f9b)
• 添加了针对整个 API 中无效使用 CarSpan 情况的检查 (I65ae6)
• 修复了以下问题：如果 Screen 在创建过程中被标记为完成，则会将堆栈留为损坏状态 (I81b13)
• 修复了以下问题：如果 CarAppExtender 中的操作带有图标，CarNotificationManager.notify 会针对 AutomotiveOS 记录错误 (I3633d)
• 为应用和主机添加了一个握手方法，用于确定 API 版本 (I7d6f8)

版本 1.1.0-alpha02

2021 年 7 月 21 日

发布了 androidx.car.app:app-*:1.1.0-alpha02。版本 1.1.0-alpha02 中包含这些提交内容。

新功能

• API 级别 3：添加了 CarHardwareManager，可用于查询车辆的硬件数据，如型号和品牌、油位以及其他传感器。目前，在开放式测试渠道中，此功能仅适用于 Android Auto 6.7 及更高版本。如要在桌面环境中测试此功能，您需要将单独发布的新版 Desktop Head Unit。敬请关注“测试 Android 车载应用”页面，详细了解该新版本何时发布。
• 请参阅开发指南和库参考文档，详细了解如何在与 API 级别 3 兼容的汽车主机中使用这些功能以及相关的设计准则。

API 变更

• 将 SessionController 和 ScreenController 生命周期方法合并为一个 moveToState 方法 (I1ed00)
• 添加了 CarContext#getHostInfo() (I8977e)
• 移除了已弃用的字段。(I67168)
• 更新了 SessionController 和 ScreenController，以直接提供构造函数 (Iabf22)
• 移除了 PinSignInMethod.Builder 和 ProviderSignInMethod.Builder (I9f0cb)
• 添加了“setCarAppResult()”，以支持在 AAOS 中使用模板化应用“for result”(I37741)
• 使用 @MainThread 对 CarHardware 接口进行了注解。(Ib2f85)
• 将 OnCarDataListener 重命名为 OnCarDataAvailableListener (I518ca)
• 更新了 CarInfo、Speed、Mileage 方法名称和 javadoc。(I86672)
• 将 Toll 重命名为 TollCard。(I3e7c8)
• 移除了已弃用的 PinSignInMethod.getPin，取而代之的是 PinSignInMethod.getPinCode (I996ce)
• 移除了 OnInputCompletedListener（取而代之的是 InputCallback）。(Ib5be1)
• 将 PinSignInMethod 更改为接受 CharSequence（而非 String）(I275d5)

bug 修复

• 对汽车硬件进行了 Javadoc 修复。(I2abbc)

外部贡献

已知问题

• 在 SignInTemplate 中，使用 InputSignInMethod 可能会导致汽车主机中出现 NullPointerException。此问题将在下一个版本的库中得到解决。解决此问题的权宜方法是，在应用的 Proguard 配置中添加以下代码行：-keep class androidx.car.app.model.signin.InputSignInMethod { *; }

版本 1.1.0-alpha01

2021 年 6 月 16 日

发布了 androidx.car.app:app:1.1.0-alpha01、androidx.car.app:app-automotive:1.1.0-alpha01 和 androidx.car.app:app-testing:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

• API 级别 2：新增了 SignInTemplate 和 LongMessageTemplate，可用于车辆停好后的登录流。
• API 级别 2：NavigationTemplate 内新增了地图互动支持
• API 级别 2：新增对多个文本长度的支持，允许应用提供多个版本的字符串，以根据车载显示屏的尺寸显示相应版本。
• 请参阅开发指南和库 Javadoc，详细了解如何在与 API 级别 2 兼容的汽车主机中使用这些功能以及相关的设计准则。

API 变更

• 将所有 *Callback 接口方法设为默认方法，并将 OnRequestPermissionsCallback 重命名为 OnRequestPermissionsListener (Ib3ec9)
• 更新了 androidx.car.app.hardware 类，以移除不必要的构建器和参数类。(I67beb)
• 添加了 androidx.car.app.hardware 类，用于访问汽车特有数据，例如燃油、电池和速度。(Iff3c9)
• 添加了对 MessageTemplate 的 ActionStrip 支持 (Ida657)
• 已将 setLoading 添加到 MessageTemplate 中。(I2a4b5)
• ConnectionToCar 已重命名为 CarConnection (Ife9bd)
• 更改了 NavigationTemplate 以返回显式 PanModeDelegate (I13877)
• 更新了 CarContext.requestPermissions 的参数顺序 (Ib890a)
• 更新了元数据键，以将最低 Car API 级别定义为 androidx.car.api.minCarApiLevel (Ib0d41)
• 创建了一个可用于观察汽车连接状态的 API (Ifc935)
• 添加了对设置 Action 切换开关的支持，并添加了平移模式 Action 类型 (Ica6af)
• 创建了 CarNotificationManager，以支持在汽车内发送通知 (I10d7a)
• 添加了 ConstraintManager，用于提供来自主机的列表限制 (I8690e)
• 在 NavigationTemplate 中添加了平移模式和地图操作栏 API (I77aa6)
• 在 SurfaceCallback 中为导航应用添加了平移和缩放 API (Id5e9d)
• CarAppApiLevel 已更新至 2 (Ic1540)
• 添加了向 CarAppService 请求权限的功能 (I5421e)
• 为多文本 API 添加了 RequiresCarApi(2) 注解 (Iacb62)
• 允许在半列表模板标题中使用多个文本变体 (Ib8df7)
• 添加了新的 LongMessageTemplate（要求 Car API 级别为 2）(Ic5cee)

bug 修复

• 更新了图片大小要求，以顾及到较大的车载显示屏 (I116dc)
• 禁止在模板主体中添加 2 个以上操作 (I32157)
• 已确保汽车应用库中创建的所有 PendingIntent 都设置了标志。（If84fe、b/186394900）
• 更新了 javadoc，使 Row 的文本可以在刷新时更改 (If3f9c)
• androidx.activity:activity:1.2.0 现在是 API 依赖项 (Id1cb9)
• 将 SignInTemplate 和 LongMessageTemplate 设为要求在其主体中包含仅限停车状态下的操作，并更新了文档以指示只能在停车后显示这些操作 (Iddaa9)
• 修复了启动期间会弹出 Screen 的异常（Ifcf40、b/184664896）
• 允许在 ForegroundCarColorSpan 中使用自定义文本颜色 (I69e59)
• 修复了以下问题：在对 Screen 执行 ON_DESTROY 之后观察到对 Session 执行 ON_DESTROY（I52e01、b/183696617）
• 更新了允许将 TravelEstimate 的剩余时间设置为未知时间时的 javadoc。（I99610、b/183632456）
• 更新了 Action，以支持标题和任何自定义背景颜色中的 ForegroundColorSpan (I578e4)
• 如果在执行程序执行之前清除了回调，就不会执行 NavigationManagerCallback#onStopNavigation（I7fc5e、b/181143772）
• 修复了要求应用显式依赖于 lifecycle-common-java8 的问题 (I8b8c8)

已知问题

• 在 SignInTemplate 中，当用户想要确认输入时，屏幕键盘会显示“搜索”图标而非“输入”图标。若要解决此问题，用户可以使用在输入字段获得焦点时激活的手机键盘。
• 在 Android Auto 版本 6.5 中，可能会针对某些轻触手势错误地调用 SurfaceCallback 中的平移和缩放回调。

Car App Testing 版本 1.0.0

版本 1.0.0-alpha01

2021 年 3 月 24 日

发布了 androidx.car.app:app-testing:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

这是先前关闭的源代码测试库的第一个 Jetpack 版本。如需了解如何在测试中使用此库，请参阅我们的示例。

新功能

• 模型类的控制器已被移除。模型 getter 现在是公共 API 接口的一部分，可用于验证在构建器中设置的值。
• 之前的 CarAppServiceController 已被新的 SessionController 取代，用于测试与热点的连接的生命周期相关逻辑。

版本 1.0.0

版本 1.0.0

2021 年 4 月 21 日

发布了 androidx.car.app:app:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

• 4 月初，我们宣布开发者可以开始使用 androidx.car.app:app:1.0.0-rc01 将应用发布到正式版发行渠道。汽车应用库 v1.0.0 现为稳定版本，且与 Android Auto 6.1 及更高版本完全兼容。
• 请参阅开发指南，详细了解如何使用该库为 Android Auto 构建导航、停车和充电应用。

bug 修复

• 修复了启动期间会弹出 Screen 的异常（70aae1、b/184664896）
• 修复了以下问题：在对 Screen 执行 ON_DESTROY 之后观察到对 Session 执行 ON_DESTROY（0ceecb、b/183696617）

版本 1.0.0-rc01

2021 年 3 月 24 日

发布了 androidx.car.app:app:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

• 修复了在清除回调后调用 NavigationManagerCallback#onStopNavigation 的竞态条件问题。如果在回调执行程序实际运行之前清除了回调，就会出现此问题（I7fc5e、b/181143772）
• 修复了要求应用显式依赖于 lifecycle-common-java8 的问题 (I8b8c8)
• 修复了应用在移除回调后收到 stopNavigation 调用时，系统抛出 NullPointerException 的问题（Ib8b89、b/181143772）
• 实施了多项改进，确保当应用的生命周期至少不处于 CREATED 状态时，系统将不向应用发送调用（I86965、b/179800224、b/177921120）
• 修复了由于应用清单中指定的最低 API 无效，导致主机上出现 ANR 的问题。（Iffedd、b/174231592）

版本 1.0.0-beta01

2021 年 2 月 24 日

发布了 androidx.car.app:app:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

这是先前闭源库的第一个 Jetpack 版本，且与 Android Auto 6.1 或更高版本兼容。请参阅开发指南，详细了解如何使用该库构建汽车应用。

新功能

• 引入了 GridTemplate，应用可以用它来在网格布局中显示界面元素列表。
• 引入了 CarAppService.createHostValidator 方法，用于验证主机连接是否来自可信来源（例如 Android Auto）。
• 添加了 CarAppExtender.Builder.setColor API。(b/174231592)

bug 修复

• 修复了按顺序弹出屏幕时恢复的 Screen 不正确的问题。(b/177590791)