OpenPencil SDK 组件解析:用 PropertyList 原语构建 Fills、Strokes 与 Effects 的无头属性列表
OpenPencil SDK 组件解析:用 PropertyList 原语构建 Fills、Strokes 与 Effects 的无头属性列表
PropertyList 是 OpenPencil 可编程 SDK(@open-pencil/vue)中用于属性面板的受控、无头(headless)列表原语,专门服务于填充(Fills)、描边(Strokes)与效果(Effects)三类数组型场景属性。本文以其 API 文档为主体,结合仓库内 packages/vue/src/primitives/PropertyList/ 与 packages/vue/src/controls/property-list/ 的真实实现,讲解它的类型判别机制、五件套解剖结构、受控事件契约,以及如何通过 useEditorPropertyList() 把它接入选择集、多节点更新与撤销批处理。读完你可以在自己的自定义面板、第三方 SDK 应用中直接复刻编辑器内置的属性列表行为。
PropertyList 是什么:受控的无头列表原语
在编辑器属性面板中,填充、描边和效果本质上是挂在场景节点上的数组属性,开发者需要一套统一、可复用的列表 UI 来增删、排序、显隐这些条目。PropertyList 正是为此设计的受控原语:
- 受控(controlled):列表内容完全由外部传入的
items驱动,组件自身不维护数据状态,所有变更通过语义事件回传给宿主; - 无头(headless):组件不预设任何视觉样式与 DOM 结构,只负责状态、类型与事件契约,具体渲染交给调用方的插槽;
- 场景化类型安全:
propKey判别器让插槽和动作获得精确的Fill、Stroke或Effect类型,而不是笼统的Record<string, unknown>。
从源码看,PropertyListRoot 是一个极简的“状态 + 事件”容器:它接收 items 并原样交给默认插槽,同时把 isMixed(混合状态)、disabled、keyOf(行身份)与 actions(动作集合)一并暴露给后代组件(见 PropertyListRoot.vue)。
编辑器内的可变性与撤销行为不在原语内部实现,而是集中在 useEditorPropertyList() 或应用自定义适配器里——这一分层正是 OpenPencil 面板组件“可复用、可替换”的关键:原语只做通用契约,编辑器相关的选择集与撤销逻辑全部外置。
propKey 判别器:让插槽与动作获得精确类型
PropertyList 类型系统的核心是 propKey。在 types.ts 中,这一判别器由一张类型映射表驱动:
export interface PropertyListItemMap {
fills: Fill
strokes: Stroke
effects: Effect
}
export type PropertyListKey = keyof PropertyListItemMap
export type PropertyListItemFor<K extends PropertyListKey> = PropertyListItemMap[K]
export type PropertyListPatchFor<K extends PropertyListKey> = Partial<PropertyListItemFor<K>>
Fill、Stroke、Effect均来自场景图包@open-pencil/scene-graph,与节点上的真实属性类型一一对应;- 当
prop-key="fills"时,PropertyListItemFor<'fills'>被推导为Fill,patch动作接收Partial<Fill>; - 同理
"strokes"对应Stroke、"effects"对应Effect,杜绝了把填充条目误传给描边逻辑的类型事故。
PropertyListRoot 本身是泛型组件(generic="K extends PropertyListKey"),因此插槽里的 items、actions 等全部沿判别器收窄类型。PropertyListIdentity 定义为 string | number,用于行的稳定身份。
Anatomy:五个结构部件
PropertyList 由五个可独立使用的部件组成,它们共享同一个由 PropertyListRoot 通过 provide/inject 提供的上下文(见 context.ts):
| 部件 | 职责 |
|---|---|
PropertyListRoot |
受控条目容器:管理 items、行身份(identity)、混合状态与语义事件 |
PropertyListItem |
单个列表行:携带精确条目类型,并暴露 data-hidden 与 data-dragging 状态属性 |
PropertyListAdd |
追加一条类型化条目(触发 add 事件) |
PropertyListRemove |
删除指定索引的条目(触发 remove 事件) |
PropertyListVisibility |
切换指定索引条目的可见性,并暴露 aria-pressed 无障碍状态 |
其中 PropertyListItem 的说明见 property-list-item.md:它把 update、patch、remove、toggleVisibility 四类行级处理器一次性暴露给插槽,适合自建列表行 UI 的场景。
实战示例:一个最小可用的填充列表
以下示例来自 property-list-root.md,展示用 PropertyListRoot + PropertyListItem + PropertyListRemove 拼出一个可删除条目的填充列表。这里 fills 是一个受控的 Fill[] 引用,删除事件通过 @remove 回传给调用方完成数据变更:
<script setup lang="ts">
import { ref } from 'vue'
import type { Fill } from '@open-pencil/scene-graph'
import {
PropertyListItem,
PropertyListRemove,
PropertyListRoot
} from '@open-pencil/vue'
const fills = ref<Fill[]>([])
</script>
<template>
<PropertyListRoot
prop-key="fills"
:items="fills"
@remove="fills.splice($event, 1)"
v-slot="{ items }"
>
<PropertyListItem
v-for="(_, index) in items"
:key="index"
prop-key="fills"
:index="index"
v-slot="{ item }"
>
<span>{{ item?.type }}</span>
<PropertyListRemove prop-key="fills" :index="index">Remove</PropertyListRemove>
</PropertyListItem>
</PropertyListRoot>
</template>
要点:
prop-key在 Root 与各部件上必须保持一致,才能维持泛型推导并匹配上下文;v-for的:key默认使用索引;若你的列表有稳定 ID,可通过getKey自定义行身份;- 事件载荷即索引(
remove的$event是number),数据在哪里、事件就回到哪里,符合受控组件契约。
更完整的共享交互状态矩阵(open / empty / disabled 等),参见 PropertySection 演示。
PropertyListRoot 的 Props、Emits 与插槽(源码级)
从 PropertyListRoot.vue 的实现可以完整还原它的契约:
Props(默认值见 types.ts)
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
propKey |
K extends PropertyListKey |
必填 | 判别器,提供精确的 Fill/Stroke/Effect 类型 |
items |
PropertyListItemFor<K>[] |
必填 | 受控列表条目 |
mixed |
boolean |
false |
标记当前选择集内该属性取值不一致(混合状态) |
disabled |
boolean |
false |
禁用全部条目动作 |
getKey |
(item, index) => string | number |
索引 | 为 keyed 行提供稳定身份 |
label |
string |
— | 暴露给消费方的无障碍标签 |
Emits(语义事件)
| 事件 | 载荷 | 含义 |
|---|---|---|
add |
item: PropertyListItemFor<K> |
追加一条类型化条目 |
remove |
index: number |
删除指定索引条目 |
update |
(index, item) |
整体替换指定索引条目 |
patch |
(index, changes: PropertyListPatchFor<K>) |
局部合并变更到指定条目 |
toggleVisibility |
index: number |
切换指定条目可见性 |
reorder |
(fromIndex, toIndex) |
移动条目(拖拽排序) |
实现细节:所有动作在触发前都会检查 disabled 状态,禁用时事件不会向外发射;keyOf 默认回退为索引,有 getKey 时优先使用自定义身份函数。Root 通过 providePropertyList({ propKey, items, isMixed, disabled, keyOf, actions }) 把上下文下发给所有后代部件,同时默认插槽会收到 items、isMixed、disabled、keyOf、actions 五组插槽属性(见 types.ts)。
行级动作与显隐切换的行为细节
PropertyListItem 的插槽会收到 { item, index, hidden, dragging, disabled, actions },其中 actions 为行级处理器集合(types.ts):
export interface PropertyListItemActions<K extends PropertyListKey> {
update(item: PropertyListItemFor<K>): void
patch(changes: PropertyListPatchFor<K>): void
remove(): void
toggleVisibility(): void
}
hidden/dragging会以data-hidden、data-dragging的形式落到 DOM 上,方便你直接用 CSS 属性选择器做显隐与拖拽态样式,无需额外 JS 状态;PropertyListVisibility会同步维护aria-pressed,让“眼睛图标”这类按钮具备正确的无障碍语义;PropertyListAdd/PropertyListRemove等子部件均支持as(渲染为指定元素)与asChild(合并到唯一子元素)两种复合模式,默认渲染为<button>,便于接入你的按钮体系。
编辑器适配器:useEditorPropertyList 的底层实现
原生属性列表接入编辑器时,OpenPencil 面板使用 useEditorPropertyList(propKey) 把受控事件连接到选择集、多节点更新、撤销批处理与排序。其实现位于 use.ts,核心链路如下:
- 读取编辑器上下文与节点属性:
useEditor()获取编辑器实例;useNodeProps()(见 node-props/use.ts)提供selectedNodes、activeNode与isArrayMixed(propKey)——后者判断当前选择集内该数组属性是否混合,混合时items直接置空并置isMixed为 true; - 撤销批处理:
useUndoBatch(editor.undo, editor.beginInteractiveEdit)提供ensure/flush两个入口。高频操作(如逐条update、patch)用batch.ensure(key, label)把连续变更合并为一个撤销步骤;一次性操作(add、remove、toggleVisibility、reorder)先用flush()切断上一个批,再通过editor.undo.runBatch(label, apply)包裹; - 多节点广播:
targetNodes()在单选时返回[activeNode],多选时返回全部选中节点,每个操作都遍历节点逐个updateNodeWithUndo(node.id, { [propKey]: next }, label)写入并记录撤销; - 不可变更新:所有条目变更都基于数组拷贝 +
structuredClone深拷贝实现(见update、patch、add中的next[index] = structuredClone(item)),保证不原地修改受控数据;reorder通过moveItem辅助函数完成“取出—插入”的索引搬运; - 操作命名:撤销标签语义化,如
Add fills、Remove fills、Change fills、Toggle fills visibility、Reorder fills,多节点场景使用Set fills。
值得注意:toggleVisibility 在回写前会通过 editor.getNode(node.id) 重新获取实时节点,避免陈旧引用;isMulti 时 add 会把新条目作为该属性的唯一值写入所有节点([nextItem]),而不是追加,这是设计上的选择——多选时避免各节点数组长度不一致。
第三方消费者:usePropertyList 与自定义适配器
对于不依赖 OpenPencil 编辑器上下文的应用,usePropertyList() 提供了轻量路径:它仅读取 PropertyListRoot 提供的本地上下文,返回受控条目、混合状态与行级处理器,全程不触碰编辑器(见 use-property-list.md)。
这意味着你可以:
- 在任意 Vue 应用中用
PropertyListRoot+ 自己的items与事件处理构建独立的填充/描边/效果列表; - 把
useEditorPropertyList(propKey)放在一个适配器组件里,作为“编辑器态”与“原语态”之间的桥,实现与 OpenPencil 编辑器解耦; - 或将两者组合:适配器组件内部调用
useEditorPropertyList,再把items、actions作为 props 传给纯原语层,逻辑与 UI 完全分离。
相关 API 与延伸阅读
- PropertyListRoot API 文档(本文主体)
- PropertyListItem API 文档:单行原语的 update/patch/remove/visibility 处理器
- usePropertyList 高级 API:原语上下文读取助手
- PropertySection 文档:可折叠属性分区解剖结构与空态示例
- 组件索引:Components 总览,查看
@open-pencil/vue全部无头原语清单 - 源码参考:PropertyList 原语实现、编辑器适配器实现