OpenPencil SDK:usePropertyList 属性列表上下文 Hook 完整指南
OpenPencil SDK:usePropertyList 属性列表上下文 Hook 完整指南
usePropertyList() 是 OpenPencil 可编程 SDK 中读取 PropertyListRoot 提供的本地上下文的核心组合式函数(composable),专为自定义「填充(fills)/ 描边(strokes)/ 效果(effects)」列表行 UI 设计。本文将从上下文数据结构、源码实现、五个 part 组件协作方式到编辑器适配器 useEditorPropertyList 的调用链,带你完整掌握如何在插件与面板中构建受控的、支持混合状态与撤销批处理的属性列表。
一、usePropertyList 是什么
根据 usePropertyList API 文档 的定义:
usePropertyList()返回离它最近的PropertyListRoot所提供的 property-list 本地上下文(local context);- 它的使用场景是:在自定义的**后代组件(descendant components)**中获取受控条目(controlled items)、混合状态信息(mixed-state information)以及行级操作处理器(row-level handlers),用于构建填充、描边与效果列表;
- 它不访问编辑器(does not access an editor)——上下文只描述「列表」本身,不关心文档模型;
- OpenPencil 编辑器面板需要在适配器组件中改用
useEditorPropertyList(propKey),才能把受控原语连接到选择集(selection)、撤销批处理(undo batching)与多节点变更(multi-node mutations)。
从源码看,该 Hook 的实现位于 context.ts:
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>
}
它基于 Vue 的 provide / inject 机制,通过 Symbol('PropertyList') 作为注入键。如果组件树中不存在 PropertyListRoot,调用 usePropertyList() 会直接抛出 [open-pencil] PropertyList part must be used inside PropertyListRoot,从而在开发期就暴露错误的组件嵌套。
二、上下文对象的结构:PropertyListContext
usePropertyList() 返回的上下文类型定义在 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
PropertyListKey 只有三个合法取值:'fills'、'strokes'、'effects',对应的条目类型分别来自 @open-pencil/scene-graph 的 Fill、Stroke、Effect。这就是「propKey 判别器(discriminator)给插槽与动作提供精确类型」的实现基础。
上下文本身:
| 字段 | 类型 | 含义 |
|---|---|---|
propKey |
PropertyListKey |
判别当前列表是 fills / strokes / effects |
items |
ComputedRef<PropertyListItemFor<K>[]> |
受控条目数组(由外部传入) |
isMixed |
ComputedRef<boolean> |
是否处于混合状态(多选节点值不一致) |
disabled |
ComputedRef<boolean> |
是否禁用所有条目操作 |
keyOf(item, index) |
(item, index) => PropertyListIdentity |
为行提供稳定身份,默认回退到索引 |
actions |
PropertyListActions<K> |
六种行级操作 |
PropertyListActions<K> 完整定义了六个受控动作,均由 PropertyListRoot 以事件形式向上抛出:
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() 用在 PropertyListRoot 内部的任意自定义组件中,即可读取 items、isMixed、actions 等。以 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>
注意几个细节:
PropertyListRoot的prop-key="fills"与每个 part 组件的prop-key必须一致。这是因为 part 组件内部调用的是 usePropertyListPart:
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
}
不匹配时会抛出 [open-pencil] PropertyList part propKey must match PropertyListRoot (fills) 之类的错误;同时该签名借助泛型 K 保持类型推断,让插槽里的 item 精确到 Fill / Stroke / Effect。
-
PropertyListItem默认渲染为div(as属性可改为任意元素或组件),并在根元素上输出data-slot="item"、data-hidden、data-dragging、data-disabled数据属性,便于无样式(headless)架构下的 CSS 选择器定制(见 PropertyListItem.vue)。 -
item的类型是PropertyListItemFor<K> | undefined,因为数组索引可能越界或处于混合状态(此时items为空数组)。
四、五个 part 组件如何通过 usePropertyList 协作
PropertyList 原语的 Anatomy(解剖结构)由 PropertyListRoot 文档 归纳为五个部件:
PropertyListRoot— 受控条目、身份、混合状态与语义事件,是上下文的唯一提供者;PropertyListItem— 单行原语,携带精确条目类型与data-hidden、data-dragging;PropertyListAdd— 添加一个类型化条目;PropertyListRemove— 移除指定索引的条目;PropertyListVisibility— 切换指定索引的可见性并暴露aria-pressed。
它们都通过 usePropertyListPart(propKey) 读取同一个上下文,并遵循「先 emit 事件、再调用 context.actions」的转发模式。例如 PropertyListVisibility.vue 会计算可见性、设置 aria-pressed 与 data-hidden,点击时依次 emit('toggle', index) 和 context.actions.toggleVisibility(index);PropertyListAdd.vue 与 PropertyListRemove.vue 则额外通过 :type="!asChild && as === 'button' ? 'button' : undefined" 保证渲染为原生按钮时类型安全。
仓库中一份完整的交互式用法见 States.vue 示例:它维护 fills 响应式数组,用 PropertyListAdd 追加克隆的默认填充、PropertyListVisibility 切换 visible、PropertyListRemove 删除行,并演示了空状态(PropertySectionEmptyAction)、标题区(PropertySectionHeader)与分段控件(SegmentedControlRoot)的组合——这正是 OpenPencil 属性面板的典型布局。
五、编辑器适配:useEditorPropertyList 与撤销/多节点语义
usePropertyList() 本身与编辑器解耦,第三方 SDK 消费者可以自带状态适配器。而 OpenPencil 自己的面板(如填充/描边/效果小节)则通过 useEditorPropertyList(propKey) 把受控原语接入编辑器,其实现位于 packages/vue/src/controls/property-list/use.ts,内部依次依赖:
useNodeProps():低层属性面板辅助(use-node-props API),提供混合值检测isArrayMixed(propKey)、selectedNodes与activeNode;useEditor():编辑器上下文,负责updateNodeWithUndo与撤销栈;useUndoBatch():撤销批处理,用于多节点一次性变更。
它返回的 actions 与 PropertyListActions<K> 同构,但在每个动作上叠加了真实语义:
| 动作 | 编辑器行为要点 |
|---|---|
add |
多选时 undo.runBatch(label, apply) 批量操作,单节点直接执行;多选下新建为单元素数组 |
remove |
对每个目标节点过滤掉指定索引后写回,多节点时批量入撤销栈 |
update / patch |
通过 batch.ensure(key, label) 在连续滑动等交互中合并撤销记录;patch 对条目做浅合并 { ...current, ...changes } |
toggleVisibility |
取实时节点(editor.getNode)翻转 visible 后写回 |
reorder |
借助 moveItem 辅助函数移动条目,多选时整批撤销 |
一个关键设计:当多选且 isArrayMixed(propKey) 为真时,items 计算属性直接返回 [],避免在值不一致的多节点上展示伪造的单一值——这正是属性面板中「混合值(mixed)提示」的数据来源。此外 selectedNodeIds、isMulti、active、flush 等返回值可供适配器组件驱动外层 UI 状态(如禁用添加按钮)。
六、相关 API 与深入阅读
- PropertyListRoot:受控、无样式的 fills/strokes/effects 列表原语总览与 Anatomy;
- PropertyListItem:单行条目的 update / patch / remove / visibility 处理器;
- useNodeProps:
useEditorPropertyList底层的选择集与混合值辅助; - 源码实现:context.ts、types.ts、PropertyListRoot.vue、controls/property-list/use.ts;
- 完整示例:States.vue。
实践要点回顾:在 PropertyListRoot 内部的自定义组件里直接 usePropertyList() 拿到 items、isMixed 与 actions;构建 OpenPencil 编辑器面板时改用 useEditorPropertyList(propKey) 以获得选择集、撤销与多节点支持;所有 part 组件的 propKey 必须与最近的 PropertyListRoot 匹配,否则会抛出明确的开发期错误。