使用車輛專用 Android App Library

車輛專用 Android App Library 可讓您將導航、搜尋點和物聯網 (IOT) 應用程式帶入車內。為此，我們提供一套範本，以符合駕駛人分心等級的標準，並妥善處理各種車輛螢幕因素和輸入模式等細節。

本指南將概略說明程式庫的主要功能與概念，並逐步引導您設定基本應用程式。

程式碼研究室

瞭解 Car App Library 基礎知識

arrow_forward

事前準備

1. 查看有關車輛應用程式程式庫的「行車設計」頁面。
   • 導航應用程式和其他駕駛相關應用程式類別總覽
   • 「使用範本建構應用程式」總覽
   • 包含範本和範本元件的建構模塊
   • 示範常見使用者體驗模式的範例流程
   • 範本應用程式規定
2. 請參閱下一節的重要詞彙與概念。
3. 熟悉 Android Auto 系統 UI 和 Android Automotive OS 設計。
4. 查看版本資訊。
5. 查看範例。

重要詞彙與概念

模型和範本

使用者介面是以模型物件圖表表示，模型物件能以不同方式排列，一如其所屬範本的允許。範本是模型的子集，可以在這些圖表中做為根層級運作。模型包含要以文字和圖片形式向使用者顯示的資訊，以及可設定這類資訊外觀外觀的屬性 (例如文字顏色或圖片大小)。主機會將模型轉換為符合駕駛人分心標準的檢視畫面，並妥善處理各種細節，例如各種車輛螢幕因素和輸入模式。

主機

主機為後端元件，會實作程式庫 API 提供的功能，讓應用程式在車上執行。主機的職責包括探索應用程式及管理其生命週期，以及將模型轉換為檢視畫面，以及通知應用程式使用者互動通知。在行動裝置上，這個主機是由 Android Auto 實作。在 Android Automotive OS 中，這個主機會安裝為系統應用程式。

範本限制

不同的範本會強制限制模型的內容。例如，清單範本對使用者可呈現的項目數量設有限制。範本在連結後會形成任務流程，也設有限制。例如，應用程式最多只能將五個範本推送至畫面堆疊。詳情請參閱「範本限制」一節。

Screen

Screen 是程式庫提供的類別，由應用程式實作，用於管理提供給使用者的使用者介面。Screen 具有生命週期，並提供機制，讓應用程式在畫面可見時傳送要顯示的範本。系統也可以推送及從 Screen 堆疊推送及彈出 Screen 執行個體，確保這些執行個體符合範本流程限制。

CarAppService

CarAppService 是應用程式必須實作和匯出的抽象 Service 類別，主機才能尋找及管理。應用程式的 CarAppService 負責使用 createHostValidator 驗證主機連線是否可信任，然後使用 onCreateSession 為每個連線提供 Session 執行個體。

Session

Session 是應用程式必須使用 CarAppService.onCreateSession 實作及傳回的抽象類別。這可做為在車輛螢幕上顯示資訊的進入點。其中包含生命週期功能，可在車輛螢幕上通知應用程式目前的狀態，例如應用程式處於顯示或隱藏狀態。

當 Session 啟動 (例如應用程式首次啟動) 時，主機會透過 onCreateScreen 方法要求顯示初始 Screen 來顯示內容。

安裝 Car App Library

請參閱 Jetpack 程式庫版本頁面，瞭解如何將程式庫新增至應用程式。

設定應用程式的資訊清單檔案

建立車用應用程式前，請先按照以下步驟設定應用程式的資訊清單檔案。

宣告您的 CarAppService

主機透過 CarAppService 實作連線至應用程式。您在資訊清單中宣告此服務，讓主機探索並連線至您的應用程式。

您也需要在應用程式意圖篩選器的 <category> 元素中宣告應用程式類別。如要瞭解此元素允許的值，請參閱支援的應用程式類別清單。

下列程式碼片段說明如何為資訊清單中的搜尋點應用程式宣告車輛應用程式服務：

<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>

支援的應用程式類別

如要宣告應用程式的類別，請在宣告 CarAppService 時 (如上一節所述)，在意圖篩選器中加入下列一或多個類別值：

• androidx.car.app.category.NAVIGATION：提供即時路線導航路線的應用程式。如要進一步瞭解這個類別的說明文件，請參閱「建構車輛專用導航應用程式」。
• androidx.car.app.category.POI：提供與尋找搜尋點相關的功能，例如停車位、充電站和加油站。如要進一步瞭解這個類別的說明文件，請參閱「建構車輛專用搜尋點應用程式」。
• androidx.car.app.category.IOT：可讓使用者在車內，在已連結的裝置上進行相關動作的應用程式。如要進一步瞭解這個類別的說明文件，請參閱「建構車用物聯網應用程式」。

請參閱「車用 Android 應用程式品質指南」，進一步瞭解各類別的應用程式及其所屬標準。

指定應用程式名稱和圖示

您必須指定應用程式名稱和圖示，讓主機可在系統 UI 中代表您的應用程式。

您可以使用 CarAppService 的 label 和 icon 屬性，指定用於代表應用程式的應用程式名稱和圖示：

...
<service
   android:name=".MyCarAppService"
   android:exported="true"
   android:label="@string/my_app_name"
   android:icon="@drawable/my_app_icon">
   ...
</service>
...

如未在 <service> 元素中宣告標籤或圖示，主機就會改回使用 <application> 元素指定的值。

設定自訂主題

如要為車輛應用程式設定自訂主題，請在資訊清單檔案中加入 <meta-data> 元素，如下所示：

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

然後宣告樣式資源，為自訂車輛應用程式主題設定下列屬性：

<resources>
  <style name="MyCarAppTheme">
    <item name="carColorPrimary">@layout/my_primary_car_color</item>
    <item name="carColorPrimaryDark">@layout/my_primary_dark_car_color</item>
    <item name="carColorSecondary">@layout/my_secondary_car_color</item>
    <item name="carColorSecondaryDark">@layout/my_secondary_dark_car_color</item>
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

車輛應用程式 API 級別

Car App Library 會定義自己的 API 級別，讓您瞭解車輛的範本主機支援哪些程式庫功能。如要擷取主機支援的最高 Car App API 級別，請使用 getCarAppApiLevel() 方法。

在 AndroidManifest.xml 檔案中，宣告應用程式支援的最低 Car App API 級別：

<manifest ...>
    <application ...>
        <meta-data
            android:name="androidx.car.app.minCarApiLevel"
            android:value="1"/>
    </application>
</manifest>

請參閱 RequiresCarApi 註解的說明文件，進一步瞭解如何維持回溯相容性，以及宣告使用功能所需的最低 API 級別。如要瞭解使用 Car App Library 特定功能需要哪個 API 級別，請參閱 CarAppApiLevels 的參考說明文件。

建立 CarAppService 和工作階段

您的應用程式需要擴充 CarAppService 類別並實作 onCreateSession 方法，以便傳回對應至目前主機連線的 Session 例項：

class HelloWorldService : CarAppService() {
    ...
    override fun onCreateSession(): Session {
        return HelloWorldSession()
    }
    ...
}

public final class HelloWorldService extends CarAppService {
    ...
    @Override
    @NonNull
    public Session onCreateSession() {
        return new HelloWorldSession();
    }
    ...
}

Session 例項負責傳回 Screen 例項，以使用應用程式首次啟動：

class HelloWorldSession : Session() {
    ...
    override fun onCreateScreen(intent: Intent): Screen {
        return HelloWorldScreen(carContext)
    }
    ...
}

public final class HelloWorldSession extends Session {
    ...
    @Override
    @NonNull
    public Screen onCreateScreen(@NonNull Intent intent) {
        return new HelloWorldScreen(getCarContext());
    }
    ...
}

如要處理車輛應用程式必須從非應用程式主畫面或到達畫面開始的情境 (例如處理深層連結)，您可以使用 ScreenManager.push 預先啟動畫面返回堆疊，然後再從 onCreateScreen 傳回。預先播種功能可讓使用者從應用程式顯示的第一個畫面返回先前的畫面。

建立開始畫面

您可以定義擴充 Screen 類別的類別，並實作其 onGetTemplate 方法，藉此建立應用程式顯示的畫面。此項目會傳回 Template 例項，代表要在車輛螢幕上顯示的 UI 狀態。

下列程式碼片段說明如何宣告使用 PaneTemplate 範本的 Screen，以顯示簡單的「Hello World!」字串：

class HelloWorldScreen(carContext: CarContext) : Screen(carContext) {
    override fun onGetTemplate(): Template {
        val row = Row.Builder().setTitle("Hello world!").build()
        val pane = Pane.Builder().addRow(row).build()
        return PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build()
    }
}

public class HelloWorldScreen extends Screen {
    @NonNull
    @Override
    public Template onGetTemplate() {
        Row row = new Row.Builder().setTitle("Hello world!").build();
        Pane pane = new Pane.Builder().addRow(row).build();
        return new PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build();
    }
}

CarContext 類別

CarContext 類別是 ContextWrapper 子類別，可供 Session 和 Screen 執行個體存取。可讓您存取車輛服務，例如用於管理畫面堆疊的 ScreenManager、一般應用程式相關功能的 AppManager (例如存取繪製地圖的 Surface 物件)，以及透過即時導航導航應用程式使用NavigationManager與導航事件通訊的中繼資料相關。

如需導航應用程式可用的完整程式庫功能清單，請參閱「存取導覽範本」。

CarContext 也提供其他功能，例如可使用車輛螢幕上的設定載入可繪製資源、使用意圖在車上啟動應用程式，以及指出應用程式是否應以深色主題顯示地圖。

實作畫面導覽

應用程式通常會顯示多個不同的畫面，每一個畫面可能都使用不同的範本，讓使用者能夠在與畫面顯示的介面互動時瀏覽。

ScreenManager 類別提供螢幕堆疊，當使用者在車輛螢幕上選取返回按鈕，或使用部分車輛提供的硬體返回按鈕時，畫面就會自動彈出。

下列程式碼片段說明如何在訊息範本中新增返回動作，以及在使用者選取時推送新畫面的動作：

val template = MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener { screenManager.push(NextScreen(carContext)) }
            .build())
    .build()

MessageTemplate template = new MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        new Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener(
                () -> getScreenManager().push(new NextScreen(getCarContext())))
            .build())
    .build();

Action.BACK 物件是自動叫用 ScreenManager.pop 的標準 Action。您可以使用 CarContext 提供的 OnBackPressedDispatcher 執行個體覆寫這項行為。

為確保應用程式在行車期間安全無虞，畫面堆疊的深度可達五個畫面。詳情請參閱「範本限制」一節。

重新整理範本內容

應用程式可以呼叫 Screen.invalidate 方法，要求要撤銷 Screen 的內容。主機隨後會呼叫應用程式的 Screen.onGetTemplate 方法，使用新內容擷取範本。

重新整理 Screen 時，請務必瞭解範本中可更新的特定內容，這樣主機就不會將新範本計入範本配額。詳情請參閱「範本限制」一節。

建議您建立畫面結構，讓 Screen 透過實作 onGetTemplate 傳回的範本類型能夠進行一對一的對應。

繪製地圖

使用以下範本的導航和搜尋點 (POI) 應用程式可以透過存取 Surface 繪製地圖：

宣告表面權限

除了應用程式使用範本所需的權限外，應用程式也必須在 AndroidManifest.xml 檔案中宣告 androidx.car.app.ACCESS_SURFACE 權限，才能存取介面：

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

存取介面

如要存取主機提供的 Surface，您必須實作 SurfaceCallback，並將實作項目提供給 AppManager 車輛服務。目前的 Surface 會傳遞至 onSurfaceAvailable() 和 onSurfaceDestroyed() 回呼的 SurfaceContainer 參數中的 SurfaceCallback。

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

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

瞭解平面的可見區域

主機可在地圖上層為範本繪製使用者介面元素。只要呼叫 SurfaceCallback.onVisibleAreaChanged 方法，主機即可與使用者絕對可見的介面區域通訊。此外，為了盡量減少變更，主機會透過最小矩形呼叫 SurfaceCallback.onStableAreaChanged 方法，這種矩形一律會根據目前的範本顯示。

舉例來說，如果導航應用程式使用頂端有動作列的 NavigationTemplate，在使用者有一段時間未與畫面互動時，系統就會隱藏動作列，為地圖提供更多空間。在這種情況下，系統會使用相同矩形來回呼 onStableAreaChanged 和 onVisibleAreaChanged。隱藏動作列時，系統只會使用較大的區域呼叫 onVisibleAreaChanged。如果使用者與畫面互動，系統只會使用第一個矩形呼叫 onVisibleAreaChanged。

支援深色主題

當主機判定條件可提供擔保時，應用程式必須使用適當的深色在 Surface 例項上重新繪製地圖，如「車用 Android 應用程式品質指南」所述。

如要判斷是否應繪製深色地圖，可以使用 CarContext.isDarkMode 方法。只要深色主題狀態變更，您就會收到 Session.onCarConfigurationChanged 呼叫。

允許使用者與地圖互動

使用以下範本時，您還可以新增支援功能，讓使用者與繪製的地圖互動，例如縮放及平移地圖，查看地圖的不同部分。

實作互動回呼

SurfaceCallback 介面提供多種回呼方法，您可以實作如上一節以範本建構的地圖，新增互動功能：

新增地圖動作區域

這些範本可以包含地圖操作列，用於地圖相關動作，例如縮放和縮小、重新置中、顯示指南針，以及您選擇顯示的其他動作。地圖動作列最多可有四個純圖示按鈕，這些按鈕可重新整理，不會影響工作深度。處於閒置狀態時，這個動作列會隱藏，待回到啟用狀態才會再顯示。

如要接收地圖互動回呼，必須在地圖動作列中新增 Action.PAN 按鈕。使用者按下平移按鈕時，主機會進入平移模式，如下一節所述。

如果應用程式忽略地圖動作列中的 Action.PAN 的按鈕，就無法從 SurfaceCallback 方法收到使用者輸入內容，而且主機會結束先前啟用的平移模式。

如果是觸控螢幕，畫面上不會顯示平移按鈕。

瞭解平移模式

在平移模式下，使用者透過非觸控輸入裝置 (例如旋轉控制器和觸控板) 輸入的內容，會由範本主機轉譯成適當的 SurfaceCallback 方法。使用 NavigationTemplate.Builder 中的 setPanModeListener 方法，可在使用者進入或結束平移模式時做出反應。使用者處於平移模式時，主機可隱藏範本中的其他 UI 元件。

與使用者互動

您的應用程式可以透過與行動應用程式類似的模式與使用者互動。

處理使用者輸入內容

應用程式可將適當的事件監聽器傳遞至支援這些事件監聽器的模型，藉此回應使用者輸入內容。下列程式碼片段說明如何建立 Action 模型，以設定 OnClickListener 來呼叫應用程式程式碼所定義的方法：

val action = Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(::onClickNavigate)
    .build()

Action action = new Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(this::onClickNavigate)
    .build();

接著，onClickNavigate 方法即可使用 CarContext.startCarApp 方法啟動預設車輛導航應用程式：

private fun onClickNavigate() {
    val intent = Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address))
    carContext.startCarApp(intent)
}

private void onClickNavigate() {
    Intent intent = new Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address));
    getCarContext().startCarApp(intent);
}

如要進一步瞭解如何啟動應用程式 (包括 ACTION_NAVIGATE 意圖的格式)，請參閱「使用意圖啟動車用應用程式」一節。

部分動作 (例如需要引導使用者繼續在行動裝置上進行互動的操作) 只能在車輛停妥時才能使用。您可以使用 ParkedOnlyOnClickListener 實作這些動作。如果車輛並未停妥，主機會顯示通知，讓使用者知道在這種情況下不允許執行此動作。如果車輛停妥，程式碼就會正常執行。下列程式碼片段說明如何使用 ParkedOnlyOnClickListener 在行動裝置上開啟設定畫面：

val row = Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(::openSettingsOnPhone))
    .build()

Row row = new Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(this::openSettingsOnPhone))
    .build();

顯示通知

傳送到行動裝置的通知只有在透過 CarAppExtender 擴充時，才會顯示在車輛螢幕上。您可以在 CarAppExtender 中設定部分通知屬性，例如內容標題、文字、圖示和動作，藉此覆寫顯示在車輛螢幕上的通知屬性。

下列程式碼片段說明如何傳送通知到車輛螢幕，但該螢幕顯示的標題與行動裝置上顯示的標題不同：

val notification = NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build()

Notification notification = new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        new CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build();

通知可能會影響使用者介面的以下部分：

• 系統可能會向使用者顯示抬頭通知 (HUN)。
• 您可在通知中心新增一個項目，並視需要在邊欄顯示標記。
• 如果是導航應用程式，請按照「即時路線通知」的說明，在邊欄小工具中顯示通知。

您可以使用通知的優先順序來設定應用程式通知，進而影響各個使用者介面元素，如 CarAppExtender 說明文件所述。

如果使用 true 值呼叫 NotificationCompat.Builder.setOnlyAlertOnce，則高優先順序的通知只會顯示一次 HUN。

如要進一步瞭解如何設計車用應用程式的通知，請參閱「通知」的 Google Design for 行車指南。

顯示浮動式訊息

應用程式可以使用 CarToast 顯示浮動式訊息，如以下程式碼片段所示：

CarToast.makeText(carContext, "Hello!", CarToast.LENGTH_SHORT).show()

CarToast.makeText(getCarContext(), "Hello!", CarToast.LENGTH_SHORT).show();

要求權限

如果應用程式需要存取受限資料或動作 (例如位置資訊)，則適用 Android 權限的標準規則。如要要求權限，您可以使用 CarContext.requestPermissions() 方法。

使用 CarContext.requestPermissions() 與標準 Android API 相比的優點是不必自行啟動 Activity，即可建立權限對話方塊。此外，您可以在 Android Auto 和 Android Automotive OS 中使用相同的程式碼，不必建立平台相關的流程。

設定 Android Auto 權限對話方塊的樣式

在 Android Auto 上，使用者的權限對話方塊會在手機上顯示。根據預設，對話方塊後不會有任何背景。如要設定自訂背景，請在 AndroidManifest.xml 檔案中宣告車用應用程式主題，然後為車輛應用程式主題設定 carPermissionActivityLayout 屬性。

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

然後，為車輛應用程式主題設定 carPermissionActivityLayout 屬性：

<resources>
  <style name="MyCarAppTheme">
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

使用意圖啟動車用應用程式

您可以呼叫 CarContext.startCarApp 方法，執行下列其中一項動作：

• 開啟撥號程式即可撥打電話。
• 使用預設車輛導航應用程式啟動某個地點的即時路線導航。
• 使用意圖啟動自己的應用程式。

以下範例說明如何透過可開啟應用程式的動作建立通知，畫面會顯示停車預訂詳細資料的畫面。您可以利用包含 PendingIntent 的內容意圖，將通知執行個體擴充到應用程式動作中：

val notification = notificationBuilder
    ...
    .extend(
        CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(ComponentName(context, MyNotificationReceiver::class.java)),
                    0))
            .build())

Notification notification = notificationBuilder
    ...
    .extend(
        new CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    new Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(new ComponentName(context, MyNotificationReceiver.class)),
                    0))
            .build());

應用程式也必須宣告 BroadcastReceiver，此值會在使用者於通知介面中選取動作時叫用以處理意圖，並使用含有資料 URI 的意圖叫用 CarContext.startCarApp：

class MyNotificationReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val intentAction = intent.action
        if (ACTION_VIEW_PARKING_RESERVATION == intentAction) {
            CarContext.startCarApp(
                intent,
                Intent(Intent.ACTION_VIEW)
                    .setComponent(ComponentName(context, MyCarAppService::class.java))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)))
        }
    }
}

public class MyNotificationReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        String intentAction = intent.getAction();
        if (ACTION_VIEW_PARKING_RESERVATION.equals(intentAction)) {
            CarContext.startCarApp(
                intent,
                new Intent(Intent.ACTION_VIEW)
                    .setComponent(new ComponentName(context, MyCarAppService.class))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)));
        }
    }
}

最後，應用程式中的 Session.onNewIntent 方法會在堆疊上推送停車預訂畫面 (如果尚未在上方顯示) 來處理此意圖：

override fun onNewIntent(intent: Intent) {
    val screenManager = carContext.getCarService(ScreenManager::class.java)
    val uri = intent.data
    if (uri != null
        && MY_URI_SCHEME == uri.scheme
        && MY_URI_HOST == uri.schemeSpecificPart
        && ACTION_VIEW_PARKING_RESERVATION == uri.fragment
    ) {
        val top = screenManager.top
        if (top !is ParkingReservationScreen) {
            screenManager.push(ParkingReservationScreen(carContext))
        }
    }
}

@Override
public void onNewIntent(@NonNull Intent intent) {
    ScreenManager screenManager = getCarContext().getCarService(ScreenManager.class);
    Uri uri = intent.getData();
    if (uri != null
        && MY_URI_SCHEME.equals(uri.getScheme())
        && MY_URI_HOST.equals(uri.getSchemeSpecificPart())
        && ACTION_VIEW_PARKING_RESERVATION.equals(uri.getFragment())
    ) {
        Screen top = screenManager.getTop();
        if (!(top instanceof ParkingReservationScreen)) {
            screenManager.push(new ParkingReservationScreen(getCarContext()));
        }
    }
}

如要進一步瞭解如何處理車輛應用程式的通知，請參閱「顯示通知」一節。

範本限制

主機會限制指定工作顯示的範本數量，上限為五個，最後的範本必須是下列其中一種類型：

• NavigationTemplate
• PaneTemplate
• MessageTemplate

請注意，這項限制適用於範本數量，不適用於堆疊中的 Screen 執行個體數量。舉例來說，如果應用程式在畫面 A 中傳送兩個範本，然後推送畫面 B，現在可以再傳送三個範本。或者，如果每個畫面的結構都是傳送單一範本，則應用程式可以將五個畫面例項推送到 ScreenManager 堆疊中。

這些限制有一些特殊情況：範本重新整理，以及返回和重設作業。

範本重新整理作業

某些內容更新不會計入範本限制。一般來說，如果應用程式推送類型與先前範本相同的新範本，且包含與先前範本相同的主要內容，則新範本不會計入配額。舉例來說，更新 ListTemplate 中資料列的切換狀態不會計入配額。如要進一步瞭解哪些類型的內容更新可視為重新整理，請參閱個別範本的說明文件。

返回作業

為了在工作內啟用子流程，主機會偵測應用程式何時從 ScreenManager 堆疊彈出 Screen，並根據應用程式返回的範本數量更新剩餘的配額。

舉例來說，如果應用程式在畫面 A 中傳送兩個範本，接著推送畫面 B 並另外傳送兩個範本，則應用程式還有一個配額。如果應用程式接著回到畫面 A，主機會將配額重設為三，因為應用程式已改回使用兩個範本。

請注意，當您彈出至螢幕時，應用程式必須傳送與該畫面最後傳送的相同類型範本。傳送任何其他範本類型會導致錯誤發生。不過，只要類型在返回作業期間保持不變，應用程式就可以自由修改範本的內容，而不會影響配額。

重設作業

某些範本具有特殊語意，代表工作的結尾。舉例來說，NavigationTemplate 是指預期會持續顯示在螢幕上的檢視畫面，並且會重新整理新的即時路線指示，供使用者的使用情況使用。達到其中一個範本後，主機會重設範本配額，並將該範本視為新任務的第一步。這麼做可讓應用程式開始新的工作。請參閱個別範本的說明文件，瞭解哪些範本會在主機上觸發重設。

如果主機收到透過通知動作或啟動器啟動應用程式的意圖，也會重設配額。此機制可讓應用程式從通知啟動新的工作流程，即使應用程式已繫結且位於前景，此機制也會保持不變。

如要進一步瞭解如何在車輛螢幕上顯示應用程式通知，請參閱「顯示通知」一節。如要瞭解如何透過通知動作啟動應用程式，請參閱「使用意圖啟動車用應用程式」。

連線 API

您可以使用 CarConnection API 在執行階段擷取連線資訊，判斷應用程式是否在 Android Auto 或 Android Automotive OS 上執行。

例如，在車用應用程式的 Session 中，初始化 CarConnection 並訂閱 LiveData 更新：

CarConnection(carContext).type.observe(this, ::onConnectionStateUpdated)

new CarConnection(getCarContext()).getType().observe(this, this::onConnectionStateUpdated);

在觀察器中，您可以回應連線狀態的變更：

fun onConnectionStateUpdated(connectionState: Int) {
  val message = when(connectionState) {
    CarConnection.CONNECTION_TYPE_NOT_CONNECTED -> "Not connected to a head unit"
    CarConnection.CONNECTION_TYPE_NATIVE -> "Connected to Android Automotive OS"
    CarConnection.CONNECTION_TYPE_PROJECTION -> "Connected to Android Auto"
    else -> "Unknown car connection type"
  }
  CarToast.makeText(carContext, message, CarToast.LENGTH_SHORT).show()
}

private void onConnectionStateUpdated(int connectionState) {
  String message;
  switch(connectionState) {
    case CarConnection.CONNECTION_TYPE_NOT_CONNECTED:
      message = "Not connected to a head unit";
      break;
    case CarConnection.CONNECTION_TYPE_NATIVE:
      message = "Connected to Android Automotive OS";
      break;
    case CarConnection.CONNECTION_TYPE_PROJECTION:
      message = "Connected to Android Auto";
      break;
    default:
      message = "Unknown car connection type";
      break;
  }
  CarToast.makeText(getCarContext(), message, CarToast.LENGTH_SHORT).show();
}

限制 API

不同車輛可能會允許使用者一次顯示不同數量的 Item 例項。使用 ConstraintManager 在執行階段檢查內容限制，並設定範本中的適當項目數量。

首先，從 CarContext 取得 ConstraintManager：

val manager = carContext.getCarService(ConstraintManager::class.java)

ConstraintManager manager = getCarContext().getCarService(ConstraintManager.class);

接著，您可以查詢已擷取的 ConstraintManager 物件，查看相關內容的限制。舉例來說，如要取得格線可顯示的項目數量，請使用 CONTENT_LIMIT_TYPE_GRID 呼叫 getContentLimit：

val gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID)

int gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID);

新增登入流程

如果您的應用程式為使用者提供登入體驗，則可以使用搭配 Car App API 級別 2 以上級別的 SignInTemplate 和 LongMessageTemplate 等範本，處理在車用車用運算主機上登入應用程式的程序。

如要建立 SignInTemplate，請定義 SignInMethod。車輛應用程式程式庫目前支援下列登入方法：

• InputSignInMethod 用於登入使用者名稱/密碼。
• PinSignInMethod 用於 PIN 碼登入，使用者需使用車用運算主機上顯示的 PIN 碼，從手機連結帳戶。
• ProviderSignInMethod 用於供應商登入程序，例如 Google 登入和 One Tap。
• QRCodeSignInMethod 用於 QR code 登入，使用者只要掃描 QR code，即可在手機上完成登入程序。適用於 Car API 級別 4 及以上級別。

舉例來說，如要實作收集使用者密碼的範本，請先建立 InputCallback 來處理及驗證使用者輸入內容：

val callback = object : InputCallback {
    override fun onInputSubmitted(text: String) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    override fun onInputTextChanged(text: String) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
}

InputCallback callback = new InputCallback() {
    @Override
    public void onInputSubmitted(@NonNull String text) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    @Override
    public void onInputTextChanged(@NonNull String text) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
};

必須為 InputSignInMethod Builder 設定 InputCallback。

val passwordInput = InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build()

InputSignInMethod passwordInput = new InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build();

最後，使用新的 InputSignInMethod 建立 SignInTemplate。

SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build()

new SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build();

使用 AccountManager

設有驗證功能的 Android Automotive OS 應用程式都必須使用 AccountManager，原因如下：

• 提供更優質的使用者體驗和簡便的帳戶管理功能：使用者可透過系統設定中的帳戶選單輕鬆管理所有帳戶 (包括登入及登出帳戶)。
• 「訪客」體驗：由於車輛是共用裝置，因此原始設備製造商 (OEM) 可以在車輛上啟用訪客體驗，藉此禁止新增帳戶。

新增文字字串變化版本

不同大小的車輛螢幕顯示的文字量可能不同。使用 Car App API 級別 2 以上的時，您可以指定文字字串的多個變化版本，以符合螢幕尺寸。如要查看文字變化版本的接受位置，請找出採用 CarText 的範本和元件。

您可以使用 CarText.Builder.addVariant() 方法將文字字串變化版本新增至 CarText：

val itemTitle = CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build()

CarText itemTitle = new CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build();

接著，您可以使用這個 CarText，例如做為 GridItem 的主要文字。

GridItem.Builder()
    .addTitle(itemTitle)
    ...
    .build()

new GridItem.Builder()
    .addTitle(itemTitle)
    ...
    build();

新增字串，按照偏好由高到低排列，例如從長到短。主辦人會根據車輛螢幕上的可用空間大小，選擇合適的長度字串。

新增資料列的內嵌 CarIcons

您可以使用 CarIconSpan 新增內嵌文字的圖示，讓應用程式的視覺效果更豐富。如要進一步瞭解如何建立這些 Span，請參閱 CarIconSpan.create 的說明文件。如要概略瞭解使用 Span 的文字樣式設定方式，請參閱「使用 Span 定義文字樣式」一文。

  
val rating = SpannableString("Rating: 4.5 stars")
rating.setSpan(
    CarIconSpan.create(
        // Create a CarIcon with an image of four and a half stars
        CarIcon.Builder(...).build(),
        // Align the CarIcon to the baseline of the text
        CarIconSpan.ALIGN_BASELINE
    ),
    // The start index of the span (index of the character '4')
    8,
    // The end index of the span (index of the last 's' in "stars")
    16,
    Spanned.SPAN_INCLUSIVE_INCLUSIVE
)

val row = Row.Builder()
    ...
    .addText(rating)
    .build()
  
  

  
SpannableString rating = new SpannableString("Rating: 4.5 stars");
rating.setSpan(
        CarIconSpan.create(
                // Create a CarIcon with an image of four and a half stars
                new CarIcon.Builder(...).build(),
                // Align the CarIcon to the baseline of the text
                CarIconSpan.ALIGN_BASELINE
        ),
        // The start index of the span (index of the character '4')
        8,
        // The end index of the span (index of the last 's' in "stars")
        16,
        Spanned.SPAN_INCLUSIVE_INCLUSIVE
);
Row row = new Row.Builder()
        ...
        .addText(rating)
        .build();
  
  

車用硬體 API

自 Car App API 級別 3 起，車輛應用程式程式庫提供 API，可讓您存取車輛屬性和感應器。

規定

如要搭配 Android Auto 使用 API，請先在 Android Auto 模組的 build.gradle 檔案中新增 androidx.car.app:app-projected 的依附元件。如果是 Android Automotive OS，請在 Android Automotive OS 模組的 build.gradle 檔案中新增 androidx.car.app:app-automotive 的依附元件。

此外，在 AndroidManifest.xml 檔案中，您需要宣告必要的相關權限，才能要求要使用的車輛資料。請注意，這些權限還必須由使用者授予您。您可以在 Android Auto 和 Android Automotive OS 上使用相同程式碼，不必建立依平台區分的資料流。但是需要的權限不同。

汽車資訊

下表說明 CarInfo API 顯示的屬性，以及使用這些屬性所需的權限：

舉例來說，如要取得剩餘的範圍，請將 CarInfo 物件例項化，然後建立並註冊 OnCarDataAvailableListener：

val carInfo = carContext.getCarService(CarHardwareManager::class.java).carInfo

val listener = OnCarDataAvailableListener<EnergyLevel> { data ->
    if (data.rangeRemainingMeters.status == CarValue.STATUS_SUCCESS) {
      val rangeRemaining = data.rangeRemainingMeters.value
    } else {
      // Handle error
    }
  }

carInfo.addEnergyLevelListener(carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener)

CarInfo carInfo = getCarContext().getCarService(CarHardwareManager.class).getCarInfo();

OnCarDataAvailableListener<EnergyLevel> listener = (data) -> {
  if(data.getRangeRemainingMeters().getStatus() == CarValue.STATUS_SUCCESS) {
    float rangeRemaining = data.getRangeRemainingMeters().getValue();
  } else {
    // Handle error
  }
};

carInfo.addEnergyLevelListener(getCarContext().getMainExecutor(), listener);
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener);

請勿假設車輛隨時都能取得資料。如果收到錯誤訊息，請查看所要求值的狀態，進一步瞭解無法擷取您要求資料的原因。如需完整的 CarInfo 類別定義，請參閱參考說明文件。

汽車感測器

CarSensors 類別可讓您存取車輛的加速計、陀螺儀、指南針和位置資料。這些值的可用性可能取決於原始設備製造商 (OEM) 而定。加速計、陀螺儀和指南針的資料格式與 SensorManager API 取得的資料格式相同。舉例來說，如要查看車輛的方向，請按照下列步驟操作：

val carSensors = carContext.getCarService(CarHardwareManager::class.java).carSensors

val listener = OnCarDataAvailableListener<Compass> { data ->
    if (data.orientations.status == CarValue.STATUS_SUCCESS) {
      val orientation = data.orientations.value
    } else {
      // Data not available, handle error
    }
  }

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener)

CarSensors carSensors = getCarContext().getCarService(CarHardwareManager.class).getCarSensors();

OnCarDataAvailableListener<Compass> listener = (data) -> {
  if (data.getOrientations().getStatus() == CarValue.STATUS_SUCCESS) {
    List<Float> orientations = data.getOrientations().getValue();
  } else {
    // Data not available, handle error
  }
};

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, getCarContext().getMainExecutor(),
    listener);
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener);

如要存取車輛的位置資料，您還需要宣告並要求 android.permission.ACCESS_FINE_LOCATION 權限。

測試

如要在 Android Auto 上測試時模擬感應器資料，請參閱電腦版車用運算主機指南的「感應器」和「感應器設定」章節。如要在 Android Automotive OS 上測試時模擬感應器資料，請參閱 Android Automotive OS 模擬器指南的「模擬硬體狀態」一節。

CarAppService、工作階段和螢幕生命週期

Session 和 Screen 類別會實作 LifecycleOwner 介面。使用者與應用程式互動時，系統會叫用 Session 和 Screen 物件的生命週期回呼，如下圖所示。

CarAppService 和工作階段的生命週期

詳情請參閱 Session.getLifecycle 方法的說明文件。

畫面的生命週期

詳情請參閱 Screen.getLifecycle 方法的說明文件。

透過汽車麥克風錄影

只要使用應用程式的 CarAppService 和 CarAudioRecord API，即可授權應用程式存取使用者的車用麥克風。使用者必須授予應用程式權限，才能存取車輛麥克風。應用程式可在應用程式中記錄及處理使用者的輸入內容。

錄音權限

錄製任何音訊前，您必須先宣告在 AndroidManifest.xml 中錄製的權限，並要求使用者授予權限。

<manifest ...>
   ...
   <uses-permission android:name="android.permission.RECORD_AUDIO" />
   ...
</manifest>

你必須取得在執行階段錄製的權限。如要進一步瞭解如何在車輛應用程式中要求權限，請參閱「要求權限」一節。

錄音

使用者授予錄音權限後，您就可以錄製音訊並處理錄音內容。

val carAudioRecord = CarAudioRecord.create(carContext)
        carAudioRecord.startRecording()

        val data = ByteArray(CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE)
        while(carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording()
 

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        carAudioRecord.startRecording();

        byte[] data = new byte[CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE];
        while (carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording();
 

音訊焦點

從車輛麥克風錄音時，請先取得音訊對焦，以確保任何進行中的媒體已停止。如果您失去音訊焦點，請停止錄音

以下範例說明如何取得音訊焦點：

 
val carAudioRecord = CarAudioRecord.create(carContext)
        
        // Take audio focus so that user's media is not recorded
        val audioAttributes = AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
            // Use the most appropriate usage type for your use case
            .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
            .build()
        
        val audioFocusRequest =
            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                .setAudioAttributes(audioAttributes)
                .setOnAudioFocusChangeListener { state: Int ->
                    if (state == AudioManager.AUDIOFOCUS_LOSS) {
                        // Stop recording if audio focus is lost
                        carAudioRecord.stopRecording()
                    }
                }
                .build()
        
        if (carContext.getSystemService(AudioManager::class.java)
                .requestAudioFocus(audioFocusRequest)
            != AudioManager.AUDIOFOCUS_REQUEST_GRANTED
        ) {
            // Don't record if the focus isn't granted
            return
        }
        
        carAudioRecord.startRecording()
        // Process the audio and abandon the AudioFocusRequest when done

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        // Take audio focus so that user's media is not recorded
        AudioAttributes audioAttributes =
                new AudioAttributes.Builder()
                        .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                        // Use the most appropriate usage type for your use case
                        .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
                        .build();

        AudioFocusRequest audioFocusRequest =
                new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                        .setAudioAttributes(audioAttributes)
                        .setOnAudioFocusChangeListener(state -> {
                            if (state == AudioManager.AUDIOFOCUS_LOSS) {
                                // Stop recording if audio focus is lost
                                carAudioRecord.stopRecording();
                            }
                        })
                        .build();

        if (getCarContext().getSystemService(AudioManager.class).requestAudioFocus(audioFocusRequest)
                != AUDIOFOCUS_REQUEST_GRANTED) {
            // Don't record if the focus isn't granted
            return;
        }

        carAudioRecord.startRecording();
        // Process the audio and abandon the AudioFocusRequest when done
 

測試程式庫

車輛專用 Android 測試程式庫提供輔助類別，可用來在測試環境中驗證應用程式行為。舉例來說，SessionController 可讓您模擬與主機的連線，並確認已建立並傳回正確的 Screen 和 Template。

如需使用範例，請參閱範例。

回報車輛專用 Android App Library 問題

如果您發現程式庫有問題，請使用 Google Issue Tracker 回報。在問題範本中，請務必填寫所有必要資訊。

建立新問題

提交新問題之前，請先查看該問題是否列在程式庫的版本資訊中，或是列在問題清單中。您可以在追蹤程式中按一下該問題的星號，訂閱該問題並投下一票。詳情請參閱訂閱問題一文。