元件資訊清單 (.cml) 參考資料

.cml 檔案包含單一 json5 物件常值,其中包含下列鍵。

在預期使用字串值的地方,通常會列出有效值清單。以下字串值類型會重複使用,且必須遵循特定規則。

.cml 檔案會編譯為 FIDL 線格式 (.cm) 檔案。

字串類型

名稱

功能和元件的子項都會命名。名稱字串可能包含下列一或多個字元:A-Za-z0-9_.-。長度不得超過 255 個半形字元,且開頭不得為 .-

路徑

路徑是一系列名稱,以 / 字元分隔。路徑長度不得超過 4095 個半形字元。整份文件中,

  • 相對路徑的開頭不能為 / 字元。
  • 命名空間和傳出目錄路徑必須以 / 字元開頭。

參考資料

參照字串的格式為 #<name>,其中 <name> 是子項的名稱:

頂層鍵

include

string 陣列 (選用)

選用的 include 屬性會說明要合併至此元件資訊清單的零個或多個其他元件資訊清單檔案。例如:

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

在上述範例中,元件資訊清單會納入 syslog 程式庫提供的資訊清單區塊內容,藉此確保元件在嘗試寫入 syslog 時,能正確執行。依照慣例,這類檔案稱為「資訊清單區塊」,結尾為 .shard.cml

// 開頭的包含路徑相對於 Fuchsia 檢出的來源根目錄。不過,如果包含路徑前方沒有 // (如上例所示),系統會從匯出元件資訊清單碎片的 Fuchsia SDK 程式庫 (//sdk/lib) 中解析路徑。

以下是 Fuchsia 檢查作業中的兩個相等的包含路徑,供您參考:

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

您可以叫用下列指令,查看將 any 及 all include 合併到元件資訊清單檔案後的結果:

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

只要屬性相同,包含功能就能處理參照相同功能的重複 useofferexposecapabilities 宣告。例如:

// 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 屬性,才能選取執行元件的執行器program 部分的其餘格式由該特定執行程式決定。

ELF 執行緒

如果元件使用 ELF 執行元件,則 program 至少必須包含下列屬性:

  • runner:必須設為 "elf"
  • binary:可執行二進位檔的套件相對路徑
  • args (選用):引數清單

範例:

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

如需完整的屬性清單,請參閱:ELF Runner

其他跑者

如果元件使用自訂執行元件,則除了 runner 以外,program 參數內的值只會是執行元件專屬值。執行程式會以鍵/值組合的字典形式接收引數。請參閱所使用的特定執行程式,判斷該執行程式預期收到哪些鍵,以及如何解讀這些鍵。

children

object 陣列 (選用)

children 部分會宣告子項元件執行個體,如「子項元件執行個體」一節所述。

  • name:(string) 子項元件執行個體的名稱,是一或多個下列字元的字串:a-z0-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-z0-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-z0-9_.-。在參照中使用時,名稱會識別此環境。
  • extends:(選用 string) 環境應如何擴充此領域的環境。
    • realm:繼承此元件環境的所有屬性。
    • none:從空白環境開始,不要繼承任何內容。
  • runners:(選用 object 陣列) 在環境中註冊的執行者。物件陣列,其中包含下列屬性:

    • runner:(string) 執行功能的名稱,來源在 from 中指定。
    • from:(string) 執行器功能的來源,可選值如下:
      • 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) 元件程式的傳出目錄中,用來擷取功能的路徑。

    對於 protocolservice,預設為 /svc/${protocol},否則為必要。

    對於 protocol,路徑的目標必須是頻道,通常會使用與這項功能名稱相符的通訊協定。

    對於 servicedirectory,路徑的目標必須是目錄。

    對於 runner,路徑的目標必須是管道,且必須使用通訊協定 fuchsia.component.runner.ComponentRunner

    如果是 resolver,路徑目標「必須」為管道,且「必須」說出通訊協定 fuchsia.component.resolution.Resolver

    對於 dictionary,這是選用項目。如果提供,則為程式提供的 fuchsia.component.sandbox/DictionaryRouter 路徑,應傳回 fuchsia.component.sandbox/DictionaryRef,藉此讓程式可動態提供自身的字典。如果這是 dictionary 的設定,則不允許 offer 使用此字典。

  • rights:(選用 array of string) (僅限 directory) 使用此目錄時,可設定的最大目錄權限

  • from:(選用 string) (僅限 storage) 支援此儲存空間能力的現有目錄能力的來源元件,可以是下列其中一項:

    • parent:元件的父項。
    • self:這個元件。
    • #<child-name>:子元件例項的參照
  • backing_dir:(非必要的 string) (僅限 storage) 備份儲存空間的目錄能力 名稱。功能必須可透過 from 中參照的元件使用。

  • subdir:(選用 string) (僅限 storage) backing_dir 中的子目錄,用於建立各個元件的隔離儲存空間目錄

  • storage_id:(選用 string) (僅限 storage) 用於元件隔離儲存空間的 ID,可選填:

    • 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 設定為「字串」時才會支援。這是字串的大小上限。

  • max_count:(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是向量中的元素數量上限。

  • element:(選用 object) (僅限 configuration) 只有在這項設定 type 為「向量」時才會支援。這是設定向量中的元素類型。

    範例 (簡式類型):

    { 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][fidl-environment-decl] 之一。
    • framework:元件架構執行階段。
    • self:此元件。
    • #<capability-name>:要求的功能所衍生自的其他功能名稱。
    • #<child-name>:子元件例項的參照

    [fidl-environment-decl]: /reference/fidl/fuchsia.component.decl#Environment

  • path:(選用 string) 在元件命名空間中安裝功能的路徑。通訊協定預設為 /svc/${protocol}directorystorage 為必要欄位。如果宣告包含能力名稱陣列和執行元件功能,就不允許使用這個屬性。

  • 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

    詳情請參閱可用性說明文件。

  • 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 為「字串」時支援。這是字串的大小上限。

  • max_count:(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是向量中的元素數量上限。

  • element:(選用 object) (僅限 configuration) 只有在這項設定 type 為「向量」時才會支援。這是設定向量中的元素類型。

    範例 (簡式類型):

    { 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) 能力目標。parentframework。預設為 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 依附元件。此曝光的最終來源必須是 void 或實際元件。
    • same_as_target:這項功能的預期可用性會與目標一致。如果目標需要這項功能,則這個欄位會設為 required。如果目標包含能力上的選用依附元件,則該欄位會設為 optional
    • transitional:類似 optional,但會容許來源缺少的情況。只有在多步驟程式碼變更的過渡期間,才需要使用這個屬性,以免發生驗證錯誤。

    詳情請參閱可用性說明文件。

  • 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:來源經過刻意省略。只有在 availabilityoptionaltransitional 時才有效。
  • to:(string or array of strings) 能力目標。下列其中一項:
    • #<target-name> 或 [#name1, ...]:子項或集合的參照,或參照陣列。
    • all:包含所有子項參照offer 子句的簡寫形式。
  • as:(選用 string) 能力的明確名稱,因為目標會知道該名稱。如果您省略此屬性,系統會預設使用原始名稱。如果提供多個名稱的陣列,則無法使用 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 依附元件。此優惠的最終來源必須為 void 或實際元件。
    • same_as_target:這項功能的預期可用性會與目標一致。如果目標需要這項功能,則這個欄位會設為 required。如果目標對功能有選用依附元件,則欄位會設為 optional
    • transitional:類似 optional,但會容許來源缺少的情況。只有在多步驟程式碼變更的過渡期間,才需要使用這個屬性,以免發生驗證錯誤。

    詳情請參閱可用性說明文件。

  • 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,可使用下列字串之一:booluint8int8uint16int16uint32int32uint64int64stringvector

範例:

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,
        }
    }
}