OpenPencil SDK:usePropertyList 属性列表上下文 Hook 完整指南

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

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 内部的自定义组件里直接 usePropertyList() 拿到 items、isMixed 与 actions;构建 OpenPencil 编辑器面板时改用 useEditorPropertyList(propKey) 以获得选择集、撤销与多节点支持;所有 part 组件的 propKey 必须与最近的 PropertyListRoot 匹配,否则会抛出明确的开发期错误。

登录后查看全文
open-pencil