實體鍵盤事件
Fuchsia 的鍵盤服務提供實體鍵盤的機制 活動給所有感興趣的客戶。
已轉譯的文件
總覽
按鍵事件只會傳送至透過 Keyboard
FIDL 訂閱的元件
因此效能相當卓越想要使用此服務的元件,應在
系統會在元件啟動時插入這個資訊清單。
常見用途:
- 使用 Tab 鍵瀏覽表單欄位。
- 使用方向鍵瀏覽選單、清單。
- 按下「F」鍵從選單開啟 F 鍵。
- 正在關閉 ESC 的彈出式視窗。
- 遊戲中的 WASD 導覽功能。
提供媒體按鈕、捷徑和文字輸入 (IME) 相關事件 分別透過專用介面單獨取用
系統只會將按鍵事件傳送至瀏覽焦點鏈中的元件。 只有焦點所在的元件會收到重要事件。
重要事件是以根層級到分葉順序 (即父項元件) 提交。
父項元件可透過以下項目,封鎖進一步的事件傳播:
傳回 KeyEventStatus.Handled
,藉此KeyboardListener.OnKeyEvent
,防止
事件的傳播方式。
用戶端會透過 Pressed
收到按下或釋放按鍵的通知,以及
Released
事件類型。
用戶端無法使用時,系統會通知用戶端按下按鍵或放開按鍵
透過 Sync
和 Cancel
事件類型 (例如未聚焦或未開始)。這些
只為相關事件提供,例如按住按鍵
客戶無法使用。
範例
use fidl_fuchsia_ui_input3 as ui_input;
let keyboard = connect_to_protocol::<ui_input::KeyboardMarker>()
.context("Failed to connect to Keyboard service")?;
let (listener_client_end, mut listener_stream) =
create_request_stream::<ui_input::KeyboardListenerMarker>()?;
keyboard.add_listener(view_ref, listener_client_end).await.expect("add_listener");
match listener_stream.next().await {
Some(Ok(ui_input::KeyboardListenerRequest::OnKeyEvent { event, responder, .. })) => {
assert_eq!(event.key, Some(fuchsia_input::Key::A));
responder.send(ui_input::Status::Handled).expect("response from key listener")
},
}
通訊協定
KeyEventInjector
在 fuchsia.ui.input3/keyboard.fidl 中定義的
提供將 KeyEvent
插入鍵盤子系統的功能。
角色
這個通訊協定通常為:
- 由處理及提供鍵盤的平台元件實作 事件。
- 由來源鍵盤事件的元件消耗。例如: 螢幕小鍵盤或 Session Framework 輸入管道
相關通訊協定
這個通訊協定應優先使用,而非提供支援的舊版通訊協定 我們也提供類似功能具體來說,這表示應優先採用這個通訊協定 高於
fuchsia.ui.input.ImeService
,其中提供InjectInput()
、DispatchKey()
。 和DispatchKey3()
fuchsia.ui.input.InputMethodEditor
,提供InjectInput()
和DispatchKey3()
附註
產品插入事件時,應謹慎限制產品對這項通訊協定的存取權 此通訊協定與實體裝置之間的應用程式互不區別。
注入
將事件插入鍵盤子系統。
傳回
HANDLED
:如果鍵盤子系統將事件傳送給消費者, 消費者回報該事件HANDLED
NOT_HANDLED
:如果鍵盤子系統未仰賴事件執行 或消費者都未回報該事件HANDLED
。
要求
名稱 | 類型 |
---|---|
key_event |
KeyEvent
|
回應
名稱 | 類型 |
---|---|
status |
KeyEventStatus
|
鍵盤
在 fuchsia.ui.input3/keyboard.fidl 中定義的
元件可向其命名空間要求此項服務,以接收 實體重要事件。
AddListener
為指定的檢視畫面新增按鍵事件監聽器。
如果新增多個事件監聽器,每個事件監聽器都會各自收到按鍵事件,
應傳回 Status
。
呼叫 AddListener
的用戶端應保持與 Keyboard
的連線保持有效
(前提是需要收到 KeyboardListener
的事件)。捨棄
連至 Keyboard
通訊協定的連線也會終止 KeyboardListener
。
要求
名稱 | 類型 |
---|---|
view_ref |
fuchsia.ui.views/ViewRef
|
listener |
KeyboardListener
|
回應
<空白>
KeyboardListener
在 fuchsia.ui.input3/keyboard.fidl 中定義的
用戶端應實作這項通訊協定,才能收到重要事件的通知。
OnKeyEvent
在發生按鍵事件 (例如按鍵或放開按鍵) 時呼叫。
通訊協定實作者必須透過傳回狀態來回應確認事件 及時更新,例如避免造成嚴重延遲 輸入管道 (通常為 10 毫秒)
傳回 NOT_HANDLED
表示該活動可提供給其他公司
其他相關 API 的用戶端
未確認事件的用戶端最終會中斷連線。
通知只會分派給已聚焦的檢視區塊。沒有其他檢視畫面
包含家長或子女時,系統會透過 OnKeyEvent
收到明確的通知。
要求
名稱 | 類型 |
---|---|
event |
KeyEvent
|
回應
名稱 | 類型 |
---|---|
status |
KeyEventStatus
|
ENUMS
KeyEventStatus 嚴格
類型:uint32
在 fuchsia.ui.input3/keyboard.fidl 中定義的
用戶端按鍵事件監聽器的傳回類型。
我們不希望新的值加入這個列舉。
名稱 | 值 | 說明 |
---|---|---|
手持 |
1 |
系統已處理重要事件,並應停止進一步傳播。 |
NOT_HANDLED |
2 |
系統不會處理按鍵事件,應將其傳遞至其他用戶端或事件監聽器。 |
KeyEventType 嚴格
類型:uint32
在 fuchsia.ui.input3/events.fidl 中定義的
鍵盤按鍵輸入事件的類型。
我們不希望新的值加入這個列舉中。
名稱 | 值 | 說明 |
---|---|---|
已推薦 |
1 |
已啟動金鑰。 收到這個事件類型,表示金鑰已執行 收到事件的時間戳記;在事件發生期間 收件者已聚焦。 舉例來說,如果鍵是鍵盤鍵 已按下。 |
新上架 |
2 |
目前已停止執行金鑰。 如果收到這個事件類型,表示金鑰已撤銷 收到事件的時間戳記;在事件發生期間 收件者已聚焦。 舉例來說,如果鍵是鍵盤鍵 已發布。 |
同步處理 |
3 |
金鑰在用戶端無法接收時執行了, 而現在用戶端能接收到 重要事件。 以下列舉幾個可能原因:
因此,這不是「一般」金鑰動畫回報 因為該金鑰在過去未知了。只有部分通知 因此,活動收件者可能會認為 觸發的重要事件,有些則有可能認定是該事件。 舉例來說,觸發某些使用者動作的收件者可能會
決定忽略 |
取消 |
4 |
金鑰可能已啟動,但其觸發機制 因金鑰以外的事件而失效 以及欺騙性 以下列舉幾個可能原因:
因此,這不是「一般」的關鍵。回報 由於發生以下事件: 新的金鑰發布部分活動收件者可能會因此決定 這不是可操作的重要事件,有些 最終決定採用 舉例來說,觸發某些使用者動作的收件者可能會
決定忽略 |
NonPrintableKey 彈性
類型:uint32
在 fuchsia.ui.input3/events.fidl 中定義的
NonPrintableKey 代表鍵盤上非符號鍵的意義。
每個鍵的定義衍生自 W3C 鍵的已命名值 屬性。
API 9 以上版本
自 API 第 9 版起,列舉值空間將依據 「已命名鍵屬性值」一節的子節數字,相乘 乘以 0x1000
舉例來說,第 3.10 節多媒體鍵的鍵位於何處。
結束時間:0xa000
-0xafff
。存在的值和預留項目
。
已插入邏輯運算子和值
合併到邏輯位置 (請見下文)。這樣一來,
這麼一來,如果基於某些原因能擷取區段範圍
應用程式。
API 第 9 版之前
無法列印的按鍵空間大約會細分,以與 「已命名主要屬性值」一文中第 3 節的子章節。 區段值的選擇是任意選擇,只要 值會同時分配,而用途類似的鍵 。
保留範圍
[NonPrintableKey] 的可能值空間可細分為 並預先將列舉值放在 合適的資料集
- 特殊鍵:0x00-0x10
- 輔助鍵:0x11-0x30
- 空白鍵:0x31-0x40
- 瀏覽鍵:0x61-0x80
- 一般用途函式鍵:0x9000-0x9FFF
名稱 | 值 | 說明 |
---|---|---|
未表明 |
0 |
實作項目無法辨識時,會使用這個鍵/值 硬體、平台或軟體導致 其他的鍵/值 限制。 新增:9
|
替代文案 |
17 |
Alt (替代) 鍵。 這個索引鍵會啟用替代的輔助鍵功能來解讀並行 或執行後續鍵盤輸入動作 這個鍵/值也用於 Apple Option 鍵。 新增:9
|
ALT_GRAPH |
18 |
替代圖形 (AltGr 或 AltGraph)。 此鍵用於啟用 ISO 等級 3 Shift 輔助鍵 (標準 Shift 鍵為等級 2 修飾符)。請參閱 ISO9995-1。 新增:9
|
CAPS_LOCK |
19 |
Caps Lock (大寫) 鍵。 切換大寫字元鎖定函式,以解讀後續的鍵盤輸入事件。 新增:9
|
控制 |
20 |
Ctrl 或 Ctrl 鍵,用於啟用控制輔助鍵功能, 「上一個」鍵盤輸入。 新增:9
|
FN |
21 |
函式切換功能鍵。 同時啟用這組金鑰,同時讓另一個重要變更將該鍵的值變更為替代金鑰 字元或函式這個按鍵通常是直接在鍵盤硬體中處理,而且需要 通常不會產生重要事件 新增:9
|
FN_LOCK |
22 |
函式鎖定 (FnLock 或 F-Lock) 鍵。 啟用這個按鍵會切換鍵盤模式,以變更某些按鍵。」設為 替代字元或函式這個按鍵通常是直接在鍵盤硬體中處理 通常不會產生重要事件 新增:9
|
META |
23 |
Meta 鍵,用於啟用中繼輔助鍵來解讀並行或後續的 鍵盤輸入。 這個鍵/值是用於 Windows 標誌鍵和 Apple Command 或 ⌘ 鍵, 新增:9
|
NUM_LOCK |
24 |
NumLock 或 Number Lock 鍵,可以切換 numpad 模式函式來解讀後續內容 鍵盤輸入。 新增:9
|
SCROLL_LOCK |
25 |
捲動鎖定鍵,可切換捲動和遊標移動模式。 新增:9
|
改變 |
26 |
Shift 鍵可用於啟用 Shift 修飾符函式解讀並行或 鍵盤輸入。 新增:9
|
SYMBOL |
27 |
符號輔助鍵 (適用於部分虛擬鍵盤)。 新增:9
|
SYMBOL_LOCK |
28 |
符號鎖定鍵。 新增:9
|
HYPER |
29 |
超鍵。舊版修飾符, 新增:9
|
上標 |
30 |
超級鍵。舊版修飾符, 新增:9
|
輸入 |
49 |
按下 Enter 或 ← 可啟用目前的選取項目,或是接受目前的輸入來源。 這個鍵值也適用於 Return (Macintosh numpad) 鍵。 |
TAB |
50 |
水平分頁鍵。 |
BACKSPACE |
65 |
刪除緊接在遊標之前的字元 (也就是 字元)。 |
朝下 |
97 |
向下鍵瀏覽鍵。 |
餘額 |
98 |
向左箭頭瀏覽鍵。 |
右 |
99 |
向右箭頭瀏覽鍵。 |
UP |
100 |
向上箭頭瀏覽鍵。 |
結束 |
101 |
「End」鍵。 |
住家 |
102 |
「首頁」鍵。 |
PAGE_DOWN |
103 |
Page Down 鍵鍵。 |
PAGE_UP |
104 |
Page Up 鍵鍵。 |
變造 |
24581 |
新增:10
|
選取 |
24588 |
選取鍵。用於選取工作聚焦的視窗。 新增:10
|
BRIGHTNESS_DOWN |
28672 |
調低亮度鍵。通常用於控制螢幕亮度。 新增:10
|
BRIGHTNESS_UP |
28673 |
「調高亮度」鍵。通常用於控制螢幕亮度。 新增:10
|
F1 鍵 |
36865 |
F1 鍵,一般用途功能鍵,為索引 1。 新增:9
|
F2 |
36866 |
F2 鍵,一般用途功能金鑰,為索引 2。 新增:9
|
F3 |
36867 |
F3 鍵,一般用途功能金鑰,為索引 3。 新增:9
|
F4 |
36868 |
F4 鍵,一般用途功能金鑰,為索引 4。 新增:9
|
F5 |
36869 |
F5 鍵,一般用途功能金鑰,為索引 5。 新增:9
|
F6 鍵 |
36870 |
F6 金鑰,此為一般用途的功能金鑰,為索引 6。 新增:9
|
F7 鍵 |
36871 |
F7 鍵,一般用途功能金鑰,為索引 7。 新增:9
|
F8 |
36872 |
F8 鍵,一般用途函式金鑰,為索引 8。 新增:9
|
F9 |
36873 |
F9 鍵,一般用途函式金鑰,為索引 9。 新增:9
|
F10 |
36874 |
F10 鍵,一般用途函式金鑰,為索引 10。 新增:9
|
F11 |
36875 |
F11 鍵,一般用途功能鍵,為索引 11。 新增:9
|
F12 |
36876 |
F1 鍵,一般用途功能金鑰,為索引 12。 新增:9
|
SOFT_1 |
36881 |
一般用途虛擬函式金鑰,如索引 1。 新增:9
|
SOFT_2 |
36882 |
一般用途虛擬函式金鑰,如索引 2。 新增:9
|
SOFT_3 |
36883 |
一般用途虛擬函式金鑰,如索引 3。 新增:9
|
SOFT_4 |
36884 |
一般用途虛擬函式金鑰,為索引 4。 新增:9
|
MEDIA_PLAY_PAUSE |
40968 |
暫停目前正在播放的媒體。 注意:媒體控制器裝置應使用這個值,而非
新增:10
|
AUDIO_VOLUME_DOWN |
49162 |
調低音訊音量。 新增:10
|
AUDIO_VOLUME_UP |
49163 |
調高音訊音量。 新增:10
|
AUDIO_VOLUME_MUTE |
49164 |
切換靜音狀態和之前的音量。 新增:10
|
BROWSER_BACK |
61440 |
前往目前記錄中的先前內容或頁面。 新增:10
|
BROWSER_FAVORITES |
61441 |
開啟瀏覽器的最愛清單。 新增:10
|
BROWSER_FORWARD |
61442 |
前往目前記錄中的下一個內容或頁面。 新增:10
|
BROWSER_HOME |
61443 |
前往使用者的偏好首頁。 新增:10
|
BROWSER_REFRESH |
61444 |
重新整理目前的頁面或內容。 新增:10
|
BROWSER_SEARCH |
61445 |
打開使用者偏好的搜尋網頁。 新增:10
|
BROWSER_STOP |
61446 |
新增:10
|
ZOOM_TOGGLE |
73799 |
切換全螢幕和縮放內容,或修改放大等級。 新增:10
|
資料表
KeyEvent
在 fuchsia.ui.input3/events.fidl 中定義的
為反映按鍵輸入而產生的鍵盤事件。必須提供 timestamp
和 type
。
有效的事件必須至少設定 key
和 key_meaning
。
Ordinal | 欄位 | 類型 | 說明 |
---|---|---|---|
1 |
timestamp |
zx/Time
|
記錄事件的時間 (以奈秒為單位),以 |
2 |
type |
KeyEventType
|
事件類型。 |
3 |
key |
fuchsia.input/Key
|
用於識別按鍵忽略修飾符、版面配置、先前的重要事件等。 「實體金鑰」某些平台的內容並非源自於重要事件 這個欄位可能會空白。 |
4 |
modifiers |
Modifiers
|
在事件發生時套用的修飾符。 範例: CapsLock 已關閉。使用者依序按下 CapsLock 鍵和 A 鍵,然後放開這兩個按鍵。 事件順序如下:
CapsLock 已開啟,使用者依序按下 CapsLock 鍵和 A 鍵,然後放開這兩個按鍵。
|
5 |
key_meaning |
KeyMeaning
|
金鑰的定義。 |
6 |
repeat_sequence |
uint32
|
此 如果此事件是在立即回應
輸入字詞即可如果 |
7 |
lock_state |
LockState
|
事件發生時生效的鎖定狀態。 舉例來說,如果開啟 CapsLock 效果,則在 效果「A」),已設定鎖定狀態中的對應位元。 注意: |
聯合國
金鑰意義嚴格
在 fuchsia.ui.input3/events.fidl 中定義的
按鍵按鍵的意義。通常是插入的 Unicode 碼點 為此事件或是列舉代表鍵 (對應空白字元或 否則無法列印。
Ordinal | Variant | 類型 | 說明 |
---|---|---|---|
1 |
codepoint |
uint32
|
代表已輸入字元的 Unicode 碼點 (如果有的話)。
|
2 |
non_printable_key |
NonPrintableKey
|
沒有對應符號的按鍵事件代表性。 |
商業智慧
LockState 彈性
類型:uint64
在 fuchsia.ui.input3/modifiers.fidl 中定義的
目前為鎖定狀態的位元欄位。
鎖定狀態會回報鎖定狀態的按鍵是否處於鎖定狀態 狀態 (需要按一次才能啟用,再次按下一次即可停用)。 組合位元表示活動鎖定狀態。
舉例來說,如果 Caps Lock 鍵已啟用,也就是按下「a」鍵,會產生
的「A」CAPS_LOCK
位元就會啟用。
選擇 LockState
中的位元值,會對應至
Modifiers
,為長時間執行此操作。
名稱 | 值 | 說明 |
---|---|---|
CAPS_LOCK |
1 | 在 使用者必須注意, 舉例來說,在 字母按鍵的位置,可能會因程式的按鍵對應配置而異 目前用量。 |
NUM_LOCK |
2 | 在 |
SCROLL_LOCK |
4 | 在 |
FUNCTION_LOCK |
8 | 在 |
SYMBOL_LOCK |
16 | 在 |
修飾符彈性
類型:uint64
在 fuchsia.ui.input3/modifiers.fidl 中定義的
宣告 Fuchsia 輸入子系統支援的所有修飾符。
修飾符是修改用途或函式的特殊鍵 與其他鍵搭配使用時在修飾符類型中 如果特定輔助鍵啟用 (按住),會設定位元。 無論修飾符是否具有相關聯的鎖定狀態,都一樣。
注意:如果您要檢查鎖定狀態 (例如 Caps) 鎖頭需要將所有字母轉換為大寫),請使用 [LockState] 。
有些特殊的修飾符是方便好用的修飾符 有「左」和「右」變種版本具有特殊位元值,可用於 兩個邊的區別沒有影響
名稱 | 值 | 說明 |
---|---|---|
CAPS_LOCK |
1 | 在啟用 |
NUM_LOCK |
2 | 在啟用 |
SCROLL_LOCK |
4 | 在啟用 |
功能 |
8 | 在啟用 |
SYMBOL |
16 | 在啟用 |
LEFT_SHIFT |
32 | 在使用左側 SHIFT 修飾符時套用。 |
RIGHT_SHIFT |
64 | 系統會在產生正確的 SHIFT 修飾符時套用。 |
改變 |
128 | 系統會在執行 這個位元遮罩是測試 |
LEFT_ALT |
256 | 系統會在啟用左側 |
RIGHT_ALT |
512 | 系統會在產生正確的 |
替代文案 |
1024 | 適用於左側 |
ALT_GRAPH |
2048 | 在啟用 |
LEFT_META |
4096 | 在啟用 |
RIGHT_META |
8192 | 在啟用 |
META |
16384 | 系統會在執行 |
LEFT_CTRL |
32768 | 在啟用 |
RIGHT_CTRL |
65536 | 在啟用 |
CTRL |
131072 | 系統會在執行 |