fuchsia.ui.input3

實體鍵盤事件

Fuchsia 的鍵盤服務提供一項機制，可將實體鍵盤事件提供給所有感興趣的用戶端。

已轉譯的文件

總覽

重要事件只會傳送至透過 Keyboard FIDL 通訊協定訂閱的元件。對服務感興趣的元件應在元件資訊清單中列出 FIDL 服務，並在元件啟動時插入該服務。

常見用途：

  • 按 Tab 鍵切換表單欄位。
  • 使用方向鍵瀏覽選單和清單。
  • 按「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 插入鍵盤子系統的功能。

角色

這個通訊協定通常如下：

  • 由處理及傳送鍵盤事件的平台元件實作。
  • 由產生鍵盤事件的元件使用。例如螢幕小鍵盤或工作階段架構輸入管道。

相關通訊協定

而這個通訊協定應優先於提供類似功能的舊版通訊協定。具體來說，這表示您應該優先使用這個通訊協定

  • 提供 InjectInput()、DispatchKey() 和 DispatchKey3() 的 fuchsia.ui.input.ImeService
  • fuchsia.ui.input.InputMethodEditor，提供 InjectInput() 和 DispatchKey3()

附註

產品應謹慎限制存取這項通訊協定，因為使用這項通訊協定插入的事件無法區分來自實體裝置的事件。

插入

將事件插入鍵盤子系統。

傳回

  • 如果鍵盤子系統將事件傳送給消費者，且取用端回報該事件 HANDLED，則為 HANDLED
  • 如果鍵盤子系統沒有向任何取用者發出事件，或是沒有任何取用者回報該事件的 HANDLED，則為 NOT_HANDLED。

要求

名稱類型
key_event KeyEvent

回應

名稱類型
status KeyEventStatus

鍵盤

定義於 fuchsia.ui.input3/keyboard.fidl

元件可以向其命名空間要求這項服務，藉此接收實體重要事件的通知。

AddListener

為特定檢視畫面新增主要事件監聽器。如果新增多個事件監聽器，每個事件監聽器都會獨立收到按鍵事件，且應使用 Status 回應。

每當需要接收 KeyboardListener 的事件時，呼叫 AddListener 的用戶端應將與 Keyboard 的連線保持有效。中斷與 Keyboard 通訊協定的連線也會終止 KeyboardListener。

要求

名稱類型
view_ref fuchsia.ui.views/ViewRef
listener KeyboardListener

回應

<EMPTY>

KeyboardListener

定義於 fuchsia.ui.input3/keyboard.fidl

用戶端應實作這個通訊協定，以便接收重要事件的通知。

OnKeyEvent

發生重要事件 (例如按鍵或放開) 時呼叫。

通訊協定實作者必須及時傳回「狀態」來回應確認事件，也就是不會對輸入管道造成嚴重延遲 (通常是 10 毫秒)。

傳回 NOT_HANDLED 表示事件可能會提供給其他相關 API 的其他用戶端。

未確認其事件的用戶端最終會中斷連線。

通知只會分派給有焦點的檢視畫面。其他檢視畫面 (包括家長或子項) 將不會透過 OnKeyEvent 明確收到通知。

要求

名稱類型
event KeyEvent

回應

名稱類型
status KeyEventStatus

表情符號

KeyEventStatus strict

類型：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 開始，列舉值空間是根據「Named Key Attribute Values」一節的子編號細分，乘以 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 鍵為第 2 級修飾符)。請參閱 ISO9995-1。

已新增：9
19

Caps Lock (大寫) 鍵。

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

已新增：9
20

按下 Control 或 Ctrl 鍵，即可啟用控制輔助鍵函式來解讀並行或後續的鍵盤輸入內容。

已新增：9
21

函式切換 Fn 鍵。

同時啟用這個鍵與其他鍵，將該鍵的值變更為替代字元或函式。這個按鍵通常會直接在鍵盤硬體中處理，而且通常不會產生按鍵事件。

已新增：9
22

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

啟用這個鍵會切換鍵盤模式，將某些鍵的值變更為替代字元或函式。這個按鍵通常會直接在鍵盤硬體中處理，而且通常不會產生按鍵事件。

已新增：9
23

Meta 鍵，用來啟用中繼輔助鍵函式，以便解讀並行或後續的鍵盤輸入內容。

這個鍵/值會用於 Windows 標誌鍵和 Apple Command 或 ⌘ 鍵。

已新增：9
24

NumLock 或 Number Lock 鍵，用於切換數字鍵盤模式函式來解讀後續的鍵盤輸入。

已新增：9
25

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

已新增：9
26

Shift 鍵，用來啟用 Shift 修飾符函式，解讀並行或後續的鍵盤輸入內容。

已新增：9
27

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

已新增：9
28

符號鎖定鍵。

已新增：9
29

超鍵。舊版修飾符。

已新增：9
30

超級鍵。舊版修飾符。

已新增：9
49

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

水平分頁鍵。
65

刪除遊標前緊鄰的字元 (如果是 LTR 語言，則刪除左側的字元)。
97

向下鍵。
98

向左鍵瀏覽鍵。
99

向右鍵。
100

向上鍵瀏覽鍵。
101

「End」鍵。
102

「主畫面」鍵。
103

「Page Down」鍵。
104

「Page Up」鍵。
24581

Escape 或 Esc 鍵。

已新增：10
24588

「Select」鍵。用於選取要聚焦的工作視窗。

已新增：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 其中至少一個。

序數欄位類型說明
timestamp zx/Time

記錄事件的時間 (以奈秒為單位)，以 CLOCK_MONOTONIC 時間為準。每個重要事件都「必須」提供時間戳記，使用者就能預期該時間戳記一律會顯示。
type KeyEventType

事件類型。
key fuchsia.input/Key

用於識別按鍵忽略修飾符、版面配置、之前的重要事件等，在某些平台上稱為「實體鍵」。如果按鍵事件不是來自實體鍵盤 (例如螢幕小鍵盤)，這個欄位可能會空白。
modifiers Modifiers

事件發生時生效的修飾符。範例：CapsLock 已關閉，使用者依序按下 CapsLock 和 A 鍵，接著放開兩者。事件序列如下：

  1. 類型：按下, 鍵, 鍵：CapsLock, 修飾符：None
  2. 類型：按下, 鍵：A, 修飾符：CapsLock
  3. 類型：Released，鍵：CapsLock，修飾符：CapsLock
  4. 類型：Released、鍵：A、修飾符：CapsLock

CapsLock 已開啟，使用者依序按下 CapsLock 和 A 鍵，接著放開兩者。

  1. 類型： Pressed, 鍵：CapsLock, 修飾符：CapsLock
  2. 類型：按下, 鍵：A, 修飾符：無
  3. 類型：Released、key：CapsLock、修飾符：None
  4. 類型：已發行，鍵：A，修飾符：無
key_meaning KeyMeaning

金鑰的意義。
repeat_sequence uint32

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

如果鍵盤驅動程式庫的輸入即時回應中產生此事件，系統會取消設定。如果透過自動重複機制產生 KeyEvent，則此屬性會設定，並針對每個連續產生的按鍵事件逐一遞增。
lock_state LockState

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

舉例來說，如果開啟 CapsLock 效果 (按下「a」就會產生「A」)，系統會設定鎖定狀態中的對應位元。

注意：LockState 與 CapsLock 輔助鍵是否啟用功能不同。即便 Caps Lock 鍵未啟用，LockState.CAPS_LOCK 也可以啟用。

聯合國

金鑰意義嚴格

定義於 fuchsia.ui.input3/events.fidl

按鍵按下的意義。通常是這個事件插入的 Unicode 碼點，或列舉代表與空白字元對應或無法列印的鍵。

序數Variant類型說明
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」的效果，螢幕會顯示「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 Lock 是否需要將所有字母轉換成大寫)，您的目標是 [LockState]。

有時更特別，為了方便使用者使用，具有「left」和「right」變種版本的修飾符具有特殊位元值，因此如果兩邊的區別並不重要，就可以使用這些值。

名稱值說明
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 修飾符時，就會套用這個設定。