Xây dựng ứng dụng chỉ đường

Trang này trình bày chi tiết các tính năng của Thư viện ứng dụng trên ô tô mà bạn có thể dùng để triển khai chức năng của ứng dụng chỉ đường theo từng chặng.

Khai báo khả năng hỗ trợ chỉ đường trong tệp kê khai

Ứng dụng chỉ đường của bạn cần khai báo androidx.car.app.category.NAVIGATION danh mục ứng dụng cho ô tô trong bộ lọc ý định của CarAppService:

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

Hỗ trợ ý định chỉ đường

Để hỗ trợ các ý định chỉ đường cho ứng dụng của bạn, bao gồm cả những ý định đến từ Trợ lý Google thông qua truy vấn bằng giọng nói, ứng dụng của bạn cần xử lý ý định CarContext.ACTION_NAVIGATE trong Session.onCreateScreen và Session.onNewIntent.

Vui lòng xem tài liệu về CarContext.startCarApp để biết thông tin chi tiết về định dạng của ý định.

Truy cập vào các mẫu chỉ đường

Ứng dụng chỉ đường có thể truy cập vào các mẫu được thiết kế riêng (cho ứng dụng chỉ đường) sau đây. Tất cả các mẫu này hiển thị một nền tảng trong nền cùng với bản đồ và trong khi chỉ đường, chỉ đường theo từng chặng.

• NavigationTemplate: cũng hiển thị thông báo thông tin không bắt buộc và các thông tin ước tính về hành trình trong khi chỉ đường.
• MapTemplate: trình bày phiên bản thu gọn của danh sách (như trong ListTemplate) hoặc của ngăn (thông tin chi tiết với các thao tác nổi bật, như trong PaneTemplate) bên cạnh bản đồ.
• PlaceListNavigationTemplate: cũng hiển thị danh sách các địa điểm, có thể chứa điểm đánh dấu tương ứng được vẽ trên bản đồ.
• RoutePreviewNavigationTemplate: cũng hiển thị danh sách các tuyến đường mà một trong số đó có thể được chọn và đánh dấu trên bản đồ.

Để biết thêm thông tin chi tiết về cách thiết kế giao diện người dùng của ứng dụng chỉ đường bằng các mẫu đó, hãy xem phần Ứng dụng chỉ đường.

Để có quyền truy cập vào các mẫu chỉ đường, ứng dụng của bạn cần khai báo quyền androidx.car.app.NAVIGATION_TEMPLATES trong tệp AndroidManifest.xml của ứng dụng:

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

Vẽ bản đồ

Các ứng dụng chỉ đường có thể truy cập vào Surface để vẽ bản đồ trên các mẫu liên quan.

Sau đó, ứng dụng có thể truy cập đối tượng SurfaceContainer bằng cách đặt một thực thể SurfaceCallback vào dịch vụ cho ô tô AppManager:

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

SurfaceCallback cung cấp lệnh gọi lại khi SurfaceContainer có sẵn cùng với các lệnh gọi lại khác trong trường hợp các thuộc tính của Surface thay đổi.

Để có quyền truy cập vào nền tảng, ứng dụng của bạn cần khai báo quyền androidx.car.app.ACCESS_SURFACE trong tệp AndroidManifest.xml:

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

Khu vực nhìn thấy của bản đồ

Máy chủ có thể vẽ các thành phần trên giao diện người dùng cho các mẫu trên bản đồ. Máy chủ sẽ thông báo về khu vực được đảm bảo không bị che khuất và người dùng có thể nhìn thấy toàn bộ bằng cách gọi phương thức SurfaceCallback.onVisibleAreaChanged. Ngoài ra, để giảm thiểu số lần thay đổi, máy chủ sẽ gọi phương thức SurfaceCallback.onStableAreaChanged có hình chữ nhật nhỏ nhất luôn hiển thị dựa trên mẫu hiện tại.

Ví dụ: Khi một ứng dụng chỉ đường dùng NavigationTemplate với một chuỗi hành động ở trên cùng, chuỗi hành động đó có thể tự ẩn khi người dùng không tương tác với màn hình trong một thời gian để có thêm không gian trên bản đồ. Trong trường hợp này, hệ thống sẽ gọi lại onStableAreaChanged và onVisibleAreaChanged có cùng hình chữ nhật. Khi chuỗi hành động bị ẩn, chỉ onVisibleAreaChanged được gọi với khu vực lớn hơn. Nếu người dùng tương tác với màn hình, thì một lần nữa, chỉ onVisibleAreaChanged được gọi với hình chữ nhật đầu tiên.

Hỗ trợ chế độ tối

Các ứng dụng chỉ đường phải vẽ lại bản đồ của ứng dụng vào thực thể Surface có màu tối thích hợp khi máy chủ lưu trữ xác định các điều kiện đảm bảo cho thực thể, như đã mô tả trong phần Chất lượng ứng dụng Android dành cho ô tô.

Để quyết định xem có vẽ bản đồ màu tối hay không, bạn có thể sử dụng phương thức CarContext.isDarkMode. Bất cứ khi nào trạng thái chế độ tối thay đổi, bạn sẽ nhận được một lệnh gọi tới Session.onCarConfigurationChanged.

Truyền siêu dữ liệu chỉ đường

Các ứng dụng chỉ đường phải truyền thêm siêu dữ liệu chỉ đường bằng máy chủ lưu trữ. Máy chủ lưu trữ sẽ sử dụng thông tin này để cung cấp thông tin cho đầu phát trung tâm của xe và để ngăn các ứng dụng chỉ đường xung đột về những tài nguyên dùng chung.

Bạn có thể cung cấp siêu dữ liệu chỉ đường thông qua dịch vụ ô tô NavigationManager truy cập được từ CarContext:

val navigationManager = carContext.getCarService(NavigationManager::class.java)

NavigationManager navigationManager = carContext.getCarService(NavigationManager.class);

Bắt đầu, kết thúc và ngừng quy trình chỉ đường

Để quản lý nhiều ứng dụng chỉ đường, thông báo xác định tuyến đường và dữ liệu của cụm đồng hồ trên xe, máy chủ lưu trữ cần biết trạng thái chỉ đường hiện tại. Khi người dùng bắt đầu quy trình chỉ đường, hãy gọi NavigationManager.navigationStarted. Tương tự, khi quá trình chỉ đường kết thúc, chẳng hạn như khi người dùng tới điểm đến hoặc người dùng huỷ quá trình chỉ đường, hãy gọi NavigationManager.navigationEnded.

Chỉ gọi NavigationManager.navigationEnded khi người dùng hoàn tất quá trình chỉ đường. Chẳng hạn như nếu bạn cần tính toán lại tuyến đường khi đang ở giữa chuyến đi, hãy sử dụng Trip.Builder.setLoading(true).

Đôi khi, máy chủ lưu trữ cần một ứng dụng để ngừng quy trình chỉ đường và sẽ gọi onStopNavigation trong đối tượng NavigationManagerCallback do ứng dụng của bạn cung cấp thông qua NavigationManager.setNavigationManagerCallback. Sau đó, ứng dụng phải ngừng đưa ra thông tin về ngã rẽ tiếp theo trên màn hình cụm đồng hồ, thông báo chỉ đường và hướng dẫn bằng giọng nói.

Cập nhật thông tin chuyến đi

Trong khi chỉ đường, hãy gọi NavigationManager.updateTrip. Thông tin được cung cấp trong lệnh gọi này có thể được dùng trên màn hình hiển thị ngang tầm mắt và màn hình cụm đồng hồ của xe. Tuỳ thuộc vào loại xe đang dùng, người dùng có thể không thấy một số thông tin. Ví dụ: Đầu phát trung tâm trên máy tính (DHU) cho biết Step đã được thêm vào Trip, nhưng không hiển thị thông tin Destination.

Vẽ lên màn hình cụm đồng hồ

Để có trải nghiệm người dùng sống động nhất, bạn có thể không chỉ muốn hiển thị siêu dữ liệu cơ bản trên màn hình cụm đồng hồ của xe. Kể từ Car App API (API Ứng dụng dành cho ô tô) cấp độ 6, các ứng dụng chỉ đường có thể hiển thị nội dung của chính các ứng dụng đó ngay trên màn hình cụm đồng hồ (trong các xe được hỗ trợ), với những điểm hạn chế sau:

• API màn hình cụm đồng hồ không hỗ trợ chế độ kiểm soát đầu vào
• Màn hình cụm đồng hồ chỉ hiển thị được các ô bản đồ. Bạn có thể tuỳ ý hiển thị một thành phần chỉ dẫn tuyến đường đang hoạt động trên các ô này.
• API màn hình cụm đồng hồ chỉ hỗ trợ việc sử dụng NavigationTemplate
  • Không giống như màn hình chính, màn hình cụm đồng hồ có thể không hiển thị nhất quán tất cả các phần tử trên giao diện người dùng NavigationTemplate, chẳng hạn như hướng dẫn từng chặng, thẻ Giờ đến dự kiến và các thao tác. Ô bản đồ là phần tử duy nhất hiển thị nhất quán trên giao diện người dùng.

Khai báo khả năng hỗ trợ cụm

Để ứng dụng lưu trữ biết ứng dụng của bạn hỗ trợ tính năng hiển thị trên màn hình cụm đồng hồ, bạn phải thêm phần tử androidx.car.app.category.FEATURE_CLUSTER <category> vào <intent-filter> của CarAppService như minh hoạ trong đoạn mã sau:

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

Quản lý vòng đời và trạng thái

Kể từ API cấp độ 6, luồng vòng đời của ứng dụng dành cho ô tô vẫn giữ nguyên. Tuy nhiên, hiện CarAppService::onCreateSession có một tham số thuộc loại SessionInfo cung cấp thông tin bổ sung về Session đang được tạo (cụ thể là loại màn hình và tập hợp các mẫu được hỗ trợ).

Các ứng dụng có thể dùng cùng một lớp Session để xử lý cả màn hình cụm đồng hồ và màn hình chính hoặc tạo Sessions dành riêng cho mỗi màn hình để tuỳ chỉnh hành vi trên từng màn hình (như minh hoạ trong đoạn mã sau).

override fun onCreateSession(sessionInfo: SessionInfo): Session {
  return if (sessionInfo.displayType == SessionInfo.DISPLAY_TYPE_CLUSTER) {
    ClusterSession()
  } else {
    MainDisplaySession()
  }
}

@Override
@NonNull
public Session onCreateSession(@NonNull SessionInfo sessionInfo) {
  if (sessionInfo.getDisplayType() == SessionInfo.DISPLAY_TYPE_CLUSTER) {
    return new ClusterSession();
  } else {
    return new MainDisplaySession();
  }
}

Không có gì đảm bảo về thời điểm hoặc liệu màn hình cụm đồng hồ có được cung cấp hay không. Đồng thời, Session của cụm đồng hồ cũng có thể là Session duy nhất (ví dụ: người dùng đã hoán đổi màn hình chính thành một ứng dụng khác trong khi ứng dụng của bạn đang tích cực chỉ đường). Thoả thuận "tiêu chuẩn" quy định rằng ứng dụng chỉ kiểm soát màn hình cụm đồng hồ sau khi NavigationManager::navigationStarted được gọi. Tuy nhiên, có thể có trường hợp ứng dụng được cung cấp màn hình cụm đồng hồ trong khi không có hoạt động chỉ đường nào đang diễn ra hoặc không bao giờ được cung cấp màn hình cụm đồng hồ. Ứng dụng có thể xử lý những trường hợp này bằng cách hiển thị trạng thái rảnh của các ô bản đồ trong ứng dụng.

Ứng dụng lưu trữ sẽ tạo lệnh gọi binder riêng biệt và các thực thể CarContext cho mỗi Session. Điều này nghĩa là khi sử dụng các phương thức như ScreenManager::push hoặc Screen::invalidate, thì chỉ Session mà các phương thức này được gọi từ đó sẽ bị ảnh hưởng. Ứng dụng nên tạo kênh liên lạc riêng giữa những thực thể này nếu cần giao tiếp giữa các Session (ví dụ: bằng cách sử dụng thông báo – một singleton được chia sẻ – hoặc một kênh nào đó khác).

Kiểm thử khả năng hỗ trợ cụm

Bạn có thể kiểm thử hoạt động triển khai trên cả Android Auto và Android Automotive OS. Đối với Android Auto, bạn thực hiện việc này bằng cách định cấu hình Đầu phát trung tâm trên máy tính để mô phỏng màn hình cụm đồng hồ phụ. Đối với Android Automotive OS, hình ảnh hệ thống chung của API cấp độ 30 trở lên mô phỏng màn hình cụm đồng hồ.

Tuỳ chỉnh TravelEstimate bằng văn bản hoặc biểu tượng

Để tuỳ chỉnh số liệu ước tính về hành trình bằng văn bản, biểu tượng hoặc cả hai, hãy dùng các phương thức setTripIcon hoặc setTripText của lớp TravelEstimate.Builder. NavigationTemplate sử dụng TravelEstimate để tuỳ ý đặt văn bản và biểu tượng cạnh nhau hoặc thay cho thời gian đến dự kiến, thời gian còn lại và quãng đường còn lại.

Đoạn mã sau sử dụng setTripIcon và setTripText để tuỳ chỉnh số liệu ước tính về hành trình:

TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .build()

new TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .build();

Cung cấp thông báo theo từng chặng

Đưa ra hướng dẫn chỉ đường theo từng chặng (TBT) bằng cách sử dụng thông báo chỉ đường được cập nhật thường xuyên. Để được coi là thông báo chỉ đường trên màn hình ô tô, trình tạo của thông báo phải làm như sau:

1. Đánh dấu thông báo là đang diễn ra bằng phương thức NotificationCompat.Builder.setOngoing.
2. Đặt danh mục của thông báo thành Notification.CATEGORY_NAVIGATION.
3. Mở rộng thông báo bằng CarAppExtender.

Thông báo chỉ đường sẽ hiển thị trong tiện ích dải điều hướng ở cuối màn hình ô tô. Nếu bạn đặt mức độ quan trọng của thông báo thành IMPORTANCE_HIGH, thì thông báo đó cũng sẽ hiển thị dưới dạng thông báo quan trọng (HUN). Nếu bạn không đặt mức độ quan trọng bằng phương thức CarAppExtender.Builder.setImportance, thì mức độ quan trọng của kênh thông báo sẽ được sử dụng.

Ứng dụng có thể đặt PendingIntent trong CarAppExtender sẽ được gửi đến ứng dụng khi người dùng nhấn vào HUN hoặc tiện ích dải điều hướng.

Nếu NotificationCompat.Builder.setOnlyAlertOnce được gọi với giá trị true, thì thông báo có mức độ quan trọng cao sẽ chỉ cảnh báo một lần trong HUN.

Đoạn mã sau đây cho biết cách tạo thông báo chỉ đường:

NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    ...
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            ...
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    Intent(ACTION_OPEN_APP).setComponent(
                        ComponentName(context, MyNotificationReceiver::class.java)),
                        0))
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build())
    .build()

new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    ...
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        new CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            ...
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    new Intent(ACTION_OPEN_APP).setComponent(
                        new ComponentName(context, MyNotificationReceiver.class)),
                        0))
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build())
    .build();

Thường xuyên cập nhật thông báo TBT khi có thay đổi về quãng đường. Theo đó, tiện ích dải điều hướng sẽ cập nhật và chỉ hiển thị thông báo dưới dạng HUN. Bạn có thể kiểm soát hành vi của HUN bằng cách đặt mức độ quan trọng của thông báo bằng phương thức CarAppExtender.Builder.setImportance. Việc đặt mức độ quan trọng thành IMPORTANCE_HIGH sẽ hiển thị HUN. Khi bạn đặt giá trị này thành bất kỳ giá trị nào khác, chỉ tiện ích dải điều hướng cập nhật.

Làm mới nội dung PlaceListNavigationTemplate

Bạn có thể cho phép người lái xe làm mới nội dung bằng cách nhấn một nút trong khi duyệt qua danh sách các địa điểm được tạo bằng PlaceListNavigationTemplate. Triển khai phương thức onContentRefreshRequested của giao diện OnContentRefreshListener và sử dụng PlaceListNavigationTemplate.Builder.setOnContentRefreshListener nhằm thiết lập trình nghe trên mẫu để bật tính năng làm mới danh sách.

Đoạn mã sau đây cho biết cách thiết lập trình nghe trên mẫu:

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

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

Nút làm mới chỉ xuất hiện trong tiêu đề của PlaceListNavigationTemplate nếu trình nghe có một giá trị.

Khi người dùng nhấp vào nút làm mới, phương thức onContentRefreshRequested của quá trình triển khai OnContentRefreshListener sẽ được gọi. Trong onContentRefreshRequested, hãy gọi phương thức Screen.invalidate. Sau đó, máy chủ lưu trữ sẽ gọi lại phương thức Screen.onGetTemplate của ứng dụng để truy xuất mẫu có nội dung được làm mới. Xem phần Làm mới nội dung mẫu để biết thêm thông tin về cách làm mới mẫu. Chỉ cần mẫu tiếp theo mà onGetTemplate trả về thuộc cùng một loại, thì mẫu đó sẽ được tính là một lần làm mới và không được tính vào hạn mức mẫu.

Cung cấp hướng dẫn bằng âm thanh

Để phát hướng dẫn chỉ đường trên loa ô tô, ứng dụng của bạn phải yêu cầu quyền phát âm thanh. Trong AudioFocusRequest của bạn, hãy đặt mức sử dụng là AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE. Ngoài ra, hãy đặt mức lấy quyền phát là AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.

Mô phỏng hoạt động chỉ đường

Để xác minh chức năng chỉ đường của ứng dụng khi bạn gửi ứng dụng đến Cửa hàng Google Play, ứng dụng của bạn phải triển khai lệnh gọi lại NavigationManagerCallback.onAutoDriveEnabled. Khi lệnh gọi lại này được gọi, ứng dụng của bạn sẽ mô phỏng chức năng chỉ đường tới điểm đến đã chọn khi người dùng bắt đầu quy trình chỉ đường. Ứng dụng của bạn có thể thoát khỏi chế độ này bất cứ khi nào vòng đời của Session hiện tại đạt đến trạng thái Lifecycle.Event.ON_DESTROY.

Bạn có thể kiểm thử để đảm bảo việc triển khai onAutoDriveEnabled sẽ được gọi bằng cách thực thi lệnh sau từ một dòng lệnh:

adb shell dumpsys activity service CAR_APP_SERVICE_NAME AUTO_DRIVE

Lệnh này được minh hoạ trong ví dụ sau:

adb shell dumpsys activity service androidx.car.app.samples.navigation.car.NavigationCarAppService AUTO_DRIVE

Ứng dụng chỉ đường mặc định trên ô tô

Trong Android Auto, ứng dụng chỉ đường mặc định trên ô tô tương ứng với ứng dụng chỉ đường mà người dùng chạy gần đây nhất. Ứng dụng mặc định nhận được ý định chỉ đường khi người dùng gọi lệnh chỉ đường thông qua Trợ lý hoặc khi một ứng dụng khác gửi ý định bắt đầu quy trình chỉ đường.

Cho phép người dùng tương tác với bản đồ của bạn

Bạn có thể hỗ trợ người dùng tương tác với bản đồ, chẳng hạn như cho phép người dùng xem các phần khác nhau của bản đồ bằng cách thu phóng và kéo bản đồ. Mỗi mẫu có một yêu cầu tối thiểu khác nhau về cấp độ API của ứng dụng ô tô. Hãy xem bảng sau đây để biết cấp độ tối thiểu của mẫu mà bạn muốn triển khai.

Phương thức SurfaceCallback

Giao diện SurfaceCallback có nhiều phương thức gọi lại giúp bạn có thể thêm khả năng tương tác vào bản đồ được tạo bằng mẫu NavigationTemplate, PlaceListNavigationTemplate, RoutePreviewNavigationTemplate hoặc MapTemplate: onClick, onScroll, onScale và onFling. Hãy xem bảng sau đây để biết mối quan hệ giữa các lệnh gọi lại này với hoạt động tương tác của người dùng.

Chuỗi hành động trên bản đồ

Các mẫu NavigationTemplate, PlaceListNavigationTemplate, RoutePreviewNavigationTemplate và MapTemplate có thể có một chuỗi hành động trên bản đồ cho các thao tác liên quan đến bản đồ, chẳng hạn như phóng to và thu nhỏ, căn giữa lại, hiển thị la bàn hoặc các thao tác khác mà bạn chọn hiển thị. Chuỗi hành động trên bản đồ có thể có tối đa 4 nút chỉ hiển thị bằng biểu tượng có thể được làm mới mà không ảnh hưởng đến chiều sâu của nhiệm vụ. Chuỗi này ẩn khi ở trạng thái rảnh và xuất hiện lại ở trạng thái hoạt động.

Để nhận được lệnh gọi lại về tính tương tác trên bản đồ, bạn phải thêm nút Action.PAN trong chuỗi hành động trên bản đồ. Khi người dùng nhấn nút kéo, máy chủ lưu trữ sẽ chuyển sang chế độ kéo, như mô tả trong phần sau đây.

Nếu bỏ qua nút Action.PAN trong chuỗi hành động trên bản đồ, ứng dụng của bạn sẽ không nhận được hoạt động đầu vào của người dùng từ các phương thức SurfaceCallback và máy chủ lưu trữ sẽ thoát khỏi mọi chế độ kéo đã kích hoạt trước đó.

Trên màn hình cảm ứng, nút kéo không hiển thị.

Chế độ kéo

Ở chế độ kéo, máy chủ lưu trữ mẫu sẽ chuyển hoạt động đầu vào của người dùng từ các thiết bị đầu vào không cảm ứng (chẳng hạn như bộ điều khiển xoay và bàn di chuột) sang các phương thức SurfaceCallback thích hợp. Phản hồi hành động của người dùng để chuyển sang hoặc thoát chế độ kéo bằng phương thức setPanModeListener trong NavigationTemplate.Builder. Máy chủ lưu trữ có thể ẩn các thành phần khác trên giao diện người dùng trong mẫu khi người dùng đang ở chế độ kéo.

Khu vực ổn định

Khu vực ổn định sẽ cập nhật giữa trạng thái rảnh và trạng thái hoạt động. Dựa vào kích thước của khu vực ổn định, ứng dụng của bạn phải xác định xem có nên vẽ các thông tin liên quan đến việc lái xe như tốc độ, giới hạn tốc độ hoặc cảnh báo giao thông đường bộ hay không. Như vậy thì thông tin quan trọng trên bản đồ mới không bị chuỗi hành động trên bản đồ che khuất.

Hiện cảnh báo chỉ đường theo ngữ cảnh

Alert hiển thị thông tin quan trọng cho người lái với các thao tác tuỳ chọn mà không cần rời khỏi ngữ cảnh của màn hình chỉ đường. Nhằm mang lại trải nghiệm tốt nhất cho người lái, Alert sẽ hoạt động trong NavigationTemplate để tránh tình trạng chặn tuyến đường điều hướng và để giảm thiểu sự phân tâm của người lái xe.

Alert chỉ có sẵn trong NavigationTemplate. Để thông báo cho người dùng bên ngoài NavigationTemplate, hãy cân nhắc sử dụng thông báo quan trọng (HUN) như trình bày trong phần Thông báo hiển thị.

Ví dụ: bạn có thể sử dụng Alert để:

• Thông báo cho người lái về một bản cập nhật có liên quan đến thành phần điều hướng hiện tại, chẳng hạn như một thay đổi về tình trạng giao thông.
• Yêu cầu người lái cung cấp thông tin cập nhật liên quan đến thành phần điều hướng hiện tại, chẳng hạn như sự tồn tại của máy bắn tốc độ.
• Đề xuất một nhiệm vụ sắp tới và hỏi xem liệu người lái xe có chấp nhận hay không, chẳng hạn như người lái có sẵn sàng đón một người nào đó trên tuyến đường của họ hay không.

Ở dạng cơ bản, Alert bao gồm một tiêu đề và thời gian tồn tại của Alert. Thời gian tồn tại được biểu thị bằng một thanh tiến trình. Nếu muốn, bạn có thể thêm tiêu đề phụ, biểu tượng và tối đa 2 đối tượng Action.

Sau khi hiển thị, Alert sẽ không chuyển sang mẫu khác nếu hoạt động tương tác với người lái xe dẫn đến việc rời khỏi NavigationTemplate. Mẫu vẫn ở trong NavigationTemplate ban đầu cho đến khi Alert hết thời gian, người dùng thực hiện hành động hoặc ứng dụng đóng Alert.

Tạo cảnh báo

Hãy dùng Alert.Builder để tạo một thực thể Alert:

Alert.Builder(
        /*alertId*/ 1,
        /*title*/ CarText.create("Hello"),
        /*durationMillis*/ 5000
    )
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create(...))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(...)
    .build()

new Alert.Builder(
        /*alertId*/ 1,
        /*title*/ CarText.create("Hello"),
        /*durationMillis*/ 5000
    )
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create(...))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(...)
    .build();

Nếu bạn muốn nghe về việc huỷ hoặc đóng Alert, hãy triển khai giao diện AlertCallback. Các đường dẫn lệnh gọi AlertCallback bao gồm:

• Nếu Alert hết thời gian chờ, máy chủ lưu trữ sẽ gọi phương thức AlertCallback.onCancel với giá trị AlertCallback.REASON_TIMEOUT. Sau đó, máy chủ lưu trữ gọi phương thức AlertCallback.onDismiss.

• Nếu người lái xe nhấp vào một trong các nút hành động, thì máy chủ lưu trữ sẽ gọi Action.OnClickListener rồi gọi AlertCallback.onDismiss.

• Nếu Alert không được hỗ trợ, máy chủ lưu trữ sẽ gọi AlertCallback.onCancel bằng giá trị AlertCallback.REASON_NOT_SUPPORTED. Máy chủ lưu trữ không gọi AlertCallback.onDismiss vì Alert không xuất hiện.

Định cấu hình thời lượng cảnh báo

Chọn thời lượng Alert phù hợp với nhu cầu của ứng dụng. Thời lượng đề xuất cho thành phần điều hướng Alert là 10 giây. Hãy tham khảo bài viết Cảnh báo điều hướng để biết thêm thông tin.

Hiển thị cảnh báo

Để hiển thị Alert, hãy gọi phương thức AppManager.showAlert có sẵn thông qua CarContext của ứng dụng.

// Show an alert
carContext.getCarService(AppManager.class).showAlert(alert)

• Việc gọi showAlert bằng Alert có alertId giống với mã nhận dạng của Alert hiện có trên màn hình sẽ không có tác dụng gì. Alert không cập nhật. Để cập nhật Alert, bạn phải tạo lại hoạt động đó bằng alertId mới.
• Việc gọi showAlert bằng một Alert có alertId khác với Alert hiện có trên màn hình sẽ đóng Alert hiện được hiển thị.

Đóng cảnh báo

Mặc dù Alert tự động đóng do hết thời gian chờ hoặc do hoạt động tương tác của người lái, nhưng bạn cũng có thể đóng Alert, khi thông tin của cảnh báo đã lỗi thời. Để đóng Alert, hãy gọi phương thức dismissAlert bằng alertId của Alert.

// Dismiss the same alert
carContext.getCarService(AppManager.class).dismissAlert(alert.getId())

Việc gọi dismissAlert bằng alertId không khớp với Alert đang hiển thị sẽ không có tác dụng gì. Hệ thống sẽ không gửi một trường hợp ngoại lệ.