OpenPencil Vue SDK 深入解析:usePropertyList 上下文 Hook 与 PropertyList 受控列表原语

原创2026-09-27 16:14:421,429 阅读
文章标签:桌面应用开发工具前端人工智能AI 应用MCP 服务代码生成CLI插件系统

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)。可见编辑器面板在真实场景下的“撤销粒度”控制正是由这一层承担的。

因此,典型的三层架构是:

  1. 原语层:PropertyListRoot + PropertyListItem + usePropertyList() 负责受控 UI 与类型安全;
  2. 适配层:useEditorPropertyList(propKey)(或第三方自定义适配器)把原语事件翻译成编辑器命令;
  3. 面板层:属性面板组件把适配层返回的 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。

登录后查看全文
open-pencil