原始設備製造商 (OEM) 整合指南

本頁說明如何在 VHAL 中處理旋鈕輸入、設定版本以納入旋鈕服務，以及如何自訂所有應用程式的旋鈕體驗。如要瞭解預先安裝的 OEM 應用程式 (例如 OEM 提供的啟動器)，請參閱「車輛 UI 程式庫 (car-ui-library)」。

VHAL

旋轉控制器支援下列動作：

  • 往上、下、左和右微調。
  • 順時針和逆時針旋轉。
  • 按下中央按鈕。
  • 按下「返回」按鈕。
  • 按下主畫面按鈕。
  • 按下其他按鈕，例如「電話」和「媒體」。

如要瞭解系統屬性和對應的 int32Values，請參閱 hardware/interfaces/automotive/vehicle/2.0/types.hal。

VHAL 應處理下列動作：

提醒

使用者向右推動旋轉控制器時，VHAL 應使用 HW_KEY_INPUT 屬性和下列 int32Values，將事件傳送至 Android：

  1. ACTION_DOWN
  2. KEYCODE_SYSTEM_NAVIGATION_RIGHT
  3. 目標顯示。

使用者放開旋轉控制器時，VHAL 應使用與 ACTION_UP 相同的屬性和鍵碼。其他方向的微調應使用對應的鍵碼。

對角線沒有鍵碼，但如果硬體支援對角線，VHAL 可以結合水平和垂直事件來產生對角線。舉例來說，向上和向左微調應會產生：

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN

無論先放開哪個旋轉控制器，都應產生以下結果：

  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
  • HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

使用者可能會先垂直推動旋轉控制器，再放開。 舉例來說，以下情境：

垂直方向
圖 1. 垂直方向

這應該會產生下列事件序列：

  1. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_DOWN
  2. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_DOWN
  3. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_LEFT ACTION_UP
  4. HW_KEY_INPUT KEYCODE_SYSTEM_NAVIGATION_UP ACTION_UP

旋轉控制器朝同一方向轉動時，不應產生任何 repeat 事件。

旋轉

使用者將旋轉控制器順時針旋轉一個凹槽 (按一下) 時，VHAL 應使用下列 int32Values 的 HW_ROTARY_INPUT 屬性，將事件傳送至 Android：

  1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
  2. 一個 (1) 止動點。
  3. 目標顯示。

事件的時間戳記應設為經過的時間 (以奈秒為單位)。

逆時針旋轉一格應會產生相同事件，但格數為 -1。

如果旋轉時在同一方向快速發生多個凹口，VHAL 應將凹口合併為單一事件，以免系統事件過載。在這種情況下，事件的時間戳記應為發生第一次旋轉凹口的時間。int32Values 應包含連續旋轉凹口之間的奈秒數。

舉例來說，下列旋轉順序：

  • 在時間 t0，使用者逆時針旋轉一個凹槽。
  • 在時間 t0 + 5 ns，使用者逆時針旋轉一個凹口。
  • 在 t0 + 8 奈秒時，使用者逆時針旋轉一個凹口。

應會產生這個事件：

  • 資源：HW_ROTARY_INPUT
  • 時間戳記：t0
  • int32Values：
    1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
    2. -3 (逆時針旋轉三個凹槽)。
    3. 目標顯示。
    4. 第一和第二個凹槽之間有 5 奈秒。
    5. 第二個和第三個凹槽之間為 3 奈秒。

中間按鈕

使用者按下「中心」按鈕時，VHAL 應使用下列 int32Values 的 HW_KEY_INPUT 屬性，將事件傳送至 Android：

  1. ACTION_DOWN
  2. KEYCODE_DPAD_CENTER
  3. 目標顯示。

使用者放開旋轉控制器時，VHAL 應使用與 ACTION_UP 相同的屬性和鍵碼。

請勿在按住中央按鈕時產生 repeat 事件。

返回按鈕

使用者按下返回鍵時，VHAL 應使用下列 int32Values 的 HW_KEY_INPUT 屬性，將事件傳送至 Android：

  1. ACTION_DOWN
  2. KEYCODE_BACK
  3. 目標顯示。

使用者放開旋轉控制器時，VHAL 應使用與 ACTION_UP 相同的屬性和鍵碼。

按住中央按鈕時，不應產生任何 repeat 事件。

首頁按鈕

操作主畫面按鈕的方式與返回按鈕相同，但請使用 KEYCODE_HOME 而非 KEYCODE_BACK。

其他按鈕

如果旋轉控制器包含任何其他按鈕，VHAL 可以按照 OEM 的喜好處理這些按鈕，因為從 Android 的角度來看，這些按鈕不屬於旋轉控制器。這類按鈕通常會像「返回」和「首頁」按鈕一樣處理，但使用不同的鍵碼。 例如 KEYCODE_CALL 或 KEYCODE_MUSIC

建構設定

旋轉導覽功能是由名為 RotaryService 的無障礙服務提供。 如要在裝置的系統映像檔中加入這項服務，請在 Makefile 中新增下列程式碼：

PRODUCT_PACKAGES += CarRotaryController

您也可以在偵錯版本中加入下列套件：

  • RotaryPlayground 旋轉控制項的參考應用程式 (請參閱「RotaryPlayground」)。
  • RotaryIME 旋轉輸入法編輯器 (請參閱「輸入法編輯器」)。
  • CarRotaryImeRRO「RotaryIME」的重疊廣告。

裝置啟動時和使用者切換時，系統會自動啟用旋轉服務。確保使用者在設定期間可以使用旋轉控制器。

如果車輛有旋轉控制器和沒有旋轉控制器時，您使用相同的建構版本，請如上所示新增 CarRotaryController，確保建構版本包含必要的程式碼。如要避免在非旋鈕車輛上啟用旋鈕服務，請建立靜態 RRO，將 packages/services/Car/service 中的 rotaryService 字串資源覆蓋為空字串。您會使用相同的建構版本，但旋鈕和非旋鈕裝置的產品設定不同。只有後者包含疊加層。

自訂

原始設備製造商 (OEM) 可透過下列位置的資源疊加層，自訂焦點尋找邏輯、焦點螢光標示和一些額外項目：

  • car-ui-library 位於 packages/apps/Car/libs/car-ui-lib
  • 「RotaryService」位於「packages/apps/Car/RotaryController」
  • 「Core」位於「frameworks/base/core」

提醒記錄

原始設備製造商可以設定是否啟用兩種提醒記錄，如果啟用，則可設定快取大小和到期政策。只要覆寫各種 car-ui-library 資源，即可完成上述所有作業。

焦點記錄快取

(Android 11 QPR3、Android 11 車輛、Android 12)
這個 per-FocusArea 快取會儲存 FocusArea 中最近聚焦的檢視區塊，以便在輕觸返回 FocusArea 時聚焦該檢視區塊。 您可以覆寫下列 car-ui-library 資源，設定這個快取：

  • car_ui_focus_history_cache_type：
    1. 快取已停用。
    2. 快取會在一段時間後失效 (請見下方說明)。
    3. 快取永不過期。
  • car_ui_focus_history_expiration_period_ms：如果快取類型設為 2 (如上所述)，快取到期前幾毫秒。

FocusArea 歷來資料快取

(Android 11 QPR3、Android 11 Car、Android 12)
這個快取會儲存輕觸歷史記錄，因此朝相反方向輕觸可將焦點返回同一個 FocusArea。您可以覆寫下列 car-ui-library 資源，設定這個快取：

  • car_ui_focus_area_history_cache_type：
    1. 快取已停用。
    2. 快取會在一段時間後失效 (請見下方說明)。
    3. 快取永不過期。
  • car_ui_focus_area_history_expiration_period_ms：如果快取類型設為 2 (如上所述)，快取到期前經過的毫秒數。
  • car_ui_clear_focus_area_history_when_rotating：使用者旋轉控制器時是否要清除快取。

旋轉

(Android 11 QPR3、Android 11 Car、Android 12)
原始設備製造商可以在 RotaryService 中覆寫兩個整數資源，指定是否要為旋轉操作提供加速功能 (例如滑鼠加速)：

  • rotation_acceleration_3x_ms：時間間隔 (以毫秒為單位)，用於判斷 Google 是否應加速控制器旋轉，以取得旋轉的凹口。如果這個凹口與前一個凹口之間的旋轉間隔小於這個值，系統會將其視為三個凹口。如要停用 3 倍加速功能，請將此值設為 2147483647。
  • rotation_acceleration_2x_ms：與 rotation_acceleration_3x_ms 類似。 用於 2 倍速播放。如要停用 2 倍速，請將此值設為 2147483647。

如果旋轉的每個凹口都有個別的時間戳記，加速效果最佳，因為 VHAL 需要這項資訊。如果沒有這些值，RotaryService 會假設旋轉的凹口間距相等。

/**
     * Property to feed H/W rotary events to android
     *
     * int32Values[0] : RotaryInputType identifying which rotary knob rotated
     * int32Values[1] : number of detents (clicks), positive for clockwise,
     *                  negative for counterclockwise
     * int32Values[2] : target display defined in VehicleDisplay. Events not
     *                  tied to specific display must be sent to
     *                  VehicleDisplay#MAIN.
     * int32values[3 .. 3 + abs(number of detents) - 2]:
     *                  nanosecond deltas between pairs of consecutive detents,
     *                  if the number of detents is > 1 or < -1
     *
     * VehiclePropValue.timestamp: when the rotation occurred. If the number of
     *                             detents is > 1 or < -1, this is when the
     *                             first detent of rotation occurred.
     *
     * @change_mode VehiclePropertyChangeMode:ON_CHANGE
     * @data_enum RotaryInputType
     * @access VehiclePropertyAccess:READ
     */
    HW_ROTARY_INPUT = (
        0x0A20
        | VehiclePropertyGroup:SYSTEM
        | VehiclePropertyType:INT32_VEC
        | VehicleArea:GLOBAL),

焦點醒目顯示

原始設備製造商 (OEM) 可以覆寫 Android 架構中的預設焦點醒目顯示，以及 car-ui-library 中的多個焦點醒目顯示資源。

預設焦點醒目顯示

Android 架構會透過 selectableItemBackground 屬性提供預設焦點醒目顯示效果。在 Theme.DeviceDefault 中，這個屬性是指 Core 中的 item_background.xml。原始設備製造商可以疊加 item_background.xml，變更預設焦點醒目顯示可繪項目。

這個可繪項目通常是 StateListDrawable，可根據不同狀態組合 (包括 android:state_focused 和 android:state_pressed) 調整背景。當使用者使用旋轉控制器聚焦檢視區塊時，android:state_focused 會是 true，但 android:state_pressed 會是 false。如果使用者接著按下旋轉控制器的中央按鈕，則在使用者按住按鈕時，android:state_focused 和 android:state_pressed 都會是 true。使用者放開按鈕時，只會留下 android:state_focusedtrue。

car-ui-library 使用衍生自 Theme.DeviceDefault 的主題。因此，這個疊加層會影響使用這個程式庫的應用程式，以及使用衍生自 Theme.DeviceDefault 主題的應用程式。使用不相關主題 (例如 Theme.Material) 的應用程式不會受到影響。

著重於 car-ui-library 中的重點資源

原始設備製造商 (OEM) 可以覆寫多個 car-ui-library 資源，控管焦點醒目顯示在非矩形 (例如圓形或藥丸形) 焦點醒目顯示檢視區塊中的外觀，以及在不衍生自 Theme.DeviceDefault 的主題所使用的應用程式中。這些資源應重疊，使焦點醒目顯示與預設焦點醒目顯示可繪項目一致。

(Android 11 QPR3、Android 11 Car、Android 12)
下列資源用於指出檢視區塊已成為焦點，但未遭按下：

  • car_ui_rotary_focus_fill_color：填滿顏色。
  • car_ui_rotary_focus_stroke_color：外框顏色。
  • car_ui_rotary_focus_stroke_width：輪廓的粗細。

(Android 11 QPR3、Android 11 Car、Android 12)
下列資源用於指出檢視區塊何時處於焦點和按下狀態：

  • car_ui_rotary_focus_pressed_fill_color：填滿顏色。
  • car_ui_rotary_focus_pressed_stroke_color：外框顏色。
  • car_ui_rotary_focus_pressed_stroke_width：輪廓的粗細。

有時按鈕會使用純色背景，吸引使用者注意，如範例所示。這可能會導致焦點醒目顯示難以辨識。

實心背景按鈕
圖 2. 按鈕 (實心背景)

在這種情況下，開發人員可以使用次要顏色指定自訂焦點醒目顯示：
  • (Android 11 QPR3、Android 11 Car、Android 12)
    car_ui_rotary_focus_fill_secondary_color
    car_ui_rotary_focus_stroke_secondary_color
  • (Android 12)
    car_ui_rotary_focus_pressed_fill_secondary_color
    car_ui_rotary_focus_pressed_stroke_secondary_color

如果只想填滿或只顯示輪廓，任何顏色都可以是透明色，任一維度也可以是零。

FocusArea 醒目顯示

(Android 11 QPR3、Android 11 Car、Android 12)
FocusArea 在其中一個子項處於焦點時，可以繪製兩種醒目顯示效果。如要同時使用這兩者，請一併啟用。這項功能在 AOSP 中預設為停用，但您可以覆寫 car-ui-library 資源來啟用：

  • car_ui_enable_focus_area_foreground_highlight：在 FocusArea 及其後代上方繪製醒目顯示效果。在 AOSP 中，這個可繪項目是 FocusArea 周圍的輪廓。原始設備製造商可以覆寫 car_ui_focus_area_foreground_highlight 可繪項目。
  • car_ui_enable_focus_area_background_highlight：在 FocusArea 上方繪製醒目顯示，但位於其後代之後。在 AOSP 中，這個可繪項目是實心填滿。 原始設備製造商可以覆寫 car_ui_focus_area_background_highlight 可繪項目。

輸入法編輯器

輸入法編輯器 (IME) 是輸入法。例如螢幕小鍵盤。

(Android 11 QPR3、Android 11 Car、 Android 12)
OEM 必須在 RotaryService 中疊加 default_touch_input_method 字串資源，指定觸控式 IME 的 ComponentName。舉例來說，如果原始設備製造商使用 Android Automotive 提供的 IME，就應指定 com.google.android.apps.automotive.inputmethod/.InputMethodService。

(Android 11 QPR3、Android 11 Car、Android 12)
如果 OEM 專為旋鈕建立 IME，應在 rotary_input_method 資源中指定其 ComponentName。如果這個資源遭到覆蓋，使用者透過旋轉控制器的輕觸、旋轉和中央按鈕與車機互動時，系統就會使用指定的 IME。使用者輕觸螢幕時，系統會使用先前的 IME。「返回」按鈕 (和旋轉控制器上的其他按鈕) 不會影響輸入法選取作業。如果沒有疊加這項資源，就不會切換輸入法編輯器。Carboard 不支援旋轉輸入，因此如果 OEM 未提供旋轉輸入法編輯器，使用者就無法透過旋轉控制器輸入文字。

RotaryIME 是旋轉式 IME 的示範。雖然是基本功能，但足以試用上述自動切換 IME 的功能。RotaryIME 的原始碼位於 packages/apps/Car/tests/RotaryIME/。

螢幕外自動提醒

根據預設，使用者嘗試將內容推離螢幕邊緣時，不會發生任何情況。 OEM 可以指定下列任意組合，為四個方向分別設定相應動作：

  1. 由 AccessibilityService 定義的全域動作。例如：GLOBAL_ACTION_BACK。
  2. 金鑰代碼，例如 KEYCODE_BACK。
  3. 以網址表示的活動啟動意圖。

(Android 11 QPR3、Android 11 車用版、Android 12)
方法是在 RotaryService 中疊加下列陣列資源：

  • off_screen_nudge_global_actions：使用者在螢幕邊緣向上、下、左或右輕觸時要執行的全域動作陣列。如果這個陣列的相關元素為 -1，則不會執行任何全域動作。
  • off_screen_nudge_key_codes：當使用者在螢幕邊緣向上、向下、向左或向右輕觸時，要注入的點擊事件鍵碼陣列。如果這個陣列的相關元素為 0 (KEYCODE_UNKNOWN)，系統就不會插入任何事件。
  • off_screen_nudge_intents：當使用者在螢幕邊緣向上、下、左或右輕觸時，要啟動活動的意圖陣列。如果這個陣列的相關元素為空白，系統就不會啟動任何活動。

其他設定

您應疊加下列 RotaryService 資源：

  • (Android 11 QPR3、Android 11 Car、 Android 12)
    config_showHeadsUpNotificationOnBottom：布林值，代表系統應在底部而非頂端顯示即時通知。這個值必須與 frameworks/base/packages/CarSystemUI/res/values/config.xml 中的 config_showHeadsUpNotificationOnBottom 布林值資源相同。
  • (Android 11 QPR3、Android 11 Car、 Android 12)
    notification_headsup_card_margin_horizontal：即時訊息通知視窗的左右邊界。這個值必須與 packages/apps/Car/Notification/res/values/dimens.xml 中的 notification_headsup_card_margin_horizontal dimen 資源相同。
  • (Android 12)
    excluded_application_overlay_window_titles：不應視為疊加視窗的視窗標題陣列。包括代表 TaskViews 或 TaskDisplayAreas 的應用程式視窗標題。 根據預設，這份清單只會包含「地圖」。

您可以疊加下列 RotaryService 資源：

  • (Android 11 QPR3、Android 11 Car、Android 12)
    long_press_ms：整數值，代表必須按住中央按鈕多少毫秒，才會觸發長按動作。如果設為零，代表使用系統預設的長按逾時時間。這是預設值。