组件清单 (.cml) 参考文档

.cml 文件包含具有以下键的单个 json5 对象字面量。

如果应使用字符串值，通常会记录一系列有效值。 以下字符串值类型会重复使用，并且必须遵循特定规则。

.cml 文件会被编译为 FIDL 传输格式 (.cm) 文件。

字符串类型

姓名

功能和组件的子项均有名称。名称字符串可以由以下一个或多个字符组成：A-Z、a-z、0-9、_、.、-。其长度不得超过 255 个字符，且不得以 . 或 - 开头。

路径

路径是由 [names]{#names} 组成的序列，以 / 字符分隔。路径长度不得超过 4095 个字符。在整个文档中，

• 相对路径不能以 / 字符开头。
• 命名空间和传出目录路径必须以 / 字符开头。

参考编号

引用字符串采用 #<name> 的形式，其中 <name> 是指子项的名称：

• 名称为 <name> 的静态子级实例，或者
• 名称为 <name> 的集合。

顶级键

include

string 数组（可选）

可选的 include 属性描述了要合并到此组件清单中的零个或多个其他组件清单文件。例如：

include: [ "syslog/client.shard.cml" ]

在上述示例中，组件清单包含来自 syslog 库提供的清单分片的内容，以确保该组件尝试写入 syslog 时，在运行时正常运行。按照惯例，此类文件称为“清单分片”，以 .shard.cml 结尾。

以 // 为前缀的包含路径相对于 Fuchsia 签出的源根目录。但是，如上例所示，不带前缀 // 的 include 路径将从导出组件清单分片的 Fuchsia SDK 库 (//sdk/lib) 中进行解析。

作为参考，在 Fuchsia 检出中，以下两个包含路径等效：

• syslog/client.shard.cml
• //sdk/lib/syslog/client.shard.cml

您可以通过调用以下命令查看将任何和全部包含内容合并到组件清单文件中的结果：

fx cmc include cml_file --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib

include 可以应对引用相同 capability 的重复 use、offer、expose 或 capabilities 声明，只要属性相同即可。例如：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.logger.LogSink",
            "fuchsia.posix.socket.Provider",
        ],
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

在此示例中，合并后文件的内容与 my_component.cml 相同，但系统会对 fuchsia.logger.LogSink 进行去重处理。

不过，无法编译：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: "fuchsia.logger.LogSink",
        // properties for fuchsia.logger.LogSink don't match
        from: "#archivist",
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

此约束条件的一个例外情况是 availability 属性。如果两个路由声明相同，并且其中一个可用性强于另一个，可用性将“提升”为较强的值（如果缺少 availability，则默认为 required）。例如：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.logger.LogSink",
            "fuchsia.posix.socket.Provider",
        ],
        availability: "optional",
    },
],

// syslog.client.shard.cml
use: [
    {
        protocol: "fuchsia.logger.LogSink"
        availability: "required",  // This is the default
    },
],

会变为：

use: [
    {
        protocol: "fuchsia.posix.socket.Provider",
        availability: "optional",
    },
    {
        protocol: "fuchsia.logger.LogSink",
        availability: "required",
    },
],

包含项具有传递性，也就是说，分片可以拥有自己的包含项。

包含路径可以包含菱形依赖项。例如，A 包含 B，A 包含 C，B 包含 D，C 包含 D。在这种情况下，A 将传递 B、C、D。

包含路径不能包含循环。例如，以下规则无效：A 包含 B，B 包含 A。 如上所示的循环将导致编译时错误。

disable

object（可选）

disable 部分会停用特定 CML 中由 cmc 强制执行的某些功能。

• must_offer_protocol：（可选 string 数组）列出停用了“--must-offer-protocol”选项的协议。
• must_use_protocol：（可选 string 数组）列出已停用选项“--must-use-protocol”的协议。

示例：

disable: {
    must_offer_protocol: [ "fuchsia.logger.LogSink", "fuchsia.component.Binder" ],
    must_use_protocol: [ "fuchsia.logger.LogSink" ],
}

program

object（可选）

可执行文件包含 program 部分。program 部分必须设置 runner 属性以选择用于运行组件的runner。program 区段其余内容的格式由该特定运行程序决定。

ELF 跑酷游戏

如果该组件使用 ELF 运行程序，program 必须至少包含以下属性：

• runner：必须设置为 "elf"
• binary：可执行二进制文件的软件包相对路径
• args（可选）：参数列表

示例：

program: {
    runner: "elf",
    binary: "bin/hippo",
    args: [ "Hello", "hippos!" ],
},

如需查看完整的属性列表，请参阅：ELF Runner

其他跑步者

如果某个组件使用自定义运行程序，则 program 节中除 runner 以外的值特定于该运行程序。运行程序会以键值对的形式接收参数。请参阅所使用的特定运行程序来确定它预期接收的键以及解读这些键的方式。

children

object 数组（可选）

children 部分声明了子组件实例，如子组件实例中所述。

• name：(string) 子组件实例的名称，它是以下一个或多个字符的字符串：a-z、0-9、_、.、-。在引用中使用时，该名称用于标识此组件。
• url：(string) 子组件实例的组件网址。
• startup：(string) 组件实例的启动模式。以下各项之一：
  • lazy（默认）：仅在另一个组件实例绑定到组件实例时启动组件实例。
  • eager：在组件实例的父级启动时立即启动组件实例。
• on_terminate：（可选 string）确定此组件终止时要应用的故障恢复政策。
  • none （默认）：不执行任何操作。
  • reboot：如果组件因任何原因终止，正常重新启动系统。这是一项仅供一小部分组件使用的特殊功能；如需了解详情，请参阅终止政策。
• environment：（可选 string）如果存在，则为要分配给子组件实例的环境的名称，即 environments 之一。如果省略，子项将继承分配给此组件的同一环境。

示例：

children: [
    {
        name: "logger",
        url: "fuchsia-pkg://fuchsia.com/logger#logger.cm",
    },
    {
        name: "pkg_cache",
        url: "fuchsia-pkg://fuchsia.com/pkg_cache#meta/pkg_cache.cm",
        startup: "eager",
    },
    {
        name: "child",
        url: "#meta/child.cm",
    }
],

collections

object 数组（可选）

collections 部分声明了集合（如组件集合中所述）。

• name：(string) 组件集合的名称，它是包含以下一个或多个字符的字符串：a-z、0-9、_、.、-。在引用中使用时，名称用于标识此集合。
• durability：(string) 集合中子组件实例的持续时间。
  • transient：实例存在，直到其父实例停止或明确销毁。
  • single_run：创建实例时启动实例，并在实例停止时销毁实例。
• environment：（可选 string）如果存在，将分配给此集合中的实例的环境，即 environments 之一。如果省略，此集合中的实例将继承分配给该组件的同一环境。
• allowed_offers：（可选 string）对定位到此集合中组件的动态商品的限制。 调用 fuchsia.component.Realm/CreateChild 时指定动态优惠。
  • static_only：仅限此 .cml 文件中指定的那些。没有动态优惠。 这是默认值。
  • static_and_dynamic：允许使用静态优惠和在运行时使用 CreateChild 指定的优惠。
• allow_long_names：（选填的 bool）：允许子级名称的长度不超过 1024 个字符，而不是通常的 255 个字符。 默认值为 false。
• persistent_storage：（可选 bool）如果设置为 true，则动态子实例及其后代实例使用的隔离存储空间中的数据将在实例销毁后保留。使用相同名称新建的子实例将与前一个实例共用相同的存储路径。

示例：

collections: [
    {
        name: "tests",
        durability: "transient",
    },
],

environments

object 数组（可选）

environments 部分声明了环境中所述的环境。

• name：(string) 环境的名称，是包含一个或多个以下字符的字符串：a-z、0-9、_、.、-。该名称用于在引用中标识此环境。
• extends：（可选 string）环境应如何扩展此领域的环境。
  • realm：从此组件的环境中继承所有属性。
  • none：从空环境开始，不要继承任何内容。

• runners：（可选 object 数组）在环境中注册的运行程序。一个由具有以下属性的对象组成的数组：

  • runner：(string) 运行程序功能的名称，其来源在 from 中指定。
  • from：(string) 运行程序 capability 的来源，可以是以下几项之一：
    • parent：组件的父级。
    • self：此组件。
    • #<child-name>：对子组件实例的引用。
  • as：（可选 string）运行程序的明确名称，因为此环境中将知道此名称。如果省略，则默认为 runner。

• resolvers：（可选的 object 数组）在环境中注册的解析器。一个由具有以下属性的对象组成的数组：

  • resolver：(string) 解析器功能的名称，其来源在 from 中指定。
  • from：(string) 解析器功能的来源，可以是以下几项之一：
    • parent：组件的父级。
    • self：此组件。
    • #<child-name>：对子组件实例的引用。
  • scheme：(string) 解析器应处理解析的网址架构。

• debug：（可选的 object 数组）：通过 use from debug 获取此环境中任何组件可用的调试协议。

  • protocol：（可选 string or array of strings）要提供的协议的名称。
  • from：(string) 功能的来源，可以是以下几项之一：
    • parent：组件的父级。
    • self：此组件。
    • #<child-name>：对子组件实例的引用。
  • as：（可选 string）如果指定，则 protocol 中应可供客户端使用的功能的名称。如果 protocol 为数组，则不允许。

• __stop_timeout_ms：（可选 number）在通知此环境中的组件应终止之后、强制终止该组件之前等待的毫秒数。如果环境从 none 扩展，则必须填写此字段。

示例：

environments: [
    {
        name: "test-env",
        extends: "realm",
        runners: [
            {
                runner: "gtest-runner",
                from: "#gtest",
            },
        ],
        resolvers: [
            {
                resolver: "full-resolver",
                from: "parent",
                scheme: "fuchsia-pkg",
            },
        ],
    },
],

capabilities

object 数组（可选）

capabilities 部分定义了此组件提供的功能。必须在此处声明从 self 提供或公开的功能。

功能字段

它支持以下功能键。您只能设置以下其中一项：

• protocol：（可选 string or array of strings）
• service：（可选 string or array of strings）
• directory：（可选 string）
• storage：（可选 string）
• runner：（可选 string）
• resolver：（可选 string）
• event_stream：（可选 string or array of strings）
• dictionary：（可选 string）
• config：（可选 string）

其他字段

这支持以下附加字段：

• path：（可选 string）在组件程序的传出目录中获取 capability 的路径。

  对于 protocol 和 service，默认值为 /svc/${protocol}，否则为必需项。

  对于 protocol，路径的目标必须是一个通道，该通道往往会读出与此 capability 的名称匹配的协议。

  对于 service 和 directory，路径的目标必须是目录。

  对于 runner，路径的目标必须是通道，并且必须说出协议 fuchsia.component.runner.ComponentRunner。

  对于 resolver，路径的目标必须是通道，并且必须说出协议 fuchsia.component.resolution.Resolver。

• rights：（可选 array of string）（仅限 directory）使用此目录时可设置的最大目录权限。

• from：（可选 string）（仅限 storage）支持此存储功能的现有目录功能的来源组件，可选的值有：

  • parent：组件的父级。
  • self：此组件。
  • #<child-name>：对子组件实例的引用。

• extends：（可选 string）（仅限 dictionary，可选）用于初始化字典的内容。以下各项之一：

  • parent/<relative_path>：parent 提供的字典的路径。
  • #<child-name>/<relative_path>：#<child-name> 公开的字典的路径。
  • self/<relative_path>：由此组件定义的字典的路径。
  • program/<relative_path>：此组件的程序提供的字典的路径。 是程序传出目录中指向 fuchsia.component.sandbox/DictionaryGetter 协议的路径。 <relative_path> 可以是名称，用于标识字典功能，也可以是包含多个部分的路径，用于标识嵌套字典。

• backing_dir：（可选 string）（仅限 storage）支持存储的目录功能的名称。该功能必须可从 from 中引用的组件中使用。

• subdir：（可选 string）（仅限 storage）backing_dir 中的子目录，用于为每个组件创建隔离的存储目录

• storage_id：（可选 string）（仅限 storage）用于组件隔离存储的标识符，可以是以下其中一项：

  • static_instance_id：组件 ID 索引中的实例 ID 用作组件存储的键。未在组件 ID 索引中列出的组件无法使用此存储功能。
  • static_instance_id_or_moniker：如果该组件列在组件 ID 索引中，则实例 ID 将用作组件存储空间的键。否则，系统将使用组件的存储功能名称。

• type：（可选 string）（仅限 configuration）配置类型，可以是以下几项之一：

  • bool：布尔值类型。
  • uint8：无符号 8 位类型。
  • uint16：无符号 16 位类型。
  • uint32：无符号 32 位类型。
  • uint64：无符号 64 位类型。
  • int8：有符号的 8 位类型。
  • int16：有符号的 16 位类型。
  • int32：有符号的 32 位类型。
  • int64：有符号的 64 位类型。
  • string：ASCII 字符串类型。
  • vector：矢量类型。如需了解矢量中元素的类型，请参阅 element。

• max_size：（可选 non-zero number）（仅限 configuration）仅当 type 为“string”配置时才受支持。 这是字符串的大小上限。

• max_count：（可选 non-zero number）（仅限 configuration）仅当此 type 配置为“vector”时才支持。 这是向量中元素的最大数量。

• element：（可选 object）（仅限 configuration）仅当此 type 配置为“vector”时才支持。 这是配置向量中元素的类型。

  示例（简单类型）：

  { type: "uint8" }
  

  示例（字符串类型）：

  {
    type: "string",
    max_size: 100,
  }
  

• value：（可选 any）（仅限 configuration）配置的值。

• delivery：（可选 string）（仅限 protocol）指定当有人请求该功能时，框架何时从此组件的传出目录打开协议。允许的值有：

  • eager：（默认）当某些使用方组件请求该功能时，框架会立即打开该功能。
  • on_readable：当连接请求中流水线的服务器端点变为可读状态时，框架将打开该功能。

use

object 数组（可选）

对于可执行组件，请在运行时在其命名空间中声明此组件所需的功能。除非另有说明，否则系统会从 parent 路由功能，并且每项功能都必须有通过此组件与其来源之间的所有组件的有效路由。

功能字段

它支持以下功能键。您只能设置以下其中一项：

• service：（可选 string or array of strings）
• directory：（可选 string）
• protocol：（可选 string or array of strings）
• dictionary：（可选 string）
• storage：（可选 string）
• event_stream：（可选 string or array of strings）
• runner：（可选 string）
• config：（可选 string）

其他字段

这支持以下附加字段：

• from：（可选 string）功能的来源。默认值为 parent。以下各项之一：
  • parent：组件的父级。
  • debug：环境中分配给此组件的 debug_capabilities 之一。
  • framework：组件框架运行时。
  • self：此组件。
  • #<capability-name>：从中派生请求功能的另一功能的名称。
  • #<child-name>：对子组件实例的引用。
• path：（可选 string）在组件的命名空间中安装功能的路径。对于协议，默认值为 /svc/${protocol}。对于 directory 和 storage 是必需的。对于包含功能名称数组的声明和运行程序功能，不允许使用此属性。
• rights：（可选 array of string）（仅限 directory）应用到组件命名空间中目录的最大目录权限。
• subdir：（可选 string）（仅限 directory）要在组件命名空间中提供的目录功能的子目录。
• scope：（可选 string or array of strings）（仅限 event_stream）定义后，事件流将仅包含与作用域中定义的组件相关的事件。
• filter：（可选 object）（仅限 event_stream）功能请求的事件流需要指定一个过滤器，以引用事件流中的事件适用的协议。过滤器的内容是从“名称”到“协议名称”的对象映射。
• dependency：（可选 string）来源与此组件之间的依赖关系类型，可以是以下几项之一：
  • strong：强依赖项，用于确定关闭顺序。组件管理器一定会先于源停止目标。这是默认值。
  • weak：弱依赖项，在关停期间会被忽略。当组件管理器停止父领域时，来源可能会在客户端之前停止。依赖项较弱的客户端必须能够处理这些依赖项变得不可用的情况。运行程序功能不允许使用此属性，因为运行程序功能始终是 strong 依赖项。

• availability：（可选 string）对此功能可用性的预期。以下各项之一：

  • required（默认值）：必需的依赖项，如果没有此功能，组件将无法执行其工作。
  • optional：可选依赖项，组件可以在没有此功能的情况下运行（但如果该功能不可用，某些功能可能会被停用）。
  • transitional：来源可以完全省略路由，甚至无需从 void 进行路由。用于引入新功能的软转换。运行程序功能（始终为 required）不允许使用此属性。

  如需了解详情，请参阅 [availability][/docs/concepts/components/v2/capabilities/availability.md] 文档。

• key：（可选 string）（仅限 config）此功能将设置的组件 config 代码块中的配置键。

• type：（可选 string）（仅限 config）配置类型，可以是以下几项之一：

  • bool：布尔值类型。
  • uint8：无符号 8 位类型。
  • uint16：无符号 16 位类型。
  • uint32：无符号 32 位类型。
  • uint64：无符号 64 位类型。
  • int8：有符号的 8 位类型。
  • int16：有符号的 16 位类型。
  • int32：有符号的 32 位类型。
  • int64：有符号的 64 位类型。
  • string：ASCII 字符串类型。
  • vector：矢量类型。如需了解矢量中元素的类型，请参阅 element

• max_size：（可选 non-zero number）（仅限 configuration）仅当 type 为“string”配置时才受支持。 这是字符串的大小上限。

• max_count：（可选 non-zero number）（仅限 configuration）仅当此 type 配置为“vector”时才支持。 这是向量中元素的最大数量。

• element：（可选 object）（仅限 configuration）仅当此 type 配置为“vector”时才支持。 这是配置向量中元素的类型。

  示例（简单类型）：

  { type: "uint8" }
  

  示例（字符串类型）：

  {
    type: "string",
    max_size: 100,
  }
  

• default：（可选 any）（仅限 configuration）此配置的默认值。如果相应功能是可选的，则使用默认值，并从 void 路由值。仅当 availability 不是 required 时才支持此操作。

示例：

use: [
    {
        protocol: [
            "fuchsia.ui.scenic.Scenic",
            "fuchsia.accessibility.Manager",
        ]
    },
    {
        directory: "themes",
        path: "/data/themes",
        rights: [ "r*" ],
    },
    {
        storage: "persistent",
        path: "/data",
    },
    {
        event_stream: [
            "started",
            "stopped",
        ],
        from: "framework",
    },
    {
        runner: "own_test_runner".
        from: "#test_runner",
    },
],

expose

object 数组（可选）

声明可供父组件或框架使用的功能。从 self 或子组件 expose 有效。

功能字段

它支持以下功能键。您只能设置以下其中一项：

• service：（可选 string or array of strings）
• protocol：（可选 string or array of strings）
• directory：（可选 string）
• runner：（可选 string）
• resolver：（可选 string）
• dictionary：（可选 string）
• config：（可选 string）

其他字段

这支持以下附加字段：

• from：(string or array of strings) from：功能的来源，可以是以下几项之一：
  • self：此组件。需要相应的 capability 声明。
  • framework：组件框架运行时。
  • #<child-name>：对子组件实例的引用。
• as：（可选 string）功能的名称，因为目标将知道该名称。如果省略，则默认为原始名称。如果提供了包含多个功能名称的数组，则不能使用 as。
• to：（可选 string）功能目标。可以选择 parent 或 framework。默认设置为 parent。
• rights：（可选 array of string）（仅限 directory）要应用到所公开目录功能的最大目录权限。
• subdir：（可选 string）（仅限 directory）源目录功能中要路由的子目录的相对路径。
• event_stream：（可选 string or array of strings）（仅限 event_stream）所公开的事件流的名称。
• scope：（可选 string or array of strings）（仅限 event_stream）所公开的事件流的范围。这用于缩小事件流所引用组件的范围，使其仅引用作用域中定义的组件。

• availability：（可选string）availability（可选）对此功能可用性的预期。此选择会影响构建时和运行时路由验证。以下各项之一：

  • required（默认）：必需的依赖项，来源必须存在并提供。如果此公开的目标需要此功能才能正常运行，请使用此方式。
  • optional：可选依赖项。当公开目标在具有或不具有此功能的情况下均可正常运行时，请使用此属性。目标不能required依赖于 capability。此公开项的最终来源必须是 void 或实际组件。
  • same_as_target：此功能的可用性预期将与目标的可用性预期保持一致。如果目标需要该功能，则此字段会设为 required。如果目标对 capability 有可选的依赖项，则该字段会设为 optional。
  • transitional：与 optional 类似，但可以容忍缺少来源。请仅使用此属性来避免在多步代码更改的过渡期间出现验证错误。

  如需了解详情，请参阅 [availability][/docs/concepts/components/v2/capabilities/availability.md] 文档。

• source_availability：（可选 string）此优惠的来源是否必须存在。以下各项之一：

  • required（默认）：必须在此清单中定义来源 (from)。
  • unknown：如果处理包含内容后，您未在此清单中定义此优惠的来源 (from)，则该优惠的来源将被重写为 void。

示例：

expose: [
    {
        directory: "themes",
        from: "self",
    },
    {
        protocol: "pkg.Cache",
        from: "#pkg_cache",
        as: "fuchsia.pkg.PackageCache",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "self",
    },
    {
        runner: "web-chromium",
        from: "#web_runner",
        as: "web",
    },
    {
        resolver: "full-resolver",
        from: "#full-resolver",
    },
],

offer

object 数组（可选）

声明可供子级组件实例或子集合使用的功能。

功能字段

它支持以下功能键。您只能设置以下其中一项：

• protocol：（可选 string or array of strings）
• service：（可选 string or array of strings）
• directory：（可选 string）
• storage：（可选 string）
• runner：（可选 string）
• resolver：（可选 string）
• event_stream：（可选 string or array of strings）
• dictionary：（可选 string）
• config：（可选 string）

其他字段

这支持以下附加字段：

• service：（可选 string or array of strings）在路由服务时，指服务功能的名称。
• protocol：（可选 string or array of strings）在路由协议时，表示协议功能的名称。
• directory：（可选 string or array of strings）在路由目录时，表示目录功能的名称。
• runner：（可选 string or array of strings）在路由运行程序时，表示运行程序功能的名称。
• resolver：（可选 string or array of strings）在路由解析器时，表示解析器功能的名称。
• storage：（可选 string or array of strings）在路由存储功能时，表示存储功能的名称。
• dictionary：（可选 string or array of strings）在路由字典时，表示字典功能的名称。
• config：（可选 string or array of strings）在路由配置时，表示配置功能的名称。
• from：(string or array of strings) from：功能的来源，可以是以下几项之一：
  • parent：组件的父级。此来源可用于所有功能类型。
  • self：此组件。需要相应的 capability 声明。
  • framework：组件框架运行时。
  • #<child-name>：对子组件实例的引用。此来源只能在提供协议、目录或运行程序功能时使用。
  • void：有意省略来源。仅当 availability 为 optional 或 transitional 时有效。
• to：(string or array of strings) 功能目标。以下各项之一：
  • #<target-name> 或 [#name1, ...]：对子项或集合的引用，或对引用数组的引用。
  • all：包含所有子references的 offer 子句的简写形式。
• as：（可选 string）功能的显式名称，因为目标将知道相应 capability。如果省略，则默认为原始名称。提供由多个名称组成的数组时，无法使用 as。
• dependency：（可选 string）来源与目标之间的依赖关系类型，可以是以下几项之一：
  • strong：强依赖项，用于确定关闭顺序。组件管理器一定会先于源停止目标。这是默认值。
  • weak：弱依赖项，在关停期间会被忽略。当组件管理器停止父领域时，来源可能会在客户端之前停止。依赖项较弱的客户端必须能够应对这些依赖项变得不可用的情况。
• rights：（可选 array of string）（仅限 directory）要应用于所提供的目录功能的最大目录权限。
• subdir：（可选 string）（仅限 directory）源目录功能中要路由的子目录的相对路径。
• event_stream：（可选 string or array of strings）（仅限 event_stream）所提供事件流的名称。
• scope：（可选 string or array of strings）（仅限 event_stream）定义后，事件流将仅包含与作用域中定义的组件相关的事件。

• availability：（可选string）availability（可选）对此功能可用性的预期。此选择会影响构建时和运行时路由验证。以下各项之一：

  • required（默认）：必需的依赖项，来源必须存在并提供。如果此优惠的目标需要此功能才能正常运行，请使用此选项。
  • optional：可选依赖项。如果优惠的目标在无论是否具有此功能的情况下都能发挥作用，请使用此类型。目标不能required依赖于 capability。此优惠的最终来源必须是void或实际组件。
  • same_as_target：此功能的可用性预期将与目标的可用性预期保持一致。如果目标需要该功能，则此字段会设为 required。如果目标对 capability 有可选的依赖项，则该字段会设为 optional。
  • transitional：与 optional 类似，但可以容忍缺少来源。请仅使用此属性来避免在多步代码更改的过渡期间出现验证错误。

  如需了解详情，请参阅 [availability][/docs/concepts/components/v2/capabilities/availability.md] 文档。

• source_availability：（可选 string）此优惠的来源是否必须存在。以下各项之一：

  • required（默认）：必须在此清单中定义来源 (from)。
  • unknown：如果处理包含内容后，您未在此清单中定义此优惠的来源 (from)，则该优惠的来源将被重写为 void。

示例：

offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "#logger",
        to: [ "#fshost", "#pkg_cache" ],
        dependency: "weak",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "#session",
        to: [ "#ui_shell" ],
        dependency: "strong",
    },
    {
        directory: "blobfs",
        from: "self",
        to: [ "#pkg_cache" ],
    },
    {
        directory: "fshost-config",
        from: "parent",
        to: [ "#fshost" ],
        as: "config",
    },
    {
        storage: "cache",
        from: "parent",
        to: [ "#logger" ],
    },
    {
        runner: "web",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        resolver: "full-resolver",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        event_stream: "stopped",
        from: "framework",
        to: [ "#logger" ],
    },
],

facets

object（可选）

包含组件可出于自身目的解读的元数据。组件框架不对此部分强制执行任何架构，但第三方可能希望其分面遵循特定的架构。

config

object（可选）

组件定义的配置架构。每个键表示架构中的一个字段。

配置字段是 JSON 对象，并且必须定义 type（可以是以下字符串之一）：bool、uint8、int8、uint16、int16、uint32、int32、uint64、int64、string、vector

示例：

config: {
    debug_mode: {
        type: "bool"
    },
}

默认情况下，字段通过组件的软件包进行解析。为了能够在运行时更改这些值，需要使用 mutability 说明符。

示例：

config: {
    verbose: {
        type: "bool",
        mutability: [ "parent" ],
    },
},

目前，"parent" 是唯一支持的可变性说明符。

字符串必须将 max_size 属性定义为非零整数。

示例：

config: {
    verbosity: {
        type: "string",
        max_size: 20,
    }
}

矢量必须将 max_count 属性设为非零整数。矢量还必须将 element 属性设为 JSON 对象，用于描述矢量中包含的元素。矢量可以包含布尔值、整数和字符串，但不能包含其他矢量。

示例：

config: {
    tags: {
        type: "vector",
        max_count: 20,
        element: {
            type: "string",
            max_size: 50,
        }
    }
}