本頁面由 Cloud Translation API 翻譯而成。

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

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

鹽

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

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

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

VHAL 應處理以下動作：

自動提醒
旋轉
中間按鈕
返回按鈕
主畫面按鈕
其他按鈕

清脆

當使用者向右推送旋轉控制器時，VHAL 應使用含有下列 int32Values 的 HW_KEY_INPUT 屬性以傳送事件傳送至 Android：

ACTION_DOWN
KEYCODE_SYSTEM_NAVIGATION_RIGHT
目標多媒體廣告：

使用者釋放旋轉控制器時，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

使用者可能會在釋放旋轉控制器前，將旋轉控制器朝向垂直方向推。以下列情境為例：

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

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

保留旋轉控制器時，不應產生任何重複事件會朝一個方向前進

旋轉

使用者以順時針方向旋轉旋轉控制器時 (點按)，VHAL 應使用 HW_ROTARY_INPUT 屬性搭配下列 int32Values 如何傳送事件給 Android：

ROTARY_INPUT_TYPE_SYSTEM_NAVIGATION
一 (1) 人。
目標多媒體廣告：

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

一 (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：

ACTION_DOWN
KEYCODE_DPAD_CENTER
目標多媒體廣告：

使用者釋放旋轉控制器時，VHAL 應使用相同屬性以及 ACTION_UP 的按鍵碼

在按住「中間」按鈕時，不要產生重複事件。

「返回」按鈕

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

ACTION_DOWN
KEYCODE_BACK
目標多媒體廣告：

使用者釋放旋轉控制器時，VHAL 應使用相同屬性以及 ACTION_UP 的按鍵碼

按住「中間」按鈕時，不應產生任何重複事件。

[首頁] 按鈕

處理主畫面按鈕的方式和使用返回按鈕相同，但改為使用 KEYCODE_HOME (共 KEYCODE_BACK 個)。

其他按鈕

如果旋轉控制器包含任何其他按鈕，VHAL 可以處理這些按鈕，原始設備製造商 (OEM) 類似，因此從 Android 的角度來看，這類裝置並不屬於旋轉效果。這類按鈕的處理方式通常是「返回」和「主畫面」按鈕，但按鍵碼不同。例如 KEYCODE_CALL 或 KEYCODE_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_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 汽車、 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：外框的粗細。

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

在這種情況下，開發人員可以使用 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) 可以指定組合：

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

(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：陣列不應視為重疊視窗的視窗標題。其中應包含標題代表 TaskViews 或 TaskDisplayAreas 的應用程式視窗。根據預設，這份清單只包含「地圖」。

您可以重疊下列 RotaryService 資源：

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