Fuchsia.ui.input3

实体键盘事件

Fuchsia 的键盘服务提供了一种提供实体键盘的机制。 所有感兴趣的客户

渲染的文档

概览

关键事件只会传送到通过 Keyboard 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 注入键盘子系统的功能。

角色

此协议通常为：

  • 由处理和提供键盘的平台组件实现 事件。
  • 由发起键盘事件的组件使用。例如： 屏幕键盘或会话框架输入管道。

相关协议

该协议应优先使用，而不是提供 功能类似具体而言，这意味着应首选此协议 超过

  • 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

在发生按键事件（例如按键或释放）时调用。

协议实现者必须通过返回 Status 来做出响应来确认事件 及时处理，即不给整个流程造成严重延误。 输入流水线（通常为 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

大写锁定（大写）键。

切换用于解释后续键盘输入事件的大写字符锁定功能。

添加时间：9
20

Ctrl 或 Ctrl 键，用于启用 Control 辅助键功能以解释并发或 后续键盘输入。

添加时间：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

删除紧接光标前的字符（即 字符）。
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 中的一个。

Ordinal字段类型说明
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即使将 大写锁定键目前未启动。

联合体

关键含义严格

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

按键的含义。这通常是插入 或表示与空格或 采用其他方式无法打印

Ordinal变体类型说明
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 的影响仅限于 主要是字母键（甚至不是字母数字字符）。

例如，按美式 QWERTY 键盘上的 a，同时按 CAPS_LOCK 处于“已锁定”状态，则相应按键会表示 A，就像 Shift 辅助键一样 。不过，在 CAPS_LOCK 处于锁定状态时按 [ 会输出 [， 即使 Shift+[ 返回 {，也是如此。

字母按键的位置可能因 。
2

在 NUM_LOCK 修饰符被锁定时应用。
4

在 SCROLL_LOCK 修饰符被锁定时应用。
8

在 FUNCTION 修饰符被锁定时应用。
16

在 SYMBOL 修饰符被锁定时应用。

修饰符柔性环境

类型：uint64

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

声明 Fuchsia 的输入子系统支持的所有修饰符。

修饰符是特殊键，用于修改用途或功能 与其他键组合使用时在“修饰符”类型中 如果特定的辅助键处于激活状态（按住），则也会设置位； 而不会影响修饰符是否具有关联的锁定状态。

注意：如果您想检查锁定状态（例如， Lock 需要将所有字母变成大写），您需要 [LockState] 。

有点特别，为了方便用户， “左”和“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 修饰符被激活时应用。