Android for Cars - Jetpack 迁移指南

Android for Cars 应用库现在是 Jetpack 的一部分！迁移到 Jetpack 可带来诸多优势，包括可让您更深入地了解我们的功能开发，以及与其他 Jetpack 库实现 API 一致性。

在此次迁移到 Jetpack 的过程中，我们对 API 做出了一些更改，以与 Android 生态系统的其余部分保持一致。为了帮助您迁移已使用汽车应用库的闭源版本构建的任何应用，我们编制了本指南，它详细介绍了这些更改，并提供了关于将应用迁移到新库的说明。

AndroidManifest 更改

在应用的 AndroidManifest.xml 中，将以下闭源库实例替换为 Jetpack 库等效实例（如果适用）：

应用类别

闭源	Jetpack 库等效实例
`com.google.android.car.category.NAVIGATION`	`androidx.car.app.category.NAVIGATION`
`com.google.android.car.category.PARKING`	`androidx.car.app.category.PARKING`
`com.google.android.car.category.CHARGING`	`androidx.car.app.category.CHARGING`

权限

闭源	Jetpack 库等效实例
`com.google.android.libraries.car.app.ACCESS_SURFACE`	`androidx.car.app.ACCESS_SURFACE`
`com.google.android.libraries.car.app.NAVIGATION_TEMPLATES`	`androidx.car.app.NAVIGATION_TEMPLATES`
未提供。Jetpack 库中新增	`androidx.car.app.MAP_TEMPLATES`

CarAppService

闭源	Jetpack 库等效实例
`com.google.android.car.action.CAR_APP`	`androidx.car.app.CarAppService`

主题

闭源	Jetpack 库等效实例
`com.google.android.libraries.car.app.theme`	`androidx.car.app.theme`

API 更改

命名空间更改

库的命名空间已从 com.google.android.libraries.car.app 更改为 androidx.car.app。

替换从 com.google.android.libraries.car.app.* 到 androidx.car.app.* 的所有库导入。

CarAppService 和 Session

我们已将主机与应用连接的生命周期从 CarAppService 分离为一个新的 Session 类。CarContext 和 Screen 创建逻辑现已移至 Session。

应用的一个主入口点 CarAppService#onCreateScreen(Intent) 已替换为 CarAppService.onCreateSession。之前在 CarAppService 中的许多方法现在其实都在 Session 类中。如需查看摘要，请参阅下表；如需了解详情，请参阅 Session 的类级文档。

CarAppService

闭源	Jetpack 库等效实例
`finish()`	已移除改为直接调用 `CarContext.finishCarApp`。
`getCarContext()`	已移至 `Session`
`getLifecycle()`	已移至 `Session`
`onCarAppFinished()`	已移除改为使用 `Session.getLifecycle` 并监听 `Lifecycle.Event#ON_DESTROY` 事件。
`onCarConfigurationChanged(Configuration)`	已移至 `Session`
`onCreateScreen(Intent)`	已移至 `Session`
`onDestroy()`	已移除此方法现在不相关，相应的逻辑在 `CarAppService.onUnbind` 中进行处理。
`onNewIntent(Intent)`	已移至 `Session`
未提供。Jetpack 库中新增	`getCurrentSession()`
未提供。Jetpack 库中新增	`onCreateSession()`
未提供。Jetpack 库中新增	`createHostValidator()` 请参阅主机验证。

Session

闭源	Jetpack 库等效实例
已移出 `CarAppService`	`getCarContext()`
已移出 `CarAppService`	`getLifeCycle()`
已移出 `CarAppService`	`onCarConfigurationChanged(Configuration)`
已移出 `CarAppService`	`onCreateScreen(Intent)`
已移出 `CarAppService`	`onNewIntent(Intent)`

在最简单的形式中，如果应用没有任何处理连接生命周期的逻辑，则它可以像这样返回 Session 实例：

  @Override
  @NonNull
  public Session onCreateSession() {
    return new Session() {
      @Override
      @NonNull
      public Screen onCreateScreen(@Nullable Intent intent) {
        return new HelloWorldScreen(getCarContext());
      }
    };
  }

构建器构造函数

我们正在逐步弃用我们提供静态构建器来创建各种数据对象的模型。我们改为直接将构建器构造函数作为公开方法来提供。例如：

    Pane.Builder paneBuilder = Pane.builder();

已变为：

    Pane.Builder paneBuilder = new Pane.Builder();

构建器可重用性

我们正在逐步弃用我们明确支持重用构建器的模型。允许应用清除之前设置的某些数据的构建器方法不再可用。例如，已移除以下方法（以及其他 clear* 方法）：

    ActionStrip.Builder.clearActions()

新的 GridItem 和 GridTemplate

Jetpack 库附带一个新的 GridTemplate，它能以网格格式显示 GridItem 的列表。如需了解详情和用法，请参阅 GridTemplate 的文档。

主机验证

我们添加了相关的机制，允许应用验证主机连接是否来自可信来源（例如，Android Auto 和 Android Automotive OS）。抽象 CarAppService.createHostValidator 方法的实现示例如下所示：

    @Override
    public HostValidator createHostValidator() {
        if ((getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
            return HostValidator.ALLOW_ALL_HOSTS_VALIDATOR;
        } else {
            return new HostValidator.Builder(getApplicationContext())
                    .addAllowedHosts(androidx.car.app.R.array.hosts_allowlist_sample)
                    .build();
        }
    }

如需了解详情，请参阅 CarAppService.createHostValidator 的文档。

其他方面的更改

下表重点介绍了我们对库所做的其余更改（例如重命名现有 API 或添加其他 API）。请注意，此列表并非详尽无遗，但可让您了解我们对库所做的各类更改。

AppManager

闭源	Jetpack 库等效实例
`setSurfaceListener(SurfaceListener)`	`setSurfaceCallback(SurfaceCallback)`

CarContext

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`getCarAppApiLevel()`

OnScreenResultCallback -> OnScreenResultListener

Screen

闭源	Jetpack 库等效实例
`static final String ROOT`	已移除已被 `ScreenManager.poptoRoot` 替代
`getTemplate()`	`onGetTemplate()`

ScreenManager

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`popToRoot()`

SurfaceListener -> SurfaceCallback

ItemList.Builder

闭源	Jetpack 库等效实例
`setOnItemsVisibilityChangeListener(OnItemsVisibilityChangedListener)`	`setOnItemsVisibilityChangedListener(OnItemsVisibilityChangedListener)`
`setSelectable(OnSelectedListener)`	`setOnSelectedListener(OnSelectedListener)`

ListTemplate.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

Pane.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

PlaceListMapTemplate.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

Row.Builder

闭源	Jetpack 库等效实例
`setIsBrowsable(boolean)`	`setBrowsable(boolean)`

SearchTemplate.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

com.google.android.libraries.car.app.SearchListener -> androidx.car.app.model.SearchTemplate.SearchCallback

Toggle.Builder

闭源	Jetpack 库等效实例
`setCheckedChangeListener(OnCheckedChangeListener)`	`setOnCheckedChangeListener(OnCheckedChangeListener)`

NavigationManagerListener -> NavigationManagerCallback

闭源	Jetpack 库等效实例
`stopNavigation()`	`onStopNavigation()`

NavigationManager

闭源	Jetpack 库等效实例
`setListener(NavigationManagerListener)`	`setNavigationManagerCallback(NavigationManagerCallback)`
未提供。Jetpack 库中新增	`setNavigationManagerCallback(Executor, NavigationManagerCallback)`
未提供。Jetpack 库中新增	`clearNavigationManagerCallback()`

Maneuver

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`static int TYPE_ROUNDABOUT_ENTER_CW` `static int TYPE_ROUNDABOUT_EXIT_CW` `static int TYPE_ROUNDABOUT_ENTER_CCW` `static int TYPE_ROUNDABOUT_EXIT_CCW` `static int TYPE_FERRY_BOAT_LEFT` `static int TYPE_FERRY_BOAT_RIGHT` `static int TYPE_FERRY_TRAIN_LEFT` `static int TYPE_FERRY_TRAIN_RIGHT`
已移除	`static int TYPE_ROUNDABOUT_ENTER` `static int TYPE_ROUNDABOUT_EXIT`

PlaceListNavigationTemplate.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

RoutePreviewNavigationTemplate.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

RoutingInfo.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

TravelEstimate

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`static long REMAINING_TIME_UNKNOWN`
`static Builder builder(Distance, Duration, DateTimeWithZone)`	`static Builder builder(Distance, DateTimeWithZone)`
`static Builder builder(Distance, Duration, ZonedDateTime)`	`static Builder builder(Distance, ZonedDateTime)`

TravelEstimate.Builder

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`setRemainingTimeSeconds(long)`
未提供。Jetpack 库中新增	`setRemainingTime(Duration)`

Trip.Builder

闭源	Jetpack 库等效实例
`setIsLoading(boolean)`	`setLoading(boolean)`

CarAppExtender

闭源	Jetpack 库等效实例
`getLargeIconBitmap()`	`getLargeIcon()`
`getSmallIconResId()`	`getSmallIcon()`

CarAppExtender.Builder

闭源	Jetpack 库等效实例
未提供。Jetpack 库中新增	`setColor(CarColor)`

测试库

第一个 Beta 版中尚未提供测试库。测试库提供的通过构建器类访问模型中设置的字段的部分功能现在可通过模型的 getter 自身获得。在不久的将来，当测试库作为 Jetpack 的一部分发布时，就会提供其余测试功能。