fuchsia.ui.input3

實體鍵盤事件

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")
    },
}
新增：7

通訊協定

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

系統已處理重要事件，並應停止進一步傳播。
2

系統不會處理按鍵事件，應將其傳遞至其他用戶端或事件監聽器。

KeyEventType 嚴格

類型：uint32

在 fuchsia.ui.input3/events.fidl 中定義的

鍵盤按鍵輸入事件的類型。

我們不希望新的值加入這個列舉中。

名稱值說明
1

已啟動金鑰。

收到這個事件類型，表示金鑰已執行 收到事件的時間戳記；在事件發生期間 收件者已聚焦。

舉例來說，如果鍵是鍵盤鍵 已按下。
2

目前已停止執行金鑰。

如果收到這個事件類型，表示金鑰已撤銷 收到事件的時間戳記；在事件發生期間 收件者已聚焦。

舉例來說，如果鍵是鍵盤鍵 已發布。
3

金鑰在用戶端無法接收時執行了， 而現在用戶端能接收到 重要事件。

以下列舉幾個可能原因：

- A new device was connected while its key was actuated.
- The key was actuated while the event recipient did not
  have focus.

因此，這不是「一般」金鑰動畫回報 因為該金鑰在過去未知了。只有部分通知 因此，活動收件者可能會認為 觸發的重要事件，有些則有可能認定是該事件。

舉例來說，觸發某些使用者動作的收件者可能會 決定忽略 SYNC 事件，避免採取可疑的動作。於 相對地，收件者追蹤鍵盤 您可以將SYNC事件視為信號 更新金鑰的狀態，以便執行。
4

金鑰可能已啟動，但其觸發機制 因金鑰以外的事件而失效 以及欺騙性

以下列舉幾個可能原因：

- A device was disconnected while its key was actuated.
- The event recipient just lost focus.

因此，這不是「一般」的關鍵。回報 由於發生以下事件： 新的金鑰發布部分活動收件者可能會因此決定 這不是可操作的重要事件，有些 最終決定採用

舉例來說，觸發某些使用者動作的收件者可能會 決定忽略 CANCEL 事件，避免採取可疑的動作。於 相對地，收件者追蹤鍵盤 您可以將 CANCEL 事件視為要更新的信號 要撤銷的金鑰狀態

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
18

替代圖形 (AltGr 或 AltGraph)。

此鍵用於啟用 ISO 等級 3 Shift 輔助鍵 (標準 Shift 鍵為等級 2 修飾符)。請參閱 ISO9995-1。

新增：9
19

Caps Lock (大寫) 鍵。

切換大寫字元鎖定函式，以解讀後續的鍵盤輸入事件。

新增：9
20

Ctrl 或 Ctrl 鍵，用於啟用控制輔助鍵功能， 「上一個」鍵盤輸入。

新增：9
21

函式切換功能鍵。

同時啟用這組金鑰，同時讓另一個重要變更將該鍵的值變更為替代金鑰 字元或函式這個按鍵通常是直接在鍵盤硬體中處理，而且需要 通常不會產生重要事件

新增：9
22

函式鎖定 (FnLock 或 F-Lock) 鍵。

啟用這個按鍵會切換鍵盤模式，以變更某些按鍵。」設為 替代字元或函式這個按鍵通常是直接在鍵盤硬體中處理 通常不會產生重要事件

新增：9
23

Meta 鍵，用於啟用中繼輔助鍵來解讀並行或後續的 鍵盤輸入。

這個鍵/值是用於 Windows 標誌鍵和 Apple Command 或 ⌘ 鍵，

新增：9
24

NumLock 或 Number Lock 鍵，可以切換 numpad 模式函式來解讀後續內容 鍵盤輸入。

新增：9
25

捲動鎖定鍵，可切換捲動和遊標移動模式。

新增：9
26

Shift 鍵可用於啟用 Shift 修飾符函式解讀並行或 鍵盤輸入。

新增：9
27

符號輔助鍵 (適用於部分虛擬鍵盤)。

新增：9
28

符號鎖定鍵。

新增：9
29

超鍵。舊版修飾符，

新增：9
30

超級鍵。舊版修飾符，

新增：9
49

按下 Enter 或 ← 可啟用目前的選取項目，或是接受目前的輸入來源。 這個鍵值也適用於 Return (Macintosh numpad) 鍵。
50

水平分頁鍵。
65

刪除緊接在遊標之前的字元 (也就是 字元)。
97

向下鍵瀏覽鍵。
98

向左箭頭瀏覽鍵。
99

向右箭頭瀏覽鍵。
100

向上箭頭瀏覽鍵。
101

「End」鍵。
102

「首頁」鍵。
103

Page Down 鍵鍵。
104

Page Up 鍵鍵。
24581

Escape 或 Esc 鍵。

新增：10
24588

選取鍵。用於選取工作聚焦的視窗。

新增：10
28672

調低亮度鍵。通常用於控制螢幕亮度。

新增：10
28673

「調高亮度」鍵。通常用於控制螢幕亮度。

新增：10
36865

F1 鍵，一般用途功能鍵，為索引 1。

新增：9
36866

F2 鍵，一般用途功能金鑰，為索引 2。

新增：9
36867

F3 鍵，一般用途功能金鑰，為索引 3。

新增：9
36868

F4 鍵，一般用途功能金鑰，為索引 4。

新增：9
36869

F5 鍵，一般用途功能金鑰，為索引 5。

新增：9
36870

F6 金鑰，此為一般用途的功能金鑰，為索引 6。

新增：9
36871

F7 鍵，一般用途功能金鑰，為索引 7。

新增：9
36872

F8 鍵，一般用途函式金鑰，為索引 8。

新增：9
36873

F9 鍵，一般用途函式金鑰，為索引 9。

新增：9
36874

F10 鍵，一般用途函式金鑰，為索引 10。

新增：9
36875

F11 鍵，一般用途功能鍵，為索引 11。

新增：9
36876

F1 鍵，一般用途功能金鑰，為索引 12。

新增：9
36881

一般用途虛擬函式金鑰，如索引 1。

新增：9
36882

一般用途虛擬函式金鑰，如索引 2。

新增：9
36883

一般用途虛擬函式金鑰，如索引 3。

新增：9
36884

一般用途虛擬函式金鑰，為索引 4。

新增：9
40968

暫停目前正在播放的媒體。

注意：媒體控制器裝置應使用這個值，而非 PAUSE 代表暫停鍵。

新增：10
49162

調低音訊音量。

新增：10
49163

調高音訊音量。

新增：10
49164

切換靜音狀態和之前的音量。

新增：10
61440

前往目前記錄中的先前內容或頁面。

新增：10
61441

開啟瀏覽器的最愛清單。

新增：10
61442

前往目前記錄中的下一個內容或頁面。

新增：10
61443

前往使用者的偏好首頁。

新增：10
61444

重新整理目前的頁面或內容。

新增：10
61446
新增：10
73799

切換全螢幕和縮放內容，或修改放大等級。

新增：10

資料表

KeyEvent

在 fuchsia.ui.input3/events.fidl 中定義的

為反映按鍵輸入而產生的鍵盤事件。必須提供 timestamp 和 type。 有效的事件必須至少設定 key 和 key_meaning。

Ordinal欄位類型說明
timestamp zx/Time

記錄事件的時間 (以奈秒為單位)，以 CLOCK_MONOTONIC 時間為基礎。 每個重要事件的時間戳記都是必要項目，使用者也能預期時間戳記 一律顯示在畫面上
type KeyEventType

事件類型。
key fuchsia.input/Key

用於識別按鍵忽略修飾符、版面配置、先前的重要事件等。 「實體金鑰」某些平台的內容並非源自於重要事件 這個欄位可能會空白。
modifiers Modifiers

在事件發生時套用的修飾符。 範例： CapsLock 已關閉。使用者依序按下 CapsLock 鍵和 A 鍵，然後放開這兩個按鍵。 事件順序如下：

  1. 類型：按下，按鍵：CapsLock，輔助鍵：None
  2. 類型：按下，按鍵：A，輔助鍵：CapsLock
  3. type：Released，key: CapsLock,修飾符 s: CapsLock
  4. type：Released，key: A，輔助鍵：CapsLock

CapsLock 已開啟，使用者依序按下 CapsLock 鍵和 A 鍵，然後放開這兩個按鍵。

  1. 類型：按下，按鍵：CapsLock，輔助鍵：CapsLock
  2. 類型：按下，按鍵：A，輔助鍵：無
  3. type：Released，key: CapsLock,修飾符 s: None
  4. type：已釋出，索引鍵：A，修飾符：無
key_meaning KeyMeaning

金鑰的定義。
repeat_sequence uint32

此 KeyEvent 的自動重複序列中的序號 鍵。

如果此事件是在立即回應 輸入字詞即可如果 KeyEvent 已產生 再透過自動重複機制，將這個屬性設為 在每個後續產生的重要事件中遞增 1。
lock_state LockState

事件發生時生效的鎖定狀態。

舉例來說，如果開啟 CapsLock 效果，則在 效果「A」)，已設定鎖定狀態中的對應位元。

注意：LockState 與 CapsLock 修飾符鍵不同 是否存在LockState.CAPS_LOCK 為啟用狀態，即使 目前未啟用 Caps Lock 鍵。

聯合國

金鑰意義嚴格

在 fuchsia.ui.input3/events.fidl 中定義的

按鍵按鍵的意義。通常是插入的 Unicode 碼點 為此事件或是列舉代表鍵 (對應空白字元或 否則無法列印。

OrdinalVariant類型說明
codepoint uint32

代表已輸入字元的 Unicode 碼點 (如果有的話)。

  • 在 Dart 和 Go 中，對應於 rune。
  • 在 Rust 中，這會對應至 char。
  • 在 C 和 C++ 中，這對應到 ICU 的 UChar32。
non_printable_key NonPrintableKey

沒有對應符號的按鍵事件代表性。

商業智慧

LockState 彈性

類型：uint64

在 fuchsia.ui.input3/modifiers.fidl 中定義的

目前為鎖定狀態的位元欄位。

鎖定狀態會回報鎖定狀態的按鍵是否處於鎖定狀態 狀態 (需要按一次才能啟用，再次按下一次即可停用)。 組合位元表示活動鎖定狀態。

舉例來說，如果 Caps Lock 鍵已啟用，也就是按下「a」鍵，會產生 的「A」CAPS_LOCK 位元就會啟用。

選擇 LockState 中的位元值，會對應至 Modifiers，為長時間執行此操作。

名稱值說明
1

在 CAPS_LOCK 修飾符鎖定時套用。

使用者必須注意，CAPS_LOCK 的影響範圍僅限於 主要是字母鍵 (甚至是「英數字元」)。

舉例來說，在 CAPS_LOCK 時按下美國 QWERTY 鍵盤上的 a 「狀態」已鎖定，導致鍵代表「A」，就像 Shift 修飾符一樣 不過，在 CAPS_LOCK 鎖定時按下 [ 會提供 [。 即使 Shift+[ 提供 { 也一樣

字母按鍵的位置，可能會因程式的按鍵對應配置而異 目前用量。
2

在 NUM_LOCK 修飾符鎖定時套用。
4

在 SCROLL_LOCK 修飾符鎖定時套用。
8

在 FUNCTION 修飾符鎖定時套用。
16

在 SYMBOL 修飾符鎖定時套用。

修飾符彈性

類型：uint64

在 fuchsia.ui.input3/modifiers.fidl 中定義的

宣告 Fuchsia 輸入子系統支援的所有修飾符。

修飾符是修改用途或函式的特殊鍵 與其他鍵搭配使用時在修飾符類型中 如果特定輔助鍵啟用 (按住)，會設定位元。 無論修飾符是否具有相關聯的鎖定狀態，都一樣。

注意：如果您要檢查鎖定狀態 (例如 Caps) 鎖頭需要將所有字母轉換為大寫)，請使用 [LockState] 。

有些特殊的修飾符是方便好用的修飾符 有「左」和「右」變種版本具有特殊位元值，可用於 兩個邊的區別沒有影響

名稱值說明
1

在啟用 CAPS_LOCK 修飾符時套用。
2

在啟用 NUM_LOCK 修飾符時套用。
4

在啟用 SCROLL_LOCK 修飾符時套用。
8

在啟用 FUNCTION 修飾符時套用。
16

在啟用 SYMBOL 修飾符時套用。
32

在使用左側 SHIFT 修飾符時套用。
64

系統會在產生正確的 SHIFT 修飾符時套用。
128

系統會在執行 LEFT_SHIFT 或 RIGHT_SHIFT 修飾符時套用。

這個位元遮罩是測試 LEFT_SHIFT 的便利性 或 RIGHT_SHIFT。
256

系統會在啟用左側 ALT 修飾符時套用。
512

系統會在產生正確的 ALT 修飾符時套用。
1024

適用於左側 ALT 或右側 ALT 修飾符

2048

在啟用 ALT_GRAPH 修飾符時套用。
4096

在啟用 LEFT_META 修飾符時套用。
8192

在啟用 RIGHT_META 修飾符時套用。
16384

系統會在執行 LEFT_META 或 RIGHT_META 修飾符時套用。
32768

在啟用 LEFT_CTRL 修飾符時套用。
65536

在啟用 RIGHT_CTRL 修飾符時套用。
131072

系統會在執行 LEFT_CTRL 或 RIGHT_CTRL 修飾符時套用。