OpenPencil Vue SDK 深入解析:usePropertyList 上下文 Hook 与 PropertyList 受控列表原语
OpenPencil Vue SDK 深入解析:usePropertyList 上下文 Hook 与 PropertyList 受控列表原语
导读
usePropertyList() 是 OpenPencil Vue SDK(packages/vue)中负责读取属性列表上下文的组合式函数(composable)。它不直接触碰编辑器状态,而是从最近的 PropertyListRoot 组件获取当前列表元素、混合状态(mixed state)以及针对填充(fills)、描边(strokes)和效果(effects)的逐行操作句柄,供属性面板等受控 UI 的后代组件使用。本文将以其在 use-property-list.md 中的 API 文档为骨架,结合 PropertyListRoot、PropertyListItem 及 context.ts 等真实源码,讲解上下文注入机制、类型化 propKey 判别、编辑器适配层以及完整的实操代码示例。读完本文,你将掌握如何构建自己的受控填充/描边/效果列表 UI,并在编辑器面板中通过 useEditorPropertyList(propKey) 将其接入选择集、撤销批处理与多节点变更。
从 PropertyList 原语看 usePropertyList 的定位
在深入 usePropertyList() 之前,先理解它所属的完整原语家族。根据 property-list-root.md 和英文主文档 PropertyList 文档(英文版对应 property-list-root.md),PropertyList 是一套“受控、无头(headless)”的列表原语,专为填充、描边、效果这类以数组形式存储的属性设计。其组成如下:
| 组件 / Hook | 职责 |
|---|---|
PropertyListRoot |
受控列表根:接收 items 与 mixed 状态,发出变更事件,向下提供上下文 |
PropertyListItem |
列表行:提供元素、索引、可见性、dragging 状态与行级操作 |
PropertyListAdd |
添加一个类型化元素 |
PropertyListRemove |
按索引删除元素 |
PropertyListVisibility |
切换索引元素的可见性,并暴露 aria-pressed |
usePropertyList() |
读取最近 PropertyListRoot 提供的上下文(本篇文章的主角) |
这五个组件和 hook 均在 packages/vue/src/primitives/PropertyList/index.ts 中统一导出,其中 usePropertyList 来自同目录的 context.ts。它们是纯 UI 原语,自身不依赖任何编辑器上下文,这是理解 usePropertyList() 行为边界的关键。
usePropertyList 的作用与返回值
按 use-property-list.md 的定义:
usePropertyList()读取由PropertyListRoot提供的本地属性列表上下文。请在需要受控元素、混合状态信息或针对填充、描边、效果的行级处理器的后代组件中使用它。它不访问编辑器。
也就是说,这个 hook 解决的是“后代组件如何拿到根组件托管的数据与操作”这一问题,属于 Vue 的组合式依赖注入(provide/inject)模式在列表场景下的应用。它返回的上下文类型 PropertyListContext<K> 定义在 types.ts,结构如下:
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>
}
其中 actions 的类型 PropertyListActions<K> 定义了六种受控操作(见 types.ts):
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
}
可以看出,usePropertyList() 的使用者拿到的是一个“受控”句柄:数据来自 items 计算属性,变更通过 actions 回调出去,组件自身不持有可变状态。这正是“受控列表”的核心含义。
源码级原理:注入键、provide 与类型守卫
usePropertyList() 的实现位于 context.ts:
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>
}
这里有几个值得注意的实现细节:
- Symbol 注入键:
PROPERTY_LIST_KEY被定义为Symbol('PropertyList')(context.ts),避免与其他注入键冲突; - 错误提示明确:在
PropertyListRoot之外调用usePropertyList()会抛出[open-pencil] PropertyList part must be used inside PropertyListRoot,帮助开发者在开发期快速定位组件树层级错误; - 类型守卫双保险:同文件还提供了
usePropertyListPart(propKey)(context.ts),它会额外校验调用方的propKey与最近PropertyListRoot的propKey是否一致,不一致时抛出[open-pencil] PropertyList part propKey must match PropertyListRoot (${propKey})。这是防止把“填充列表的操作”误用到“效果列表”上的运行时护栏。
在注入链的另一端,PropertyListRoot.vue 通过 providePropertyList({ propKey, items, isMixed, disabled, keyOf, actions })(PropertyListRoot.vue)向下提供上下文,并在所有 action 中先检查 disabled 再 emit 对应事件(PropertyListRoot.vue)。也就是说,禁用状态既在根层拦截事件,又在行层通过 usePropertyListPart 拿到的 disabled 计算属性双重约束,保证禁用列表不会有任何变更泄漏到上层。
类型化 propKey:精确的 Fill / Stroke / Effect 判别
usePropertyList() 泛型参数 K extends PropertyListKey 的取值空间由 types.ts 定义:
export interface PropertyListItemMap {
fills: Fill
strokes: Stroke
effects: Effect
}
export type PropertyListKey = keyof PropertyListItemMap
export type PropertyListItemFor<K extends PropertyListKey> = PropertyListItemMap[K]
Fill、Stroke、Effect 来自场景图类型包 @open-pencil/scene-graph。propKey 是一个“判别器”(discriminator):在 PropertyListRoot 上写入 prop-key="fills" 后,插槽与 actions 中的元素类型就会被精确推导为 Fill,而非宽泛的联合类型。同理,PropertyListPatchFor<K> = Partial<PropertyListItemFor<K>> 保证了“局部修改”只能提交与 propKey 匹配的字段。这一设计让填充、描边、效果三种列表共用同一套受控原语,却能在编译期维持各自的类型安全。
在自定义面板中使用 usePropertyList
英文主文档 PropertyList 文档(内容对应的原始英文版本)给出了一个完整的 Vue 3 组合式示例,可在任意非编辑器上下文(比如纯表单、设计工具插件面板)直接运行。下面将其拆解为逐步说明,并补充类型与默认值注解。
<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>
要点说明:
:items是受控数据源;@remove="fills.splice($event, 1)"把“移除索引”事件映射为外部状态的实际变更——根组件只负责通知,不直接改数据;v-slot="{ items }"拿到的是items计算属性解包后的数组,用于驱动v-for;- 每个
PropertyListItem通过:index定位到具体行,其插槽接收PropertyListItemSlotProps<K>(types.ts):item(可能为undefined,代表索引越界)、index、hidden、dragging、disabled以及行级actions; - 若需要在行内调用
usePropertyList(),同样要保证组件处于PropertyListRoot后代位置;行级操作推荐使用插槽中的actions(update/patch/remove/toggleVisibility),因为它们已自动与根上下文联动并遵循disabled状态。
这里之所以默认 :key="index",是因为 PropertyListRootProps 的 getKey 属性默认为按索引(types.ts)。当列表可能发生插入、删除、重排时,建议通过 getKey 提供稳定的元素标识,避免行状态串位。
编辑器接入:useEditorPropertyList 与 usePropertyList 的分工
usePropertyList() 本身“不访问编辑器”,但 OpenPencil 的属性面板需要把受控列表连接到选择集、撤销与多节点变更。这一层由控制层组合式函数 useEditorPropertyList(propKey) 完成,位于 packages/vue/src/controls/property-list/use.ts,并随 packages/vue/src/controls/property-list/index.ts 导出。
两者分工可概括为一张对照表:
| 关注点 | usePropertyList()(原语层) |
useEditorPropertyList(propKey)(控制层) |
|---|---|---|
| 数据来源 | PropertyListRoot 提供的本地受控上下文 |
当前选择节点的场景图属性 |
| 混合状态 | isMixed 来自根组件的 mixed prop |
isArrayMixed(propKey) 由 useNodeProps 计算 |
| 变更去向 | 向根组件 emit 语义事件 | 通过 editor.updateNodeWithUndo 写入场景图并纳入撤销历史 |
| 多节点 | 不感知选择集 | 对选中节点批量应用,并用 editor.undo.runBatch 合并撤销批次 |
| 编辑器依赖 | 无 | 依赖 useEditor() 与 useUndoBatch |
以 remove(index) 为例(use.ts):多选时它遍历所有目标节点,对每个节点过滤掉对应索引的元素后调用 updateArray,并把整批操作包装为 Remove ${propKey} 的撤销批次;单选时则直接执行。add、toggleVisibility、reorder 采用相同的“多节点批量 + runBatch / 单选直改”策略(use.ts),而 update / patch 这类高频连续操作则通过 batch.ensure(key, label) 把同一节点的连续修改合并为一次撤销记录(use.ts)。可见编辑器面板在真实场景下的“撤销粒度”控制正是由这一层承担的。
因此,典型的三层架构是:
- 原语层:
PropertyListRoot+PropertyListItem+usePropertyList()负责受控 UI 与类型安全; - 适配层:
useEditorPropertyList(propKey)(或第三方自定义适配器)把原语事件翻译成编辑器命令; - 面板层:属性面板组件把适配层返回的
items、isMixed、actions绑定给原语,并补充缩略图、控件与行菜单等应用层展示。
测试与验收
在 OpenPencil 的测试体系中,属性面板的受控列表交互经由 tests/engine/app 与 tests/e2e/properties 等测试目录覆盖,例如填充列表的增删、可见性切换与多选批量修改。此外,原语自带的示例 PropertySection/examples/States.vue 演示了 isMixed / disabled 等状态矩阵下的交互行为,是快速理解 usePropertyList() 返回状态语义的直观入口。你可以结合这些测试与示例验证自定义列表组件在混合选择(mixed selection)与禁用态下的表现。
总结
usePropertyList() 是 PropertyList 原语家族的“上下文读取口”:它让位于 PropertyListRoot 之下的任意后代组件以类型安全的方式获得受控元素、混合状态与六种行级/列表级操作,而完全不依赖编辑器。需要把列表接入选择集与撤销系统时,再通过 useEditorPropertyList(propKey) 在适配组件中桥接。将原语层、适配层与面板层分离的设计,使得第三方 SDK 使用者可以在没有 OpenPencil 编辑器上下文的环境中,复用同一套受控列表机制来构建自定义的属性编辑 UI。