ComponentSetNode

组件集是组件的集合，组件集中的组件又称之为变体。组件集的一些行为类似于普通的 Frame，但其所有子节点都是 ComponentNode。

组件集必须至少有一个子节点，没有子节点的组件集将自动删除。

Component set properties

type: 'COMPONENT_SET' [readonly]

节点类型，值为 "COMPONENT_SET"。

clone(): ComponentSetNode

复制组件集为一个新的组件集。其子节点将被复制为新的组件。默认情况下，复制的节点将被放置在 motiff.currentPage 下。

defaultVariant: ComponentNode [readonly]

组件集的默认变体，即绝对位置上最左上角的变体。

Publishable properties

description: string

注释或者描述信息。

documentationLinks: ReadonlyArray<DocumentationLink>

文档链接。

remote: boolean [readonly]

是否来自远程组件库。

key: string [readonly]

远程组件库中的 key，结合 motiff.importComponentByKeyAsync、motiff.importComponentSetByKeyAsync 和 motiff.importStyleByKeyAsync 使用。

getPublishStatusAsync(): Promise<PublishStatus>

在远程组件中的发布状态。

Base node properties

id: string [readonly]

节点的唯一标识符，例如 "42:43"。

parent: (BaseNode & ChildrenMixin) | null [readonly]

返回当前节点的父节点（如果存在）。请注意这是一个只读属性，如需修改父节点关系，请使用 appendChild 方法。

name: string

在图层面板中显示的图层名称。调用 motiff.root.name 将返回当前文件的名称（只读）。

removed: boolean [readonly]

如果节点已被删除则返回 true。对于长时间运行的插件，建议编写防御性代码检查节点是否已被用户删除。

toString(): string

返回节点的字符串表示。此方法仅用于调试目的，请勿在生产环境中依赖其具体输出格式。

remove(): void

从文档中删除此节点及其所有子节点。

Plugin data properties

getPluginData(key: string): string

获取存储在节点或样式上的自定义数据。如果指定 key 不存在，返回空字符串。

setPluginData(key: string, value: string): void

在节点或样式上存储插件私有的自定义数据。

getPluginDataKeys(): string[]

获取存储在节点或样式上的所有自定义数据的 key。

getSharedPluginData(namespace: string, key: string): string

获取存储在节点或样式上的共享数据。如果指定的 namespace 和 key 不存在，返回空字符串。

setSharedPluginData(namespace: string, key: string, value: string): void

在节点或样式上存储可供所有插件访问的共享数据。

getSharedPluginDataKeys(namespace: string): string[]

获取指定 namespace 下所有共享数据的 key。

Scene node properties

visible: boolean

节点在画布上是否可见。

locked: boolean

节点是否被锁定，防止在画布上进行某些用户交互，如选择和拖动。

componentPropertyReferences: { [nodeProperty in 'visible' | 'characters' | 'mainComponent']?: string} | null

附加在此节点上的所有组件属性。只有当节点是组件或实例的子图层时，节点才可以有 componentPropertyReferences。否则将为 null。键值对中的值指的是由包含组件、组件集或主组件（对于实例）上的 componentPropertyDefinitions 返回的组件属性名称。

Children-related properties

children: ReadonlyArray<SceneNode> [readonly]

包含所有子节点的数组，按照从后到前的顺序排列：

• 数组中的第一个元素是最底层的图层
• 数组中的最后一个元素是最顶层的图层

appendChild(child: SceneNode): void

在子节点数组末尾添加新的子节点，新节点在视觉上位于所有其他子节点的最上层。

insertChild(index: number, child: SceneNode): void

在子节点数组的指定位置插入新的子节点。

findChildren(callback?: (node: SceneNode) => boolean): SceneNode[]

搜索节点的直接子节点（不包括子节点的子节点）。返回所有满足条件的节点。

findChild(callback: (node: SceneNode) => boolean): SceneNode | null

搜索节点的直接子节点，返回第一个满足条件的节点。

findAll(callback?: (node: SceneNode) => boolean): SceneNode[]

搜索整个节点树（包括当前节点的所有后代节点）。返回所有满足条件的节点。

findOne(callback: (node: SceneNode) => boolean): SceneNode | null

搜索整个节点树，返回第一个满足条件的节点。

findAllWithCriteria<T extends NodeType[]>(criteria: FindAllCriteria<T>): Array< { type: T[number] } & SceneNode>

搜索整个节点树，返回满足所有指定条件的节点。

Frame-related properties

layoutGrids: ReadonlyArray<LayoutGrid>

用于此节点的布局网格的 LayoutGrid 数组。

gridStyleId: string

此节点关联的 GridStyle 的 ID。如果一个 FrameNode 有关联的 gridStyleId，那么它额 layoutGrids 属性就是该 GridStyle 的 layoutGrids。

clipsContent: boolean

是否裁剪其内容。即 Frame 内的图层是否在 Frame 的边界之外可见。

guides: ReadonlyArray<Guide>

Frame 内使用的 Guide 数组。请注意，每个 Frame 都有自己的 Guides，与 Page 上的 Guides 是不相关的。

layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL'

图层的自动布局模式。默认为 "NONE"，即不使用自动布局。

layoutWrap: 'NO_WRAP' | 'WRAP'

图层是否应使用换行自动布局。默认为 "NO_WRAP"。

paddingLeft: number

仅适用于自动布局 Frame。确定 Frame 边框与其子节点之间的左侧填充。

paddingRight: number

仅适用于自动布局 Frame。确定 Frame 边框与其子节点之间的右侧填充。

paddingTop: number

仅适用于自动布局 Frame。确定 Frame 边框与其子节点之间的顶部填充。

paddingBottom: number

仅适用于自动布局 Frame。确定 Frame 边框与其子节点之间的底部填充。

primaryAxisSizingMode: 'FIXED' | 'AUTO'

仅适用于自动布局 Frame。确定主轴是固定长度（由用户确定）还是自动长度（由布局引擎确定）。

counterAxisSizingMode: 'FIXED' | 'AUTO'

仅适用于自动布局 Frame。确定副轴是固定长度（由用户确定）还是自动长度（由布局引擎确定）。

primaryAxisAlignItems: 'MIN' | 'MAX' | 'CENTER' | 'SPACE_BETWEEN'

仅适用于自动布局 Frame。确定自动布局 Frame 的子节点在主轴方向上的对齐方式。

counterAxisAlignItems: 'MIN' | 'MAX' | 'CENTER' | 'BASELINE'

仅适用于自动布局 Frame。确定自动布局 Frame 的子节点在副轴方向上的对齐方式。

counterAxisAlignContent: 'AUTO' | 'SPACE_BETWEEN'

仅适用于 layoutWrap 设置为 "WRAP" 的自动布局 Frame。确定自动布局 Frame 内的换行间距。

itemSpacing: number

仅适用于自动布局 Frame。确定 Frame 的子节点之间的距离。

counterAxisSpacing: number | null

仅适用于 layoutWrap 设置为 "WRAP" 的自动布局 Frame。确定换行间距。值必须为正。

itemReverseZIndex: boolean

仅适用于自动布局 Frame。确定此 Frame 中图层的画布堆叠顺序。当为 true 时，第一个图层将绘制在顶部。

Container-related properties

expanded: boolean

在图层面板中是否展开。

Geometry-related properties

fills: ReadonlyArray<Paint> | motiff.mixed

图层的填充颜色数组。

fillStyleId: string | motiff.mixed

此节点关联的 PaintStyle 的 id。

strokes: ReadonlyArray<Paint>

图层的描边颜色数组。

strokeStyleId: string

此节点关联的 StrokeStyle 的 id。

strokeWeight: number | motiff.mixed

描边的宽度，以像素为单位。此值必须为非负数，并且可以是小数。

strokeJoin: StrokeJoin | motiff.mixed

描边顶点连接点的样式。

strokeAlign: 'CENTER' | 'INSIDE' | 'OUTSIDE'

描边相对于图形边界的对齐方式。

dashPattern: ReadonlyArray<number>

指定交替的破折号和空白长度的数字列表，以像素为单位。

strokeCap: StrokeCap | motiff.mixed

只有一个连接段的顶点的样式。

Corner-related properties

cornerRadius: number | motiff.mixed

图层的圆角半径。

cornerSmoothing: number

圆角的"平滑"程度。范围从 0 到 1。

topLeftRadius: number

topRightRadius: number

bottomLeftRadius: number

bottomRightRadius: number

RectangleNode 或 FrameNode 的四个角可以单独设置圆角半径。与 cornerRadius 一样，这些值必须为非负数，并且可以是小数。如果边长小于圆角半径的两倍，则边的每个顶点的圆角半径将被限制为边长的一半。

Individual strokes-related properties

RectangleNode 或 FrameNode 的四个边可以单独设置描边宽度。与 strokeWeight 类似，这些值必须为非负数，并且可以是小数。要隐藏一侧，可以将值设置为 0。

strokeTopWeight: number

上描边宽度。必须为非负数，并且可以是小数。

strokeBottomWeight: number

下描边宽度。必须为非负数，并且可以是小数。

strokeLeftWeight: number

左描边宽度。必须为非负数，并且可以是小数。

strokeRightWeight: number

右描边宽度。必须为非负数，并且可以是小数。

Blend-related properties

opacity: number

节点的不透明度。必须在 0 到 1 之间。

blendMode: BlendMode

此节点的混合模式。

isMask: boolean

此节点是否为 Mask。Mask 节点会遮罩其后续兄弟节点。

maskType: MaskType

此节点的 mask 类型。默认为 "ALPHA"。更改 maskType 不会设置 isMask 为 true，在使用这个属性时，你需要先判断 isMask。

effects: ReadonlyArray<Effect>

效果数组。

effectStyleId: string

此节点关联的 EffectStyle 的 ID。

Layout-related properties

x: number

节点的水平位置。与 relativeTransform[0][2] 相同。

y: number

节点的垂直位置。与 relativeTransform[1][2] 相同。

width: number [readonly]

节点的宽度。可以使用 resize 方法更改此值。

height: number [readonly]

节点的高度。可以使用 resize 方法更改此值。

minWidth: number | null

仅适用于自动布局 Frame 及其直接子节点。值必须为正。设置为 null 以移除 minWidth。

maxWidth: number | null

仅适用于自动布局 Frame 及其直接子节点。值必须为正。设置为 null 以移除 maxWidth。

minHeight: number | null

仅适用于自动布局 Frame 及其直接子节点。值必须为正。设置为 null 以移除 minHeight。

maxHeight: number | null

仅适用于自动布局 Frame 及其直接子节点。值必须为正。设置为 null 以移除 maxHeight。

relativeTransform: Transform

节点相对于其父节点的位置。

absoluteTransform: Transform [readonly]

节点相对于其所在页面的位置。

absoluteBoundingBox: Rect | null [readonly]

不包括渲染属性（如阴影或描边）的节点边界框。此属性中的 x 和 y 表示节点在页面上的绝对位置。

layoutAlign: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'INHERIT'

仅适用于自动布局 Frame 的直接子节点。确定图层是否应沿父节点的副轴拉伸。默认为 "INHERIT"。

layoutGrow: number

仅适用于自动布局 Frame 的直接子节点。确定图层是否应沿父节点的主轴拉伸。0 对应于固定大小，1 对应于拉伸。

layoutPositioning: 'AUTO' | 'ABSOLUTE'

仅适用于自动布局 Frame 的直接子节点。确定图层的大小和位置是否应由自动布局设置决定或手动调整。

absoluteRenderBounds: Rect | null [readonly]

图层的实际边界框，它包含了阴影、描边等其他实际渲染的内容。如果节点不可见，则此值为 null。

constrainProportions: boolean

调整大小时，是否保持图层的长宽比例。

rotation: number

节点的旋转角度。返回 -180 到 180 之间的值。与 relativeTransform 矩阵中的 Math.atan2(-m10, m00) 相同。设置旋转时，也会设置 m00、m01、m10、m11。

resize(width: number, height: number): void

调整节点的大小。如果节点包含具有约束的子节点，则在调整大小时也会应用这些约束。如果父节点具有自动布局，父节点的大小也会重新计算。

resizeWithoutConstraints(width: number, height: number): void

调整节点的大小，忽略子节点的约束。如果父节点具有自动布局，则导致父节点调整大小（此约束无法忽略）。

rescale(scale: number): void

缩放节点。

constraints: Constraints

相对于其父节点的约束。

Export-related properties

exportSettings: ReadonlyArray<ExportSettings>

存储在节点上的导出设置。

exportAsync(settings?: ExportSettings): Promise<Uint8Array>

exportAsync(settings: ExportSettingsSVGString): Promise<string>

将节点导出为编码后的图像。支持多种导出格式：

• 二进制格式（返回 Uint8Array）
• SVG 字符串格式

Component properties-related properties

componentPropertyDefinitions: ComponentPropertyDefinitions [readonly]

此组件集上存在的所有组件属性及其默认值。'BOOLEAN'、'TEXT' 和 'INSTANCE_SWAP' 属性的名称将会添加以 '#' 开头的唯一标识符的后缀，这有助于快速区分具有相同名称的多个组件属性。整个属性名称应用于所有与组件属性相关的 API 方法和属性。

addComponentProperty(propertyName: string, type: ComponentPropertyType, defaultValue: string | boolean | VariableAlias, options?: ComponentPropertyOptions): string

向此节点添加新的组件属性，并返回带有唯一标识符后缀的属性名称。支持类型为 'BOOLEAN'、'TEXT'、'INSTANCE_SWAP' 或 'VARIANT' 的属性。

editComponentProperty(propertyName: string, newValue: { name: string; defaultValue: string | boolean | VariableAlias; preferredValues: InstanceSwapPreferredValue[] }): string

修改此节点上组件属性的名称、默认值或首选值，并返回带有唯一标识符后缀的属性名称。

支持类型为 'BOOLEAN'、'TEXT'、'INSTANCE_SWAP' 或 'VARIANT' 的属性，具有以下限制：

• name 支持所有属性
• defaultValue 支持 'BOOLEAN'、'TEXT' 和 'INSTANCE_SWAP' 属性，但不支持 'VARIANT' 属性
• preferredValues 仅支持 'INSTANCE_SWAP' 属性

deleteComponentProperty(propertyName: string): void

删除此节点上的组件属性。仅支持类型为 'BOOLEAN'、'TEXT' 或 'INSTANCE_SWAP' 的属性。