协议

控制器

在 fuchsia.input.virtualkeyboard/virtual_keyboard.fidl 中定义

提供控制虚拟键盘的功能。

抽象模型

虚拟键盘一次最多由一个控制器“拥有”。 所有者是控制方，其关联的 View 处于聚焦状态。如果不存在此类控制器，则虚拟键盘将处于无主状态（并隐藏）。

只有自有控制器可以修改虚拟键盘的配置。 当所属控制器失去焦点时，此协议的实现者将自动关闭虚拟键盘。

角色

此协议通常为：

• 由控制键盘可见性的平台组件实现。
• 由应用运行时占用。例如 Flutter、Chromium。

相关协议

• 此协议不提供对虚拟键盘输出的访问权限。为此，请参阅以下协议之一：
  • fuchsia.ui.input3.Keyboard（针对按键）
  • fuchsia.ui.input.InputMethodEditor（用于文本编辑）
• 此协议适用于虚拟键盘的使用方/用户。键盘的实现者/所有者应使用下面的 Manager。

实现人员注意事项

理想情况下，只有在关联的 View 获得焦点时，才允许调用此协议的方法。不过，此协议的实现者和使用方会分别接收焦点更改通知，并不能保证 Controller 实现者会在 Controller 使用方之前获知焦点更改。

因此，由于上述竞态条件，禁止在 View 未聚焦时进行调用可能会错误地拒绝有效调用。相反，实现应该按照方法的注释中所述缓冲请求。

请求隐藏

请求隐藏键盘。

• 如果被调用方确定此 Controller 的 View 已获得焦点，则被调用方会立即应用更改。
• 如果被调用方确定此 Controller 的 View 未获得焦点，则：
  • 如果存在待处理的 RequestShow()，被调用方将取消该请求。
  • 否则，调用将不起作用。
• 对此方法的调用具有幂等性。

请求

<空>

请求显示

请求将键盘设为可见。

• 如果被调用方确定此 Controller 的 View 已获得焦点，则被调用方会立即应用更改。
• 如果被调用方确定此 Controller 的 View 未获得焦点，则被调用方会在 View 重新获得焦点时应用更改。但是，调用 RequestHide() 会导致此类待处理的请求失效。
• 对此方法的调用具有幂等性。

请求

<空>

SetTextType

请求更改虚拟键盘的文本类型。

• 如果被调用方确定此 Controller 的 View 已获得焦点，则被调用方会立即应用更改。
• 如果被调用方确定此 Controller 的 View 未获得焦点，则被调用方会在 View 重新获得焦点时应用更改。
• 如果被调用方在 View 重新获得焦点之前收到多个调用，则被调用方将应用最近一次调用的值。

请求

名称	类型
text_type	TextType

手表可见性

等待可见性发生变化，然后报告新值。

• 当被调用方收到来自此控制器的 RequestShow() 调用后，如果被调用方尚未请求显示键盘，会返回 true。

  • 此状态可能发生在显示键盘之前。
  • 这种情况可能发生于此控制器的 View 获得焦点之前。

• 当被调用方决定隐藏此控制器请求的键盘时，会返回 false。

  • 这可能是由于调用 RequestHide() 而导致的，或者在 View 失去焦点时隐式发生。
  • 当键盘仍显示在屏幕上时，该函数可能会返回。

• 第一次调用立即返回...

  • 如果被调用方已根据来自此控制器的请求决定应显示键盘（这无法保证键盘在屏幕上可见），则为 true
  • 否则为 false

请求

<空>

回复

名称	类型
is_visible	bool

控制器创建者

在 fuchsia.input.virtualkeyboard/virtual_keyboard.fidl 中定义

提供获取 Controller 的功能。

此协议旨在（通过 ViewRef）将 Controller 绑定到 View。绑定可让键盘子系统利用其 View 焦点知识来限制 Controller 何时会影响虚拟键盘配置。

请注意，Controller 本身允许配置虚拟键盘的呈现方式（可见性和布局），但与文本事件无关。如需了解详情，请参阅 Controller 文档。

角色

此协议通常为：

• 由控制界面政策的平台组件实现。
• 由应用运行时占用。例如 Flutter、Chromium。

创建

请求将 server_end:Controller 频道另一端的 Controller 与 view_ref 引用的 View 相关联。

调用 Controller.RequestShow() 时，Controller 实现器将尝试提供针对 text_type 输入进行了优化的键盘（除非类型已被调用 Controller.SetType() 替换）。

ControllerCreator 的实现者应该利用对关联 View 的焦点状态的了解，将访问权限控制应用于对 Controller 进行的调用。如需了解详情，请参阅 Controller 方法的文档。

ControllerCreator 的使用者可以自由断开与 Creator 的连接，而不会影响其控制方。

请求

名称	类型
view_ref	fuchsia.ui.views/ViewRef
text_type	TextType
controller_request	server_end<Controller>

经理

在 fuchsia.input.virtualkeyboard/virtual_keyboard.fidl 中定义

启用虚拟键盘界面，以便与平台同步状态。

角色

此协议通常为：

• 由控制界面政策的平台组件实现。
• 由为文本输入提供 GUI 方式的组件使用。

通知

告知被调用方虚拟键盘的可见性已发生更改，以及触发了更改的原因。

调用方应该等待结果后再调用此方法，以避免被调用方过载。

请求

名称	类型
is_visible	bool
reason	VisibilityChangeReason

回复

<空>

WatchTypeAndVisibility

等待预期 text_type 或可见性发生变化，然后报告新值。为了响应状态更改，调用方应设置请求的类型和可见性，然后调用 Notify 将这一变化告知平台。

第一次调用会立即返回当前预期的 text_type 和可见性。

如果 text_type 不受支持，调用方应实现回退机制，以提供尽可能多的必要键。

请求

<空>

回复

名称	类型
text_type	TextType
is_visible	bool

枚举

TextType 灵活

类型：uint32

在 fuchsia.input.virtualkeyboard/virtual_keyboard.fidl 中定义

描述虚拟键盘将输入的文本类型。

名称	值	说明
字母数字	0	文本可能同时包含字母和数字字符。这是枚举的默认值（零值），因此未初始化的枚举实例可以为键盘用户提供最大的输入灵活性。
数值	1	文本可能仅包含数字字符。
手机	2	文本可能会同时包含数字字符和电话号码所用的标点符号（例如“*”“#”}）。

VisibilityChangeReason（灵活）

类型：uint32

在 fuchsia.input.virtualkeyboard/virtual_keyboard.fidl 中定义

说明在呈现给用户的界面中添加或移除虚拟键盘的原因。

名称	值	说明
程序化	1	由于程序化请求，公开范围发生了变化。例如，GUI 组件对 WatchTypeAndVisibility() 的调用返回了 is_visible 的新值。
用户互动	2	可见性因用户与 GUI 组件的互动而发生变化。例如，用户点按了“关闭”按钮。