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

本頁說明如何在 VHAL 中處理旋轉輸入內容、設定版本以納入旋轉服務，以及如何在所有應用程式中自訂旋轉體驗。如要瞭解預先安裝的原始設備製造商 (OEM) 應用程式 (例如 OEM 提供的啟動器)，請參閱「Car UI Library (car-ui-library)」一文。

VHAL

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

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

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

VHAL 應處理下列動作：

清脆

當使用者將旋轉控制器推向右側時，VHAL 應使用以下 int32Values 的 HW_KEY_INPUT 屬性，將事件傳送至 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

旋轉控制器保持在單一方向時，不應產生「重複」事件。

旋轉

當使用者順時針轉動旋轉控制器一個刻度 (按一下) 時，VHAL 應使用 HW_ROTARY_INPUT 屬性搭配下列 int32Values，將事件傳送至 Android：

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

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

以逆時針方向旋轉一次 (1) 的棘爪應產生相同的事件，但棘爪數量為 -1。

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

例如，以下是旋轉的順序：

  • 在時間 t0 時，使用者逆時針旋轉一個刻度點。
  • 在時間 t0 + 5 毫秒時，使用者逆時針旋轉一個定位點。
  • 在時間 t0 + 8 奈秒時，使用者逆時針旋轉一個刻度點。

應會產生以下事件：

  • 資源：HW_ROTARY_INPUT
  • 時間戳記：t0
  • int32Values：
    1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
    2. -3 (逆時針轉三格)。
    3. 目標顯示器。
    4. 第一個和第二個鎖定點之間的時間間隔為 5 毫秒。
    5. 第二和第三個定位點之間的時間為 3 秒。

中間按鈕

當使用者按下中央按鈕時，VHAL 應使用 HW_KEY_INPUT 屬性搭配下列 int32Values，將事件傳送至 Android：

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

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

按住中央按鈕時，請勿產生「重複」事件。

「返回」按鈕

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

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

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

按住中央按鈕時，系統不應產生「重複」事件。

[首頁] 按鈕

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

其他按鈕

如果旋轉控制器包含任何其他按鈕，VHAL 可以處理這些按鈕，因為從 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

推薦歷史記錄

OEM 可以設定是否啟用兩種推送提醒記錄，如果啟用，則可設定快取大小和到期政策。這一切都是透過覆寫各種 car-ui-library 資源完成。

焦點記錄快取

(Android 11 QPR3、Android 11 Car、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)
原始設備製造商 (OEM) 可在 RotaryService 中覆寫兩個整數資源，指定是否要為旋轉提供加速度，例如滑鼠加速度：

  • rotation_acceleration_3x_ms：用於決定 Google 是否應加快控制器旋轉速度，以便在旋轉時停頓。如果此制動點與前一個旋轉制動點之間的間隔小於此值，則會視為三個旋轉制動點。將此值設為 2147483647 可停用 3 倍加速功能。
  • rotation_acceleration_2x_ms：類似 rotation_acceleration_3x_ms。用於 2 倍加速。將此值設為 2147483647 即可停用 2 倍加速功能。

加速功能的效果最佳時機，是每個旋轉停頓點都有個別的時間戳記，這項規定由 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。OEM 可以疊加 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_focused 會保留 true。

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 周圍的輪廓。原始設備製造商 (OEM) 可以覆寫 car_ui_focus_area_foreground_highlight 可繪項目。
  • car_ui_enable_focus_area_background_highlight：在 FocusArea 上方繪製醒目顯示，但位於其子項後方。在 AOSP 中，這個可繪項目是實心填充。原始設備製造商 (OEM) 可以覆寫 car_ui_focus_area_background_highlight 可繪項目。

輸入法編輯器

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

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

(Android 11 QPR3、Android 11 Car、Android 12)
如果原始設備製造商已建立專為旋轉式輸入法設計的 IME，則應在 rotary_input_method 資源中指定其 ComponentName。如果覆疊此資源，只要使用者透過旋轉控制器的輕推、旋轉和 Center 按鈕與車用主機互動，系統就會使用指定的 IME。使用者輕觸螢幕時，系統會使用先前的 IME。返回按鈕 (以及旋轉控制器上的其他按鈕) 不會影響 IME 選取。如果未疊加這項資源，就不會發生輸入法編輯器切換情形。Carboard 不支援旋轉輸入功能，因此如果原始設備製造商未提供旋轉 IME，使用者就無法透過旋轉控制器輸入文字。

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

螢幕外自動提醒

根據預設，當使用者嘗試將螢幕推離邊緣時，系統不會執行任何操作。OEM 廠商可以指定下列任意組合，設定四個方向的運作方式：

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

(Android 11 QPR3、Android 11 Car、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：整數值，代表必須按住中間按鈕多久 (以毫秒為單位)，才能觸發長按動作。零表示應使用系統預設的長按逾時時間。這是預設值。