Fuchsia.element

添加时间：7

协议

AnnotationController

在 fuchsia.element/annotations.fidl 中定义

用于创建、读取、更新和删除注解的接口，通常位于元素或其视图上。

GetAnnotations

返回元素当前的 Annotations。

  • 如果无法返回注解，则会发生 GetAnnotationsError 错误。

请求

<EMPTY>

响应

名称类型
payload AnnotationController_GetAnnotations_Result

UpdateAnnotations

添加、更新和移除注释。

服务器应遵循以下规范：

  • 如果 annotations_to_set 中的键是新键，系统会添加新注解
  • 如果 annotations_to_set 中的键已存在，则系统会更新注解值
  • 如果 annotations_to_delete 中的某个键不存在，系统会忽略该键

在对 UpdateAnnotations() 的调用中，同一个键不能出现两次。换句话说，设置两个具有匹配键的 Annotation 是非法的，因为尝试设置 Annotation 并同时删除 Annotation 也是如此。

如果操作导致错误，注释将保持不变，也不会部分更新。

  • 如果 annotations_to_set 和 annotations_to_delete 中存在相同的键，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果 annotations_to_set 或 annotations_to_delete 中的键具有空的命名空间，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果 annotations_to_set 中的 AnnotationValue.buffer 无法读取，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果操作导致存在超过 MAX_ANNOTATIONS_PER_ELEMENT 个注解，则会发生 UpdateAnnotationsError.TOO_MANY_ANNOTATIONS 错误。

请求

名称类型
annotations_to_set Annotations
annotations_to_delete AnnotationKeys

响应

名称类型
payload AnnotationController_UpdateAnnotations_Result

WatchAnnotations

当一个或多个 Annotations 发生更改时，或者客户端首次调用此方法时，返回完整的 Annotations 集。

此操作不会阻止来自客户端的其他请求，但一次只能在连接上发出一个 WatchAnnotations 请求。如果客户端在等待上一个请求完成之前发出第二个 WatchAnnotations 请求，则连接将关闭。

  • 如果无法返回注解，则会发生 WatchAnnotationsError 错误。

请求

<EMPTY>

响应

名称类型
payload AnnotationController_WatchAnnotations_Result

控制器

在 fuchsia.element/element_manager.fidl 中定义

一个接口，可让 Manager 的客户端（元素建议者）控制所提议元素的生命周期和注解。

生命周期

客户端必须保持 Controller 连接，以确保元素保留在会话中且不被销毁。关闭 Controller 后，元素及其组件将终止。元素也可能会自行终止，这会导致 Controller 关闭。

GetAnnotations

返回元素当前的 Annotations。

  • 如果无法返回注解，则会发生 GetAnnotationsError 错误。

请求

<EMPTY>

响应

名称类型
payload AnnotationController_GetAnnotations_Result

UpdateAnnotations

添加、更新和移除注释。

服务器应遵循以下规范：

  • 如果 annotations_to_set 中的键是新键，系统会添加新注解
  • 如果 annotations_to_set 中的键已存在，则系统会更新注解值
  • 如果 annotations_to_delete 中的某个键不存在，系统会忽略该键

在对 UpdateAnnotations() 的调用中，同一个键不能出现两次。换句话说，设置两个具有匹配键的 Annotation 是非法的，因为尝试设置 Annotation 并同时删除 Annotation 也是如此。

如果操作导致错误，注释将保持不变，也不会部分更新。

  • 如果 annotations_to_set 和 annotations_to_delete 中存在相同的键，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果 annotations_to_set 或 annotations_to_delete 中的键具有空的命名空间，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果 annotations_to_set 中的 AnnotationValue.buffer 无法读取，则会发生 UpdateAnnotationsError.INVALID_ARGS 错误。
  • 如果操作导致存在超过 MAX_ANNOTATIONS_PER_ELEMENT 个注解，则会发生 UpdateAnnotationsError.TOO_MANY_ANNOTATIONS 错误。

请求

名称类型
annotations_to_set Annotations
annotations_to_delete AnnotationKeys

响应

名称类型
payload AnnotationController_UpdateAnnotations_Result

WatchAnnotations

当一个或多个 Annotations 发生更改时，或者客户端首次调用此方法时，返回完整的 Annotations 集。

此操作不会阻止来自客户端的其他请求，但一次只能在连接上发出一个 WatchAnnotations 请求。如果客户端在等待上一个请求完成之前发出第二个 WatchAnnotations 请求，则连接将关闭。

  • 如果无法返回注解，则会发生 WatchAnnotationsError 错误。

请求

<EMPTY>

响应

名称类型
payload AnnotationController_WatchAnnotations_Result

GraphicalPresenter

在 fuchsia.element/graphic_presenter.fidl 中定义

用于指示服务器呈现图形视图以及观察和控制视图生命周期的界面。

PresentView

显示 view_spec 描述的视图。

如果提供了 view_controller_request，则会连接到由 GraphicalPresenter 服务器实现的 ViewController。关闭视图后，ViewController 通道会通过 ZX_OK 关闭，此时可以安全地清理支持该视图的资源。如需关闭视图，客户端应调用 ViewController.Dismiss() 并等待 ZX_OK 摘要。未提供 view_controller_request 句柄会导致客户端无法观察视图的生命周期。

  • view_spec 描述要呈现的视图
  • annotation_controller 是 AnnotationController 的句柄，可让 GraphicalPresenter 服务器观察和更新视图的注解。
  • view_controller_request：针对视图控制器的可选请求
  • 错误 view_spec 对于 Gfx 视图必须包含 view_holder_token 和 view_ref，或对于 Flatland 视图包含 viewport_creation_token，但绝不能同时包含两者。如果两者都设置了，则返回错误 PresentViewError.INVALID_ARGS。
  • 如果 spec.view_holder_token 或 spec.view_ref 缺失或无效，则会发生 PresentViewError.INVALID_ARGS 错误。

请求

名称类型
view_spec ViewSpec
annotation_controller AnnotationController?
view_controller_request server_end<ViewController>?

响应

名称类型
payload GraphicalPresenter_PresentView_Result

经理

在 fuchsia.element/element_manager.fidl 中定义

用于向会话添加元素的接口。

元素是一个组件，应被实例化为会话的子项，并（可选）以某种方式与用户互动。

会话通常会实现 Manager 并根据需要进行路由。为使 ffx session add 等工具正常运行，会话必须向其父级公开 Manager。

例如，会话中的组件可能是非交互式应用，它会监听网络以获取向用户显示元素的命令。收到命令后，该组件会调用 ProposeElement()。

ProposeElement

添加时间：19

请求

名称类型
spec Spec
controller server_end<Controller>?

响应

名称类型
payload Manager_ProposeElement_Result

RemoveElement

从会话中移除 name 标识的元素。如果该元素是持久性元素，系统会将其永久移除。元素可能已使用的任何永久性存储空间不会受到影响。

添加时间：19

请求

名称类型
name string

响应

名称类型
payload Manager_RemoveElement_Result

ViewController

在 fuchsia.element/graphic_presenter.fidl 中定义

让 GraphicalPresenter 的客户端能够控制通过 PresentView() 呈现的单个视图。

关闭

指示 Presenter 关闭关联的视图。一旦被忽略，ViewController 通道会以 ZX_OK 标题标记关闭。此时，您可以放心地清理支持视图的所有资源（例如终止组件）。

客户端应在自行关闭 ViewController 通道之前调用 Dismiss()。

请求

<EMPTY>

OnPresented

一个事件，表示正在呈现视图。

响应

<EMPTY>

结构体

注解 resource

在 fuchsia.element/annotations.fidl 中定义

由键值对动态定义的注解。

会话框架不会以任何方式限制 key 和 value 的内容。交换注释的协作组件必须根据自己的惯例定义和验证注释条目。

字段类型说明默认
key AnnotationKey

此注释的标识符。

 无默认设置
value AnnotationValue

此注释的内容。

 无默认设置

AnnotationController_GetAnnotations_Response 资源

在 fuchsia.element/annotations.fidl 中定义

字段类型说明默认
annotations Annotations 无默认设置

AnnotationController_UpdateAnnotations_Response

在 fuchsia.element/annotations.fidl 中定义

<EMPTY>

AnnotationController_WatchAnnotations_Response 资源

在 fuchsia.element/annotations.fidl 中定义

字段类型说明默认
annotations Annotations 无默认设置

AnnotationKey

在 fuchsia.element/annotations.fidl 中定义

fuchsia.element/Annotation 的键。

字段类型说明默认
namespace string[128]

用于消除各客户端间的键组歧义的命名空间。

这是为了将相关键归到同一标识符下，并避免命名冲突。例如，会话可能会使用自定义命名空间来定义特定于其实现的注释。

命名空间为必填项，且不得为空。

命名空间“global”表示全局命名空间，为许多产品和会话组件中通用的注释保留。

为确保兼容性，在引入新密钥时，客户端应使用唯一的命名空间，如 UUID 或客户端的组件网址。

 无默认设置
value string[128]

此注解的标识符，用于在 namespace 中唯一标识该注解。

 无默认设置

GraphicalPresenter_PresentView_Response

在 fuchsia.element/graphic_presenter.fidl 中定义

<EMPTY>

Manager_ProposeElement_Response

在 fuchsia.element/element_manager.fidl 中定义

<EMPTY>

Manager_RemoveElement_Response

在 fuchsia.element/element_manager.fidl 中定义

<EMPTY>

精英

GetAnnotationsError 严格

类型：uint32

在 fuchsia.element/annotations.fidl 中定义

ElementController/GetAnnotations 返回的错误。

名称值说明
1

无法读取注解的 AnnotationValue.buffer。

ManagerError 严格

类型：uint32

在 fuchsia.element/element_manager.fidl 中定义

添加时间：19

名称值说明
1

元素规范格式错误。
2

无法解析元素的组件网址。
3

由于写入永久性存储空间时出现问题，因此无法保留建议的元素。建议的元素尚未开始。

PresentViewError 严格

类型：uint32

在 fuchsia.element/graphic_presenter.fidl 中定义

当 GraphicalPresenter 无法显示视图时返回的错误。

名称值说明
1

提供的 ViewSpec 无效。

ProposeElementError strict

类型：uint32

在 fuchsia.element/element_manager.fidl 中定义

使用 Manager 协议时可能返回的错误。

移除了：19 个

名称值说明
1

元素规范格式错误。
2

无法解析元素的组件网址。

UpdateAnnotationsError 严格

类型：uint32

在 fuchsia.element/annotations.fidl 中定义

从 AnnotationController/UpdateAnnotations 返回的错误

名称值说明
1

传递给 UpdateAnnotations 的参数格式不正确。
2

更新注解后，注解总数将超过 MAX_ANNOTATIONS_PER_ELEMENT。

WatchAnnotationsError 柔性

类型：uint32

在 fuchsia.element/annotations.fidl 中定义

从 AnnotationController/WatchAnnotations 和 ElementController/WatchAnnotations 返回的错误。

名称值说明
1

无法读取注解的 AnnotationValue.buffer。

表

规范 resource

在 fuchsia.element/element_manager.fidl 中定义

要添加到会话的元素的说明。

序数字段类型说明
component_url fuchsia.url/Url

元素的组件网址。必选。
annotations Annotations

元素的初始注解。必需，但可以是空矢量。如果包含元素管理器网址注解（允许，但并非必需），则它必须与 component_url 匹配。

ViewSpec 资源

在 fuchsia.element/graphic_presenter.fidl 中定义

可由 GraphicalPresenter 呈现的视图的说明。

序数字段类型说明
view_holder_token fuchsia.ui.views/ViewHolderToken

所呈现 Gfx 视图的 ViewHolder 令牌。对于 Flatland 视图，必须取消设置此项。必须设置 view_holder_token 或 viewport_creation_token 中的一个。
view_ref fuchsia.ui.views/ViewRef

所呈现的 Gfx 视图的 ViewRef。对于 Flatland 视图，必须取消设置。
annotations Annotations

与所呈现的视图相关联的初始注释。可通过传递到 PresentView() 的 AnnotationController 观察注解的更新。

可选。
viewport_creation_token fuchsia.ui.views/ViewportCreationToken

所呈现 Flatland 视图的视口创建令牌。对于 Gfx 视图，必须取消设置。必须设置 view_holder_token 或 viewport_creation_token 中的一个。

联合体

AnnotationController_GetAnnotations_Result 严格资源

在 fuchsia.element/annotations.fidl 中定义

序数变体类型说明
response AnnotationController_GetAnnotations_Response
err GetAnnotationsError

AnnotationController_UpdateAnnotations_Result strict

在 fuchsia.element/annotations.fidl 中定义

序数变体类型说明
response AnnotationController_UpdateAnnotations_Response
err UpdateAnnotationsError

AnnotationController_WatchAnnotations_Result 严格的资源

在 fuchsia.element/annotations.fidl 中定义

序数变体类型说明
response AnnotationController_WatchAnnotations_Response
err WatchAnnotationsError

AnnotationValue 严格 资源

在 fuchsia.element/annotations.fidl 中定义

fuchsia.element/Annotation 的值。

实际使用的字段取决于注解类型。

序数变体类型说明
text string
buffer fuchsia.mem/Buffer

GraphicalPresenter_PresentView_Result strict

在 fuchsia.element/graphic_presenter.fidl 中定义

序数变体类型说明
response GraphicalPresenter_PresentView_Response
err PresentViewError

Manager_ProposeElement_Result strict

在 fuchsia.element/element_manager.fidl 中定义

序数变体类型说明
response Manager_ProposeElement_Response
err ManagerError

Manager_RemoveElement_Result 严格

在 fuchsia.element/element_manager.fidl 中定义

序数变体类型说明
response Manager_RemoveElement_Response
err ManagerError

常量

名称值类型说明
ANNOTATION_KEY_NAME name String

集合中元素的名称。如果未提供 ProposeElement，则会随机选择一个名称。

添加时间：19
ANNOTATION_KEY_PERSIST_ELEMENT persist_element String

如果存在，则该元素将在重新启动后保留。

添加时间：19
ANNOTATION_KEY_URL url String

元素的组件网址。

添加时间：19
MANAGER_NAMESPACE element_manager String
添加时间：19
MAX_ANNOTATIONS_PER_ELEMENT 1024 uint32

单个元素或视图的注解数量上限。
MAX_ANNOTATION_KEY_NAMESPACE_SIZE 128 uint32

长度上限为 AnnotationKey.namespace。
MAX_ANNOTATION_KEY_VALUE_SIZE 128 uint32

长度上限为 AnnotationKey.value。

别名

名称值说明
AnnotationKeys vector[MAX_ANNOTATIONS_PER_ELEMENT]

注解键列表。
注释 vector[MAX_ANNOTATIONS_PER_ELEMENT]

元素的注解列表。