Fuchsia.ui.views

添加次数：7

协议

对焦器

在 fuchsia.ui.views/focuser.fidl 中定义

一种以编程方式传输 View 焦点的方法。

协议客户端具有对请求者 ViewRef 的隐式访问权限，这可用作请求授权的基础。

RequestFocus

要求服务器在请求者 ViewRef 的授权下将焦点转移到 view_ref 指定的 View。此类请求可能会被拒绝。

如果该请求被接受，并触发了焦点更改，则向新聚焦的视图发出 FocusEvent（聚焦为 true），向上一个视图发出 FocusEvent（焦点为 false）。

结果回调表示已收到并遵循了请求。它无法保证请求的 View 会及时实际收到 FocusEvent。

申请遭拒的原因可能有很多，例如：

  • 如果 view_ref 无效
  • 如果没有由 view_ref 支持的 View
  • 如果聚焦器无法访问请求者 ViewRef
  • 如果请求者 ViewRef 没有对 view_ref 的 View 的授权
  • 如果 view_ref 的视图无法命中或可能无法获得焦点等。系统会返回遭拒的请求并显示一个“错误”。

请求

名称类型
view_ref ViewRef

响应

名称类型
payload Focuser_RequestFocus_Result

SetAutoFocus

将自动对焦目标设置为 view_ref 指定的视图。若要取消设置目标，请传入一个空表。

如果已设置目标，则每当调用方的视图获得焦点时，系统都会尝试立即将焦点转移到目标。如果目标不可聚焦，则新目标将是目标的第一个可聚焦祖先实体。设置自动对焦目标不会限制同时使用 RequestFocus()。

仅当自动对焦目标是 ViewTree 中调用方视图的后代时，它才“有效”。允许指定无效的自动对焦目标，因为它在以后可能会变为有效目标。客户端需负责确保目标是自动对焦的有效接收者。

如果在触发自动对焦行为时目标无效，则移动焦点的尝试将静默失败，焦点会保留在调用方的视图中。目标可能会失效，然后多次失效；自动对焦会在目标处于有效状态时继续发挥作用，并在目标处于无效状态时继续忽略目标。

如果焦点通过某种进一步的自动机制返回到调用方的视图（例如，如果目标不可聚焦），则焦点将会保留在调用方的视图中。

AutoFocusError 目前永远不会返回，且保留以供日后使用。

添加次数：9

请求

名称类型
payload FocuserSetAutoFocusRequest

响应

名称类型
payload Focuser_SetAutoFocus_Result

视图

在 fuchsia.ui.views/view.fidl 中定义

废弃了用于创建视图的 API。请勿使用。

已弃用

演示

为 View 提供指向景观图场景图的连接点。

调用 Present() 时，View 的实现应通过提供 view_token（使用 fuchsia.ui.gfx.CreateResourceCmd 和 fuchsia.ui.gfx.ViewArgs）提供 View 资源，从而在 Views 中创建一个 View 资源。

然后，该实现应使用 fuchsia.ui.gfx.AddChildCmd 将其图形内容附加到新创建的 View 资源。

如果实现已拥有 View 资源（因为之前已调用过 Present()），则应终止连接并报错。

TODO(https://fxbug.dev/42098670)：允许通过新的 Present() 调用更改 View 的父级。

请求

名称类型
view_token ViewToken

ViewRefFocused

在 fuchsia.ui.views/view_ref_focus.fidl 中定义

一种让 ViewRef 创建者能够确定其 ViewRef 在视图树中是否已获得焦点的方法。

协议客户端对其创建的 ViewRef 具有隐式访问权限；协议本身不接受 ViewRef 参数。无论是受信任客户端还是其他客户端，都需要访问视图焦点状态，因此特意将协议降至最低。拥有 ViewRef（以及此协议）并不会授予了解 ViewRef 焦点状态的权限。

观看

设置在隐式 ViewRef 获得或失去焦点时触发的回调。通常，焦点更改的速度较慢，以便回调可以捕获每个过渡。不过，焦点更改可能会快速发生，因此回调可能会将焦点更改历史记录“压缩”为最新的已知焦点状态。

回调会报告上次焦点更改（跨越从其发出到上一个回调发出的时长）。客户端可能会观察以下四种转换中的任何一种：

  • true -> true：ViewRef 至少失去了一次焦点，并在发出回调时已获得焦点。
  • true -> false：ViewRef 至少失去了一次焦点，并且在触发回调时失去了焦点。
  • false -> true：ViewRef 至少已获得一次焦点，并在发出回调时已获得焦点。
  • false -> false：ViewRef 至少获得了一次焦点，并且在触发回调时失去了焦点。

客户端可以避免“焦点抖动”，并始终看到最新状态。每次回调发出都是有意义的，客户端应适当地重新协商与焦点相关的服务（例如 IME）。

流控制：调用方一次最多只允许进行一次进行中的 |Watch| 调用：后续的 |Watch| 调用必须等到确认返回。违规会导致频道关闭。

请求

<EMPTY>

响应

名称类型
state FocusState

ViewRefInstalled

在 fuchsia.ui.views/view_ref_installed.fidl 中定义

一种用于使 ViewRef 持有者能够确定某个 ViewRef 是否已“安装”在视图树中（即它首次以传递方式连接到根视图的时间）的方法。通常，在安装后，视图焦点可能会传输到该 ViewRef。

注意：区分 ViewRef 的已安装状态和当前“连接到视图树”状态非常重要。前者会经历一次状态变更，即从“no”改为“yes”。后者可能会不断变化，具体取决于视图树拓扑。因此，“已安装”并不能暗示“当前已连接到视图树”；即使是假设的“ViewRefConnected”协议从本质上也属于少儿不宜的。

观看

设置在请求的 |view_ref| 安装时触发的回调。

  • 如果尚未安装 |view_ref|，安装时会触发 |Watch| 响应。
  • 如果 |view_ref| 已安装，|Watch| 响应会立即触发。
  • 如果 |view_ref| 无效或变为无效（可能是因为视图被销毁），|Watch| 调用会返回错误。此错误不一定立即发生，但 ViewRef 容器本身可以通过监听 ZX_EVENTPAIR_PEER_CLOSED 来确定 ViewRef 有效性。

流控制：允许调用方对多个 ViewRef 调用多次 |Watch|。每次给客户端的调用最多只有一条响应。

注意：在安装之前，只要 ViewRef 有效，此 |Watch| 调用就会保持活动状态。

请求

名称类型
view_ref ViewRef

响应

名称类型
payload ViewRefInstalled_Watch_Result

结构

Focuser_RequestFocus_Response

在 fuchsia.ui.views/focuser.fidl 中定义

<EMPTY>

Focuser_SetAutoFocus_Response

在 fuchsia.ui.views/focuser.fidl 中定义

<EMPTY>

ViewCreationToken 资源

在 fuchsia.ui.views/flatland_tokens.fidl 中定义

两个 Flatland 实例可以通过父级-子级关系连接。子端点保存在 View 中。此视图与 ViewRef 和其他相关协议密切相关。

ViewCreationToken 是通道的类型化封装容器，表示两个 Flatland 实例之间的连接的子端点。不会通过此通道发送任何消息，因为它仅用作与对等端的不可克隆对象。

字段类型说明默认
value handle<channel> 无默认取景方式

ViewHolderToken 资源

在 fuchsia.ui.views/view_token.fidl 中定义

用于在全局场景图中唯一标识 View 的连接点的令牌。每个 ViewHolderToken 只有一个对应的 ViewToken。

View 客户端可以使用此令牌创建 ViewHolder 资源，从而引用其他客户端中的内容。另一个客户端还必须使用相应的 ViewToken 创建 View 资源。

字段类型说明默认
value handle<eventpair> 无默认取景方式

ViewIdentityOnCreation 资源

在 fuchsia.ui.views/view_ref.fidl 中定义

在创建视图期间自我标识视图的便利数据类型。

ViewRef 用于标识视图，并且可以自由克隆并分发到其他组件。

ViewRefControl 用于实现生命周期通知，不得克隆，也不能分发到其他组件。系统将 ViewRefControl 对象绑定到视图，因此当视图销毁时，ViewRefControl 销毁会向所有 ViewRef 持有者触发 ZX_EVENTPAIR_PEER_CLOSED 信号，从而通知视图终止。

用法：创建 View 时，将 ViewRef 和 ViewRefControl 放入此结构体中，以便它们作为一个单元转到目标组件。这种便捷的结构体可让协议作者将此旅行对描述为一个参数。提高了可读性并减少了处理不当的情况。

字段类型说明默认
view_ref ViewRef

要创建的视图的稳定标识符。

 无默认取景方式
view_ref_control ViewRefControl

生命周期通知机制。

 无默认取景方式

ViewRef 资源

在 fuchsia.ui.views/view_ref.fidl 中定义

ViewRef 是内核对象的句柄，它可以标识整个系统中的唯一 View。同一个视图的两个 ViewRef 具有相同的 KOID。

客户端使用 ViewRef 来识别 View、验证 View 以及接收 View 失效信号。

在创建 View 的过程中，客户端会创建关联的 ViewRef/ViewRefControl 对，并将该对传递给景观（ViewRefControl 如下所述）。客户端必须移除 ViewRef 的信号功能；否则，系统不会创建 View。

客户端可以自由克隆并共享其 ViewRef，甚至在将其发送到 View 之前也是如此。

示例 1. 无障碍功能接受来自客户端的 ViewRef，以对与客户端 View 关联的语义节点和语义操作进行分组。它必须通过 Views 验证客户端的 ViewRef。

示例 2. 我们使用 ViewRefs 创建 FocusChain，它可识别在 View 层次结构中被视为“获得焦点”的 View。当某个 View 被销毁时，Scenic 会向所有 FocusChain 持有者发出信号，指明 ViewRef 现在无效。

字段类型说明默认
reference handle<eventpair> 无默认取景方式

ViewRefControl 资源

在 fuchsia.ui.views/view_ref.fidl 中定义

ViewRefControl 与 ViewRef 对等。已关联 reference。

与 ViewRef 一样，ViewRefControl 是事件对的类型化句柄。与 ViewRef 不同，ViewRefControl 的句柄是唯一的。当 View 将 ViewRefControl 与 View 绑定（被安排共享命运）时，会使用此属性。当某个 View 被销毁时，与其 ViewRefControl 的相关销毁会触发一个自动发送给所有 ViewRef 持有者的 ZX_EVENTPAIR_PEER_CLOSED 信号；因此 ViewRef 持有者可以跟踪 View 生命周期。

在创建 View 的过程中，客户端会创建关联的 ViewRef/ViewRefControl 对，并将该对传递给景观（如上文所述）。客户端不得克隆 ViewRefControl。而不得移除或修改 ViewRefControl 的功能；否则不会创建 View。

字段类型说明默认
reference handle<eventpair> 无默认取景方式

ViewRefInstalled_Watch_Response

在 fuchsia.ui.views/view_ref_installed.fidl 中定义

<EMPTY>

ViewToken 资源

在 fuchsia.ui.views/view_token.fidl 中定义

唯一标识 View（全局场景图中子图的根点）的令牌。每个 ViewToken 只有一个对应的 ViewHolderToken。

可以使用此令牌创建 View 资源，以便系统从其他客户端引用它的内容。另一个客户端还必须使用相应的 ViewHolderToken 创建 ViewHolder 资源。

字段类型说明默认
value handle<eventpair> 无默认取景方式

ViewportCreationToken 资源

在 fuchsia.ui.views/flatland_tokens.fidl 中定义

两个 Flatland 实例可以通过父级-子级关系连接。父端点位于视口中。

ViewportCreationToken 是通道的类型化封装容器，表示两个 Flatland 之间连接的父端点。系统不会通过此通道发送任何消息，因为它仅用作与对等端的不可克隆对象。

字段类型说明默认
value handle<channel> 无默认取景方式

枚举

AutoFocusError灵活

类型：uint32

在 fuchsia.ui.views/focuser.fidl 中定义

添加次数：9

名称值说明

错误严格

类型：uint32

在 fuchsia.ui.views/focuser.fidl 中定义

Focuser.RequestFocus 上发生的问题情况。

名称值说明
1

RequestFocus 遭到拒绝时返回的值。

ViewRefInstallError 严格

类型：uint32

在 fuchsia.ui.views/view_ref_installed.fidl 中定义

与 |ViewRefinstalled| 相关的一系列错误代码。

名称值说明
1

所监控的 ViewRef 无效，或已失效。

表

FocusState

在 fuchsia.ui.views/view_ref_focus.fidl 中定义

ViewRef 的焦点状态。

序数字段类型说明
focused bool

说明 ViewRef 是已获得焦点 (true) 还是失去焦点 (false)。

必填字段。

FocuserSetAutoFocusRequest 资源

在 fuchsia.ui.views/focuser.fidl 中定义

序数字段类型说明
view_ref ViewRef

联合

命令严格

在 fuchsia.ui.views/commands.fidl 中定义

请勿使用 - 为了保证 ABI 稳定性，在 fuchsia.ui.scenic.Command 中保留

已弃用：10
序数变体类型说明
empty int32

Focuser_RequestFocus_Result 严格

在 fuchsia.ui.views/focuser.fidl 中定义

序数变体类型说明
response Focuser_RequestFocus_Response
err Error

Focuser_SetAutoFocus_Result 严格

在 fuchsia.ui.views/focuser.fidl 中定义

序数变体类型说明
response Focuser_SetAutoFocus_Response
err AutoFocusError

ViewRefinstalled_Watch_Result 严格

在 fuchsia.ui.views/view_ref_installed.fidl 中定义

序数变体类型说明
response ViewRefInstalled_Watch_Response
err ViewRefInstalledError