fuchsia.input.virtualkeyboard

添加：7

PROTOCOLS

控制器

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

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

抽象模型

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

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

角色

此协议通常由以下平台组件实现：* 控制键盘可见性的平台组件。* 由应用运行时消耗。例如，Flutter、Chromium。

相关协议

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

实施者注意事项

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

因此，当 View 未处于焦点状态时禁止通话，可能会因上述竞态条件而错误地拒绝有效通话。相反，实现应按照各方法注释中的说明缓冲请求。

RequestHide

请求隐藏键盘。

  • 如果被调用方确定相应控制器的 View 处于聚焦状态，则被调用方会立即应用更改。
  • 如果被调用方确定相应控制器的 View 未聚焦，则：
    • 如果存在待处理的 RequestShow()，被调用方会取消该请求。
    • 否则，该调用不会产生任何效果。
  • 对该方法的调用具有幂等性。

请求

<EMPTY>

RequestShow

请求使键盘可见。

  • 如果被调用方确定相应控制器的 View 处于聚焦状态，则被调用方会立即应用更改。
  • 如果被调用方确定相应控制器的 View 未聚焦，则会在 View 重新聚焦时应用更改。不过，对 RequestHide() 的调用会使此类待处理的请求失效。
  • 对该方法的调用具有幂等性。

请求

<EMPTY>

SetTextType

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

  • 如果被调用方确定相应控制器的 View 处于聚焦状态，则被调用方会立即应用更改。
  • 如果被调用方确定相应控制器的 View 未聚焦，则会在 View 重新聚焦时应用更改。
  • 如果被调用方在 View 重新获得焦点之前收到多次调用，被调用方将应用最近一次调用的值。

请求

名称类型
text_type TextType

WatchVisibility

等待公开范围发生变化，然后报告新值。

  • 当此控制器尚未请求显示键盘时，在被调用方从此控制器收到 RequestShow() 调用后，返回 true。

    • 这种情况可能发生在键盘显示在屏幕上之前。
    • 这种情况可能发生在相应控制器的 View 获得焦点之前。

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

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

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

    • true 如果被调用方已决定键盘应因来自此控制器的请求而可见（这并不保证键盘在屏幕上可见）
    • 否则返回 false

请求

<EMPTY>

响应

名称类型
is_visible bool

ControllerCreator

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

提供获取 Controller 的能力。

此协议用于将 Controller 绑定到 View（通过 ViewRef）。该绑定允许键盘子系统利用其对 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 的使用者可以自由断开与创建者的连接，而不会影响其控制器。

请求

名称类型
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

响应

<EMPTY>

WatchTypeAndVisibility

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

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

如果不支持 text_type，调用方应实现一个后备方案，尽可能提供所需的密钥。

请求

<EMPTY>

响应

名称类型
text_type TextType
is_visible bool

枚举

TextType 灵活

类型：uint32

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

描述了预期通过虚拟键盘输入的文本类型。

名称值说明
0

文本可能包含字母字符和数字字符。这是枚举的默认值（零值），因此未初始化的枚举实例可为键盘用户提供最大的输入灵活性。
1

相应文本可能仅包含数字字符。
2

文本可能包含数字字符和电话号码中使用的标点符号（例如“*”“#”）。

VisibilityChangeReason flexible

类型：uint32

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

描述了虚拟键盘可能添加到或从呈现给用户的界面中移除的原因。

名称值说明
1

由于程序化请求，公开范围已更改。例如，GUI 组件对 WatchTypeAndVisibility() 的调用返回了 is_visible 的新值。
2

因用户与 GUI 组件互动而导致可见性发生变化。例如，用户点按了关闭按钮。