fuchsia.input.virtualkeyboard

添加时间：7

协议

控制器

在 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 flexible

类型：uint32

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

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

名称值说明
0

这些文字可能同时包含字母和数字 字符。这是枚举的默认值（零值），因此未初始化的枚举实例可让键盘用户在可输入的内容方面具有最大的灵活性。
1

文本可能只包含数字字符。
2

该文本可能同时包含数字字符， 和用于电话号码的标点符号（例如“*”、“#”}）。

VisibilityChangeReason 柔性

类型：uint32

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

说明可能会添加虚拟键盘的原因，或 呈现给用户的界面。

名称值说明
1

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

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