OpenPencil `usePropertyList` 深度指南:属性列表上下文的原理、用法与编辑器接入

原创2026-10-08 20:43:111,638 阅读
文章标签:桌面应用开发工具前端人工智能AI 应用MCP 服务代码生成CLI插件系统

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(来自原文档)

总结

usePropertyList 是 OpenPencil 属性面板体系中最轻量也最关键的一环:它把 PropertyListRoot 注入的上下文以类型安全的方式暴露给任意后代组件,支撑起 PropertyListItem 的行级动作封装;而真正的“编辑器力量”——选区感知、多节点批量更新、撤销批处理与重排序——则由同族的 useEditorPropertyList 在编辑器侧完成。理解这两层的边界与接线方式,无论是为 OpenPencil 编辑器编写属性面板,还是在第三方环境中做受控的属性列表 UI,都能做到游刃有余。

登录后查看全文
open-pencil