OpenPencil `usePropertyList` 深度指南:属性列表上下文的原理、用法与编辑器接入
OpenPencil usePropertyList 深度指南:属性列表上下文的原理、用法与编辑器接入
导读
usePropertyList() 是 OpenPencil Vue SDK(@open-pencil/vue)中一个面向 PropertyListRoot 后代的底层上下文助手(primitive context helper)。它让任意子孙组件无需层层透传 props,即可读取属性列表(fills / strokes / effects)的受控条目、混合状态(mixed state)与行级操作处理器;它自身不访问编辑器,因此既能用于编辑器内面板,也能在纯第三方渲染场景中与自己的状态适配器搭配。读完本文,你将掌握 usePropertyList 的定位、底层实现、slot props 与 actions 的完整类型契约,以及如何通过 useEditorPropertyList(propKey) 把受控原语接入选区、多节点变更与撤销批处理。
关联文档:
packages/docs/programmable/sdk/api/advanced/use-property-list.md;配套组件文档:PropertyListRoot、PropertyListItem。
一、定位:三类 API 在属性面板体系中的分工
usePropertyList 属于 @open-pencil/vue 中的 Advanced(高级/底层)API 层。该层 API 是公开的,但比主组件与组合式函数(composables)表面更专门化(见 Advanced API 索引 中 "Primitive context helpers" 一节,与 useCanvasContext、useLayerTree、useToolbar、useNumberField 并列)。
为了理解 usePropertyList 的边界,需要先看清三层分工:
| 层 | 代表 API | 职责 |
|---|---|---|
| 无头原语(headless primitives) | PropertyListRoot、PropertyListItem、PropertyListAdd/Remove/Visibility |
受控条目、身份(identity)、混合状态与语义事件的纯 UI 骨架 |
| 上下文助手 | usePropertyList |
读取 PropertyListRoot 注入的本地上下文,供后代组件消费 |
| 编辑器适配器 | useEditorPropertyList(propKey) |
把受控事件接到选区、多节点更新、撤销批处理与重排序(编辑器内部使用) |
usePropertyList 不访问编辑器("It does not access an editor"),它只是 Context 的读取端;而属性面板中“编辑器能力”由 useEditorPropertyList 承载,二者通过 PropertyListRoot 提供/注入的上下文衔接。
二、实现原理:provide/inject 与符号注入
从源码看,usePropertyList 的实现位于 packages/vue/src/primitives/PropertyList/context.ts,全部逻辑不过十余行,核心是 Vue 的组合式依赖注入:
import { inject, provide } from 'vue'
import type { InjectionKey } from 'vue'
import type { PropertyListContext, PropertyListKey } from './types'
const PROPERTY_LIST_KEY: InjectionKey<PropertyListContext> = Symbol('PropertyList')
export function providePropertyList<K extends PropertyListKey>(context: PropertyListContext<K>) {
provide(PROPERTY_LIST_KEY, context as PropertyListContext)
}
export function usePropertyList<K extends PropertyListKey>(): PropertyListContext<K> {
const context = inject(PROPERTY_LIST_KEY)
if (!context)
throw new Error('[open-pencil] PropertyList part must be used inside PropertyListRoot')
return context as PropertyListContext<K>
}
export function usePropertyListPart<K extends PropertyListKey>(propKey: K): PropertyListContext<K> {
const context = usePropertyList<K>()
if (context.propKey !== propKey) {
throw new Error(
`[open-pencil] PropertyList part propKey must match PropertyListRoot (${propKey})`
)
}
return context
}
值得注意的工程细节:
- 符号注入键:
PROPERTY_LIST_KEY是一个Symbol('PropertyList')类型的InjectionKey,避免与全局命名空间冲突,保证注入类型安全。 - 越界即抛错:若在
PropertyListRoot之外调用usePropertyList,会抛出[open-pencil] PropertyList part must be used inside PropertyListRoot,从根上杜绝“上下文悬空”导致的静默错误。 - propKey 一致性校验:
usePropertyListPart(propKey)进一步校验子部件的propKey与最近PropertyListRoot的propKey一致,否则抛出PropertyList part propKey must match PropertyListRoot (...)——这正是PropertyListItem等部件内部调用usePropertyListPart的原因(见 PropertyListItem.vue 第 42 行const context = usePropertyListPart(propKey))。
上下文由谁提供
注入端是 PropertyListRoot.vue:PropertyListRoot 在 setup 中把 propKey、items、isMixed、disabled、keyOf 与 actions 一起打包调用 providePropertyList(...)(该文件第 62 行),同时通过默认插槽把同样的内容作为 slot props 暴露给模板层。也就是说,同一份上下文既有“编程式注入”,也有“模板 slot 暴露”两条消费通道。
三、上下文类型契约:你能拿到什么
usePropertyList 的返回类型是 PropertyListContext<K>,其完整定义在 packages/vue/src/primitives/PropertyList/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>>
export type PropertyListIdentity = string | number
export interface PropertyListContext<K extends PropertyListKey = PropertyListKey> {
propKey: K
items: ComputedRef<PropertyListItemFor<K>[]>
isMixed: ComputedRef<boolean>
disabled: ComputedRef<boolean>
keyOf(item: PropertyListItemFor<K>, index: number): PropertyListIdentity
actions: PropertyListActions<K>
}
逐字段解读:
| 字段 | 类型 | 含义 |
|---|---|---|
propKey |
K('fills' | 'strokes' | 'effects') |
判别符(discriminator),为插槽与动作提供精确的 Fill / Stroke / Effect 类型 |
items |
ComputedRef<T[]> |
受控列表条目(响应式派生,来自 PropertyListRoot 的 items prop) |
isMixed |
ComputedRef<boolean> |
当前选区各节点该属性取值不一致时为 true(混合状态) |
disabled |
ComputedRef<boolean> |
根级禁用态,为 true 时所有动作被静默拦截 |
keyOf |
函数 | 返回条目的稳定身份(默认回退为数组索引) |
actions |
PropertyListActions<K> |
增、删、改、补丁、显隐、重排六类操作 |
PropertyListActions<K> 的动作签名(同文件):
export interface PropertyListActions<K extends PropertyListKey> {
add(item: PropertyListItemFor<K>): void
remove(index: number): void
update(index: number, item: PropertyListItemFor<K>): void
patch(index: number, changes: PropertyListPatchFor<K>): void
toggleVisibility(index: number): void
reorder(fromIndex: number, toIndex: number): void
}
关于混合状态:PropertyListRoot 的 mixed prop 默认值为 false(types.ts 第 40 行注释 "Marks values across the current selection as inconsistent. @default false")。多选节点时,若各节点同一 propKey 数组取值不一致,面板需要展示“混合/不一致”视觉状态,isMixed 即为此而生。
四、PropertyListItem 中的行级消费示例
官方组件文档给出了 usePropertyList 最典型的使用场景——PropertyListItem 内部就是用它(经 usePropertyListPart)拿到上下文后再包装出行级操作处理器。其动作集在 PropertyListItem.vue 第 47–68 行:
const actions: PropertyListItemActions<K> = {
update: (nextItem) => {
if (disabled.value) return
emit('update', index, nextItem)
context.actions.update(index, nextItem)
},
patch: (changes) => {
if (disabled.value) return
emit('patch', index, changes)
context.actions.patch(index, changes)
},
remove: () => {
if (disabled.value) return
emit('remove', index)
context.actions.remove(index)
},
toggleVisibility: () => {
if (disabled.value) return
emit('toggleVisibility', index)
context.actions.toggleVisibility(index)
}
}
可以看到行级处理器把 局部 disabled 与根级 disabled 合并(disabledProp || context.disabled.value),并且在调用上下文动作前先触发自身的 emit,形成“先通知父级、再走受控路径”的双通道。PropertyListItem 同时把 hidden(item?.visible === false)、dragging、disabled 等派生状态连同 actions 一起放进 slot props,并给渲染根元素打上 data-hidden、data-dragging、data-disabled 数据属性(该文件第 84–86 行),方便 CSS 与测试定位。
因此,当你在 PropertyListRoot 内部实现自定义行 UI 时,直接调用 usePropertyList()(或经 usePropertyListPart(propKey))即可获得同样的上下文,而不必依赖 PropertyListItem 这一现成部件。
五、在编辑器面板中:useEditorPropertyList 适配器
usePropertyList 的官方文档明确指出:OpenPencil 编辑器面板可以通过一个适配器组件调用 useEditorPropertyList(propKey),把受控原语连接到选区(selection)、撤销批处理(undo batching)与多节点变更(multi-node mutations)。
useEditorPropertyList 的实现位于 packages/vue/src/controls/property-list/use.ts,其组合了三个底层能力:
useNodeProps():读取当前selectedNodes、activeNode与isArrayMixed(propKey)(混合状态检测);useUndoBatch(editor.undo, editor.beginInteractiveEdit):为连续滑动/拖拽式的增量修改提供撤销批(batch.ensure/batch.flush);useEditor():获取编辑器实例以执行editor.updateNodeWithUndo(...)与editor.undo.runBatch(...)。
其关键行为(可对照源码验证):
- items 派生:
isMixed为真时items返回空数组(避免展示一个不存在的“混合条目”),否则取activeNode.value?.[propKey] ?? [](第 32–35 行)。 - 单/多节点差异:多选(
isMulti)时,add/remove/toggleVisibility/reorder通过editor.undo.runBatch(label, apply)对每个目标节点批量应用,并生成如Set fills、Add effects、Remove strokes、Toggle fills visibility、Reorder fills的人类可读撤销标签;单节点时直接执行。 - update / patch 用增量批:
update与patch使用batch.ensure(batchKey, label),其中 batchKey 由propKey:index:nodeIds组成,保证同一节点同一索引的连续修改合入同一撤销步骤(第 85–88、99–102 行)。 - 深拷贝防御:所有写入前都经
structuredClone复制(如add中structuredClone(item)、patch中structuredClone(changes)),避免修改外部引用共享的条目对象。 - patch 语义:
patch(index, changes)用{ ...current, ...changes }合并部分变更,适合“只改透明度”“只换颜色”这类局部写入。
useEditorPropertyList 的返回值比 usePropertyList 更丰富:items、isMixed、isMulti、active、activeNode、selectedNodeIds、flush 以及同一套 actions(第 153–162 行)。
官方适配示例:PropertyListRoot.vue 接线方式
编辑器内部正是通过一个泛型适配组件来桥接两层 API。仓库中的 src/components/properties/PropertyListRoot.vue 是编辑器侧的实际范例:它在 setup 中调用 useEditorPropertyList(propKey) 得到 context,再把它传给无头 PropertyListRoot,并通过 @add、@remove、@update、@patch、@toggle-visibility、@reorder 事件把六个受控事件逐一映射到 context.actions.*;同时向插槽额外暴露 isMulti、activeNode、selectedNodeIds 与 flush。核心片段:
<script setup lang="ts" generic="K extends PropertyListKey">
import { PropertyListRoot as HeadlessPropertyListRoot, useEditorPropertyList } from '@open-pencil/vue'
// ...
const context = useEditorPropertyList(propKey)
</script>
<template>
<HeadlessPropertyListRoot
v-if="context.active.value"
v-slot="slotProps"
:prop-key="propKey"
:label="label"
:items="context.items.value"
:mixed="context.isMixed.value"
@add="context.actions.add"
@remove="context.actions.remove"
@update="context.actions.update"
@patch="context.actions.patch"
@toggle-visibility="context.actions.toggleVisibility"
@reorder="context.actions.reorder"
>
<slot v-bind="slotProps" :is-multi="context.isMulti.value" :active-node="context.activeNode.value"
:selected-node-ids="context.selectedNodeIds.value" :flush="context.flush" />
</HeadlessPropertyListRoot>
</template>
六、第三方 SDK 消费者:自己实现状态适配器
usePropertyList 的文档特意强调其不访问编辑器,这为第三方 SDK 消费者打开了另一条路:在没有 OpenPencil 编辑器上下文(useEditor)的环境里,你完全可以把 PropertyListRoot 当成一个普通受控组件来驱动——只需要传入 items 数组、监听 remove/update/patch 等事件并回写自己的状态源即可。完整可复制的用法来自 PropertyListRoot 组件文档:
<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>
在这种受控模式下,你只需为 @add、@remove、@update、@patch、@toggle-visibility、@reorder 中实际用到的事件提供回写逻辑,撤销、多选等编辑器专属行为完全由你自己的应用状态决定——这正是“editor mutation and undo behavior stay in useEditorPropertyList() or an application adapter”的含义。
七、API 一览与导航
usePropertyList() 要点速览
- 用途:读取
PropertyListRoot提供的本地属性列表上下文,供后代组件使用; - 适用:需要受控条目、混合状态信息或行级 handlers(fills / strokes / effects)的后代组件;
- 边界:不访问编辑器,编辑器能力由
useEditorPropertyList(propKey)承载; - 约束:必须在
PropertyListRoot内调用,否则抛错;usePropertyListPart(propKey)额外校验 propKey 一致性; - 返回值:
PropertyListContext<K>(propKey、items、isMixed、disabled、keyOf、actions)。
Related APIs(来自原文档)
- PropertyListRoot → 仓库内为 PropertyListRoot 组件文档:受控、无头的 fills/strokes/effects 列表原语,
propKey判别符提供精确类型;Anatomy 包括PropertyListRoot/PropertyListItem/PropertyListAdd/PropertyListRemove/PropertyListVisibility。 - PropertyListItem → 仓库内为 PropertyListItem 组件文档:暴露单个数组条目的 update / patch / remove / visibility 行级处理器,适用于自定义列表行 UI。
- 进阶联动:
PropertyListItem文档还链接了 useNodeProps,用于读取选区节点的 props;更多高级 API 见 Advanced API 索引。 - 实现与类型源码:context.ts、types.ts、PropertyListRoot.vue、PropertyListItem.vue、use.ts(编辑器适配器),全部由 packages/vue/src/primitives/PropertyList/index.ts 统一导出。
总结
usePropertyList 是 OpenPencil 属性面板体系中最轻量也最关键的一环:它把 PropertyListRoot 注入的上下文以类型安全的方式暴露给任意后代组件,支撑起 PropertyListItem 的行级动作封装;而真正的“编辑器力量”——选区感知、多节点批量更新、撤销批处理与重排序——则由同族的 useEditorPropertyList 在编辑器侧完成。理解这两层的边界与接线方式,无论是为 OpenPencil 编辑器编写属性面板,还是在第三方环境中做受控的属性列表 UI,都能做到游刃有余。