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

本頁說明如何處理 VHAL 中的旋轉輸入、設定您的建構作業 加入旋轉服務,以及如何在所有應用程式自訂旋轉體驗。 如需預先安裝的原始設備製造商 (OEM) 應用程式 (例如原始設備製造商 (OEM) 提供的啟動器),請參閱 Car UI 程式庫 (car-ui-library)

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

  • 向上、向下、向左、向右。
  • 順時針及逆時針旋轉。
  • 按下中間的按鈕。
  • 按下「返回」按鈕。
  • 按下主畫面按鈕。
  • 按下「手機」和「媒體」等其他按鈕。

如需說明文件,請參閱 hardware/interfaces/automotive/vehicle/2.0/types.hal 系統屬性和對應的 int32Values

VHAL 應處理以下動作:

清脆

當使用者向右推送旋轉控制器時,VHAL 應使用 含有下列 int32ValuesHW_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) 代表逆時針旋轉應產生相同的事件,但 十進位的數值。

如果相同方向的多個旋轉角度發生快速連續,VHAL 應合併至單一事件,以免系統因事件而超載。 在此情況下,事件的時間戳記應為首次旋轉發生的時間。 int32Values 應包含連續點號之間的奈秒秒數 輪替金鑰

例如,下列的旋轉順序..

  • 在 t0 時,使用者逆時針旋轉一圈。
  • 在 t0 + 5 ns 時,使用者逆時針旋轉一圈。
  • 在 t0 + 8 ns 時,使用者逆時針旋轉一圈。

會產生以下事件:

  • 資源:HW_ROTARY_INPUT
  • 時間戳記:t0
  • int32Values:
    1. ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
    2. -3 (逆時針方向 3 度)。
    3. 目標多媒體廣告:
    4. 從第一到第二都的間隔 5 奈秒。
    5. 介於二到第三有機。

中間按鈕

使用者按下中心按鈕時,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 可以處理這些按鈕, 原始設備製造商 (OEM) 類似,因此從 Android 的角度來看,這類裝置並不屬於旋轉效果。 這類按鈕的處理方式通常是「返回」和「主畫面」按鈕,但按鍵碼不同。 例如 KEYCODE_CALLKEYCODE_MUSIC

建構設定

旋轉導覽是由名為 RotaryService 的無障礙服務提供。 如要在裝置的系統映像檔中加入這項服務,請在 makefile:

PRODUCT_PACKAGES += CarRotaryController

建議您一併在偵錯版本中加入下列套件:

  • RotaryPlayground旋轉的參考應用程式 (請見 RotaryPlayground)。
  • RotaryIME示範旋轉輸入法編輯器 (請參閱「輸入法編輯器」)。
  • CarRotaryImeRRO RotaryIME 的疊加層。

裝置開機時以及使用者時,旋轉服務會自動啟用 就會開啟切換器確保使用者可以在設定期間使用旋轉控制器。

如果您在搭載和沒有旋轉控制器的車輛中使用同一個版本, 新增 CarRotaryController (如上所示),以便加入必要的程式碼 在建構過程中如要避免在非旋轉車上啟用旋轉服務,請 靜態 RRO,用於將 rotaryService 字串資源疊加在 packages/services/Car/service 包含空字串。您也使用相同的版本 但針對旋轉和非旋轉裝置採用不同的產品設定。只有後者 包括疊加層

自訂

原始設備製造商 (OEM) 可以透過工具 位於下列位置的資源疊加層:

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

提醒記錄

原始設備製造商 (OEM) 可以設定兩種類型的自動提醒記錄是否啟用。如果已啟用, 快取大小和到期政策方法是覆寫各種 Car-ui-library 再複習一下,機構節點 是所有 Google Cloud Platform 資源的根節點

聚焦記錄快取

(Android 11 QPR3、Android 11 汽車、 Android 12)
這個個別 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 汽車、 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 汽車、 Android 12)
原始設備製造商 (OEM) 可以覆寫 RotaryService 中的兩個整數資源,以指定 是否使用加速功能 (例如滑鼠加速) 來旋轉:

  • rotation_acceleration_3x_ms:用於決定的時間間隔 (以毫秒為單位) 是否應加快控制器的旋轉速度,以增加旋轉量。如果 這個差距和上一個旋轉角度之間的間隔小於這個值。 系統會將之視為 3 次旋轉將這項設定設為 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_focusedtrue,但 「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 汽車、 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 汽車、 Android 12)
下列資源可用來指出聚焦按下檢視區塊的時機:

  • car_ui_rotary_focus_pressed_fill_color:填滿顏色。
  • car_ui_rotary_focus_pressed_stroke_color:外框顏色。
  • car_ui_rotary_focus_pressed_stroke_width:外框的粗細。

有時按鈕會呈現純色的背景顏色,吸引使用者的注意力。 如以下範例所示這可能會導致焦點標示難以辨識。

單色背景的按鈕
圖 2. 使用單色背景的按鈕

在這種情況下,開發人員可以使用 secondary 顏色:
  • (Android 11 QPR3、Android 11 汽車、 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

任何顏色都可以透明,而且任一尺寸可以是零。舉例來說,假設您 讓模型只包含填滿或輪廓

焦點區域醒目顯示

(Android 11 QPR3、Android 11 汽車、 Android 12)
FocusArea 焦點。如有需要,您可以為兩者合併使用。這項功能在 Android 開放原始碼計畫,但可透過覆寫 car-ui-library 資源啟用這項功能:

  • car_ui_enable_focus_area_foreground_highlight:在以下位置繪製醒目提示: FocusArea 及其子系。在 Android 開放原始碼計畫中,這個可繪項目為外框 FocusArea周圍。原始設備製造商 (OEM) 可覆寫 car_ui_focus_area_foreground_highlight 可繪項目。
  • car_ui_enable_focus_area_background_highlight:在 FocusArea,但落後其子系的區塊。在 Android 開放原始碼計畫中,這個可繪項目為純填滿。 原始設備製造商 (OEM) 可以覆寫 car_ui_focus_area_background_highlight 可繪項目。

輸入法編輯器

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

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

(Android 11 QPR3、Android 11 汽車、 Android 12)
如果原始設備製造商 (OEM) 已建立旋轉專用的輸入法編輯器,則他們應指定 rotary_input_method 資源中的 ComponentName。如果這項資源 圖片重疊,每當使用者與車用運算主機互動時,系統就會使用指定的輸入法編輯器 即可透過旋轉控制器的微調、旋轉和中間按鈕操作。使用者輕觸時 螢幕,系統會使用先前的輸入法編輯器。「返回」按鈕 (以及旋轉項目上的其他按鈕) 控制器) 的值對於選擇輸入法編輯器沒有影響。如果這項資源未重疊,則不會切換輸入法編輯器 會發生什麼事Carboard 不支援旋轉功能,因此使用者無法透過旋轉手勢輸入文字 控制器。

RotaryIME 是範例旋轉輸入法編輯器。雖然基本原則 嘗試使用上述的自動輸入法編輯器切換功能。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 汽車、 Android 12)
    config_showHeadsUpNotificationOnBottom:代表是否採用的布林值 抬頭通知應顯示在底部,而非頂端。這必須 值與 config_showHeadsUpNotificationOnBottom 相同 布林資源位於 frameworks/base/packages/CarSystemUI/res/values/config.xml
  • (Android 11 QPR3、Android 11 汽車、 Android 12)
    notification_headsup_card_margin_horizontal:下列項目的左邊界和右邊界 抬頭通知視窗。這個值必須與 「notification_headsup_card_margin_horizontal」縮小資源範圍 packages/apps/Car/Notification/res/values/dimens.xml
  • (Android 12)。
    excluded_application_overlay_window_titles:陣列 不應視為重疊視窗的視窗標題。其中應包含標題 代表 TaskViewsTaskDisplayAreas 的應用程式視窗。 根據預設,這份清單只包含「地圖」。

您可以重疊下列 RotaryService 資源:

  • (Android 11 QPR3、Android 11 汽車、 Android 12)
    long_press_ms:整數值,代表 按住中間的按鈕必須長按。0 表示系統 應使用預設的長按逾時設定。這是預設值。