flamo
开始使用
菜单
插件文档APIArtifactPlayground价格开始使用 ↗

文档/ FlamoArtifact

Artifact 参考

查询设计结构、变量、脚本与组件的字段定义。使用左侧目录或搜索，定位类型、必填项和说明。

当前合同FlamoArtifactschemaVersion: "0.1"65 个字段

Overview

持久化结构，不是运行时实例

FlamoArtifact 保存可版本化、传输和验证的设计、组件、行为与资源事实。运行状态、Canvas 和 GPU 资源由挂载后的 Instance 持有。

最小结构
const artifact = defineFlamoArtifact({
  kind: 'flamo.artifact',
  schemaVersion: '0.1',
  scene: { format: 'flamo-scene-v0', nodes: [] },
})

根对象

FlamoArtifact

Artifact 根合同。区分持久化事实、运行时 Instance 与宿主资源。

artifact

documentation

#
{ ... }可选

定义 documentation 的持久化结构与 Runtime 读取合同。

来源：runtime/src/2d/artifact/types.ts:386

kind

#
"flamo.artifact"必填

固定为 flamo.artifact，用于在加载前识别 Artifact。

来源：runtime/src/2d/artifact/types.ts:387

schemaVersion

#
string必填

Artifact schema 版本。读取方应按版本迁移或拒绝未知合同。

来源：runtime/src/2d/artifact/types.ts:388

source

#
FlamoArtifactSource可选

可选的来源与版本信息。

来源：runtime/src/2d/artifact/types.ts:389

scene

#
FlamoArtifactScene必填

必填的规范化场景；Runtime 从这里创建可渲染节点。

来源：runtime/src/2d/artifact/types.ts:390

tokens

#
FlamoArtifactTokens可选

可选的设计变量图与变量绑定。

来源：runtime/src/2d/artifact/types.ts:391

prototype

#
PrototypeRuntimeArtifact可选

可选的页面原型、导航与 Smart Animate 运行时事实。

来源：runtime/src/2d/artifact/types.ts:392

controlSurface

#
FlamoArtifactControlSurface可选已废弃

旧版根级公共控制面，仅用于迁移读取；新内容应使用节点边界和 exports。

来源：runtime/src/2d/artifact/types.ts:398

nodeArtifacts

#
Record<string, FlamoNodeArtifact>可选

以稳定节点 key 索引的组件、行为和宿主能力。

来源：runtime/src/2d/artifact/types.ts:399

pageSettings

#
Record<string, FlamoPageSettings>可选

Page-scoped Preview/Runtime settings keyed by the CANVAS node id.

来源：runtime/src/2d/artifact/types.ts:401

exports

#
Record<string, FlamoArtifactExport>可选

以公开名称索引的组件导出边界。

来源：runtime/src/2d/artifact/types.ts:402

metadata

#
FlamoArtifactMetadata可选

Artifact 的名称、描述和时间信息。

来源：runtime/src/2d/artifact/types.ts:403

来源信息

FlamoArtifactSource

记录 Artifact 从哪里产生，便于同步、诊断和来源追踪。

source

source.type

#
FlamoArtifactSourceType必填

来源类型：figma、penpot、manual、ai 或自定义来源。

来源：runtime/src/2d/artifact/types.ts:11

source.id

#
string可选

来源系统中的稳定标识。

来源：runtime/src/2d/artifact/types.ts:12

source.name

#
string可选

便于显示和诊断的来源名称。

来源：runtime/src/2d/artifact/types.ts:13

source.url

#
string可选

可追溯到原始设计或内容的 URL。

来源：runtime/src/2d/artifact/types.ts:14

source.version

#
string可选

来源版本、revision 或同步版本。

来源：runtime/src/2d/artifact/types.ts:15

场景

FlamoArtifactScene

Runtime 可物化的规范化场景节点集合。

scene

scene.format

#
"flamo-scene-v0"必填

固定为 flamo-scene-v0 的场景编码标识。

来源：runtime/src/2d/artifact/types.ts:19

scene.nodes

#
FigmaSceneNode[]必填

规范化场景节点数组；节点层级由节点自身的关系字段表达。

来源：runtime/src/2d/artifact/types.ts:20

设计变量

FlamoArtifactTokens

Artifact 内嵌的设计变量入口。

tokens

tokens.format

#
"flamo-tokens-v0"必填

固定为 flamo-tokens-v0 的 token 编码标识。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:105

tokens.schemaVersion

#
string必填

Token schema 版本。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:106

tokens.variables

#
FlamoVariableGraph可选

可选变量图，包含 collection、variable 与 binding。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:107

变量图

FlamoVariableGraph

变量集合、变量、绑定与默认模式组成的持久化图。

tokens.variables

tokens.variables.collections

#
Record<string, VariableCollectionDef>必填

以 collection id 索引的变量集合。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:91

tokens.variables.variables

#
Record<string, VariableDef>必填

以 variable id 索引的变量定义。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:92

tokens.variables.bindings

#
Record<string, VariableBindingDef>可选

把变量连接到组件属性或场景属性的绑定表。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:93

tokens.variables.defaults

#
{ ... }可选

按 collection 记录默认激活 mode。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:94

tokens.variables.provenance

#
{ ... }可选

变量图的来源与提取时间等证据。

来源：runtime/src/2d/dataTransformation/VariableRegistry.ts:97

原型交互

PrototypeRuntimeArtifact

从设计原型编译出的页面、交互与图层匹配事实。

prototype

prototype.source

#
"figma"必填

当前原型编译来源固定为 figma。

来源：runtime/src/2d/prototype/types.ts:70

prototype.nodesById

#
Record<string, FigmaSceneNode>必填

原型执行所需节点的 id 索引。

来源：runtime/src/2d/prototype/types.ts:71

prototype.frames

#
PrototypeFrameArtifact[]必填

参与原型的 frame 摘要。

来源：runtime/src/2d/prototype/types.ts:72

prototype.screenFrameIds

#
string[]必填

可作为页面 screen 的 frame id。

来源：runtime/src/2d/prototype/types.ts:73

prototype.startingFrameId

#
string可选

默认起始 frame；缺失时由宿主选择。

来源：runtime/src/2d/prototype/types.ts:74

prototype.interactions

#
PrototypeInteractionArtifact[]必填

已编译的触发与动作列表。

来源：runtime/src/2d/prototype/types.ts:75

prototype.matchableLayersByFrame

#
Record<string, PrototypeMatchableLayer[]>必填

供 Smart Animate 跨 frame 匹配图层的索引。

来源：runtime/src/2d/prototype/types.ts:76

公共控制面

FlamoArtifactControlSurface

组件参数、事件、命令和 slot 的公开边界；优先挂在组件边界或 export 上。

nodeArtifacts.*.surface

nodeArtifacts.*.surface.componentPropertiesVersion

#
"1.0"可选

组件公共属性合同版本。

来源：runtime/src/2d/artifact/types.ts:195

nodeArtifacts.*.surface.parameters

#
Record<string, FlamoControlParameterDefinition>可选

可读写参数及其 schema、默认值和 Runtime 绑定。

来源：runtime/src/2d/artifact/types.ts:196

nodeArtifacts.*.surface.events

#
Record<string, FlamoControlEventDefinition>可选

组件向宿主发出的公开事件。

来源：runtime/src/2d/artifact/types.ts:197

nodeArtifacts.*.surface.imperative

#
Record<string, FlamoControlImperativeDefinition>可选

宿主可以调用的命令式方法。

来源：runtime/src/2d/artifact/types.ts:198

nodeArtifacts.*.surface.slots

#
Record<string, FlamoControlSlotDefinition>可选

基于 W3C slot 语义的内容出口与上下文合同。

来源：runtime/src/2d/artifact/types.ts:199

节点能力

FlamoNodeArtifact

与场景节点关联的组件、行为、后端和来源能力。

nodeArtifacts.*

nodeArtifacts.*.role

#
FlamoNodeArtifactRole必填

节点在 Artifact 中的角色：component、instance、composition、local 或 leaf。

来源：runtime/src/2d/artifact/types.ts:350

nodeArtifacts.*.boundary

#
boolean可选

是否是一个可寻址的组件或组合边界。

来源：runtime/src/2d/artifact/types.ts:351

nodeArtifacts.*.of

#
string可选

实例或派生节点指向的来源节点。

来源：runtime/src/2d/artifact/types.ts:352

nodeArtifacts.*.initialComponentSetSelection

#
FlamoComponentSetSelection可选

Component Set 实例首次物化时的精确 Variant 选择。

来源：runtime/src/2d/artifact/types.ts:358

nodeArtifacts.*.capabilities

#
FlamoNodeArtifactCapability[]可选

该节点声明的可执行或可导出能力。

来源：runtime/src/2d/artifact/types.ts:359

nodeArtifacts.*.surface

#
FlamoArtifactControlSurface可选

节点边界的公开参数、事件、命令与 slot。

来源：runtime/src/2d/artifact/types.ts:360

nodeArtifacts.*.overlay

#
{ ... }可选

实例局部 props、slots、overrides 与 events 覆盖。

来源：runtime/src/2d/artifact/types.ts:361

nodeArtifacts.*.scripts

#
FlamoNodeScriptRef[]可选

与节点关联的组合、注册、生成或托管脚本。

来源：runtime/src/2d/artifact/types.ts:367

nodeArtifacts.*.interactions

#
FlamoBehaviorBinding[]可选

精确版本的 Behavior 绑定与 role 映射。

来源：runtime/src/2d/artifact/types.ts:368

nodeArtifacts.*.componentSet

#
FlamoComponentSetDefinition可选

Component Set 的 axes、variants 与初始 Variant。

来源：runtime/src/2d/artifact/types.ts:369

nodeArtifacts.*.motion

#
unknown[]可选

节点关联的动效描述。

来源：runtime/src/2d/artifact/types.ts:370

nodeArtifacts.*.bindings

#
Record<string, unknown>可选

领域扩展使用的节点绑定表。

来源：runtime/src/2d/artifact/types.ts:371

nodeArtifacts.*.roles

#
Record<string, string>可选

从语义 role 到节点的映射。

来源：runtime/src/2d/artifact/types.ts:372

nodeArtifacts.*.backend

#
FlamoNodeBackendConfig可选

选择 Flamo 或 HtmlSurface 后端及其资源配置。

来源：runtime/src/2d/artifact/types.ts:373

nodeArtifacts.*.provenance

#
{ ... }可选

节点能力的来源、状态与解析时间。

来源：runtime/src/2d/artifact/types.ts:374

组件导出

FlamoArtifactExport

把组件边界以稳定名称和可选 Custom Element 标签公开。

exports.*

exports.*.name

#
string必填

公开导出名称。

来源：runtime/src/2d/artifact/types.ts:209

exports.*.boundaryNodeId

#
string必填

导出所指向的组件边界节点 id。

来源：runtime/src/2d/artifact/types.ts:210

exports.*.tagName

#
string可选

作为 W3C Custom Element 发布时使用的标签名。

来源：runtime/src/2d/artifact/types.ts:211

exports.*.surface

#
FlamoArtifactControlSurface可选

内联的公开控制面。

来源：runtime/src/2d/artifact/types.ts:212

exports.*.surfaceRef

#
FlamoArtifactRef可选

对节点 Artifact 内公共控制面的引用。

来源：runtime/src/2d/artifact/types.ts:213

exports.*.defaultOverlay

#
Record<string, unknown>可选

实例化该 export 时使用的默认覆盖。

来源：runtime/src/2d/artifact/types.ts:214

元数据

FlamoArtifactMetadata

供人类与工具识别 Artifact 的非运行时元数据。

metadata

metadata.id

#
string可选

面向工具链的 Artifact 稳定标识。

来源：runtime/src/2d/artifact/types.ts:219

metadata.name

#
string可选

面向用户显示的名称。

来源：runtime/src/2d/artifact/types.ts:220

metadata.description

#
string可选

Artifact 的用途与内容说明。

来源：runtime/src/2d/artifact/types.ts:221

metadata.createdAt

#
string可选

ISO 8601 创建时间。

来源：runtime/src/2d/artifact/types.ts:222

metadata.updatedAt

#
string可选

ISO 8601 最近更新时间。

来源：runtime/src/2d/artifact/types.ts:223