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() 时，同一个键不能出现两次。换言之，设置两个具有匹配键的注解是非法的，因为设置注解并将其一并删除是非法的。

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

  • 如果 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。

此操作不会阻止来自客户端的其他请求，但一次只能通过一个连接发出一个 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() 时，同一个键不能出现两次。换言之，设置两个具有匹配键的注解是非法的，因为设置注解并将其一并删除是非法的。

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

  • 如果 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。

此操作不会阻止来自客户端的其他请求，但一次只能通过一个连接发出一个 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 必须包含 view_holder_token 和 view_ref（对于 Gfx 视图）或 viewport_creation_token（对于 Flatland 视图），但绝不能同时包含两者。如果两者都设置了，则会返回错误 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 并在需要时路由它。会话必须将 Manager 公开给其父级，才能让 ffx session add 等工具正常运行。

例如，会话中的某个组件可能是非交互式应用，它会监听网络以获取命令来向用户显示某个元素。收到此命令后，该组件会调用 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 墓碑。此时，您可以放心地清理任何支持该视图的资源（例如终止组件）。

客户端应先调用 Dismiss()，然后再自行关闭 ViewController 通道。

请求

<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 无效。

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 strict 资源

在 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 strict 资源

在 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 严格

在 fuchsia.element/graphic_presenter.fidl 中定义

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

Manager_ProposeElement_Result 严格

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

元素上的注解列表。