Fuchsia.ui.input3

实体键盘事件

Fuchsia 的键盘服务提供了一种机制，可将物理键盘事件提供给所有感兴趣的客户端。

渲染的文档

概览

按键事件仅会传送到通过 Keyboard FIDL 协议订阅的组件。对该服务感兴趣的组件应在组件清单中列出 FIDL 服务，并且会在组件启动时注入该服务。

典型用例：

  • 在表单字段之间使用 Tab 键导航。
  • 使用箭头键在菜单、列表中进行导航。
  • 按“f”可从菜单中打开文件。
  • 关闭 ESC 的弹出式窗口。
  • 游戏中的 WASD 导航。

媒体按钮、快捷方式和文本输入 (IME) 相关事件通过专用界面单独提供。

关键事件仅传送到“Scape 焦点链”中的组件。只有获得焦点的组件才会收到按键事件。

按键事件按根到叶的顺序传送，即首先传送父组件。

父级组件可以通过 KeyboardListener.OnKeyEvent 返回 KeyEventStatus.Handled 来阻止事件传播，从而阻止事件进一步传播。

客户端通过 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 注入键盘子系统的功能。

角色

此协议通常为：

  • 由处理和传递键盘事件的平台组件实现。
  • 由发起键盘事件的组件使用。例如，屏幕键盘或会话框架输入流水线。

相关协议

此协议应优先于提供类似功能的旧版协议使用。具体而言，这意味着此协议应优先于

  • fuchsia.ui.input.ImeService，提供 InjectInput()、DispatchKey() 和 DispatchKey3()
  • 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 严格

类型：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

功能开关 Fn 键。

同时激活此键和另一个键会将该键的值更改为替代字符或函数。该按键通常直接在键盘硬件中处理，且通常不会生成按键事件。

添加数量：9
22

功能锁定（FnLock 或 F-Lock）键。

激活此键可切换键盘模式，将某些键的值更改为备用字符或功能。该按键通常直接在键盘硬件中处理，且通常不会生成按键事件。

添加数量：9
23

Meta 键，用于启用元修饰符函数，以解释并发或后续键盘输入。

此键值用于 Windows 徽标键和 Apple Command 或 ⌘ 键。

添加数量：9
24

NumLock 或数字锁定键，用于切换数字键盘模式功能，以便解释后续的键盘输入。

添加数量：9
25

滚动锁定键，用于在滚动模式和光标移动模式之间切换。

添加数量：9
26

Shift 键，可启用 Shift 辅助键，用于解释并发或后续键盘输入。

添加数量：9
27

符号辅助键（用于某些虚拟键盘）。

添加数量：9
28

符号锁定键。

添加数量：9
29

Hyper 键。旧版修饰符。

添加数量：9
30

超级键。旧版修饰符。

添加数量：9
49

按 Enter 键或 ↵ 键，可激活当前选择或接受当前输入。 该键值还可用于 Return（Macintosh 数字键盘）键。
50

水平制表 Tab 键。
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，辅助键：无
  2. 类型：已按，键：A，辅助键：CapsLock
  3. 类型：已释放，键：CapsLock，辅助键：CapsLock
  4. 类型：已释放，键：A，辅助键：CapsLock

CapsLock 键已开启，用户先按 CapsLock 键，再按 A 键，然后再松开这两个键。

  1. 类型：已按，键：CapsLock，辅助键：CapsLock
  2. 类型：已按下，键：A，辅助键：无
  3. 类型：已释放，键：CapsLock，辅助键：无
  4. 类型：已释放，键：A，辅助键：无
key_meaning KeyMeaning

键的含义。
repeat_sequence uint32

此 KeyEvent 在自动重复的键序列中的序列号。

如果在对键盘驱动程序输入的即时响应过程中生成了此事件，则不设置此政策。如果已通过自动重复机制生成 KeyEvent，则此属性会设置，并针对每个连续生成的按键事件递增 1。
lock_state LockState

事件发生时有效的锁定状态。

例如，如果启用了 CapsLock 效果（按“a”效果为“A”），则系统会设置锁定状态中的相应位。

注意：LockState 不同于是否启动 CapsLock 辅助键。即使当前未激活大写锁定键，LockState.CAPS_LOCK 也可能处于活动状态。

联合

KeyMeaning 严格

在 fuchsia.ui.input3/events.fidl 中定义

按键的含义。这通常是由此事件插入的 Unicode 代码点，或者是表示与空白处对应的键或不可打印的键的枚举。

序数变体类型说明
codepoint uint32

表示所输入字符的 Unicode 代码点（如果有）。

  • 在 Dart 和 Go 中，这对应于 rune。
  • 在 Rust 中，这对应于 char。
  • 在 C 和 C++ 中，这对应于 ICU 的 UChar32。
non_printable_key NonPrintableKey

对于没有对应符号的按键事件的按键含义。

BITS

LockState 灵活

类型：uint64

在 fuchsia.ui.input3/modifiers.fidl 中定义

当前处于活动状态的锁定状态的位字段。

锁定状态会报告处于锁定状态的按键的锁是否处于活动状态（需按下一次即可激活，再按一次即可停用）。设置位表示有效锁定状态。

例如，当大写锁定处于活动状态时（即按“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 输入子系统支持的所有修饰符。

修饰符是一种特殊键，在与其他键结合使用时，它们可以修改其他键的用途或功能。在修饰符类型中，只要特定辅助键被触发（按住），系统就会设置一个位，而不考虑修饰符是否具有关联的锁定状态。

注意：如果要检查锁定状态（例如，大写锁定是否需要将所有字母都转换为大写），则应改用 [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 修饰符时应用。