OpenPencil SDK 组件解析:用 PropertyList 原语构建 Fills、Strokes 与 Effects 的无头属性列表

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

OpenPencil SDK 组件解析:用 PropertyList 原语构建 Fills、Strokes 与 Effects 的无头属性列表

PropertyList 是 OpenPencil 可编程 SDK(@open-pencil/vue)中用于属性面板的受控、无头(headless)列表原语,专门服务于填充(Fills)、描边(Strokes)与效果(Effects)三类数组型场景属性。本文以其 API 文档为主体,结合仓库内 packages/vue/src/primitives/PropertyList/ 与 packages/vue/src/controls/property-list/ 的真实实现,讲解它的类型判别机制、五件套解剖结构、受控事件契约,以及如何通过 useEditorPropertyList() 把它接入选择集、多节点更新与撤销批处理。读完你可以在自己的自定义面板、第三方 SDK 应用中直接复刻编辑器内置的属性列表行为。

PropertyList 是什么:受控的无头列表原语

在编辑器属性面板中,填充、描边和效果本质上是挂在场景节点上的数组属性,开发者需要一套统一、可复用的列表 UI 来增删、排序、显隐这些条目。PropertyList 正是为此设计的受控原语:

  • 受控(controlled):列表内容完全由外部传入的 items 驱动,组件自身不维护数据状态,所有变更通过语义事件回传给宿主;
  • 无头(headless):组件不预设任何视觉样式与 DOM 结构,只负责状态、类型与事件契约,具体渲染交给调用方的插槽;
  • 场景化类型安全:propKey 判别器让插槽和动作获得精确的 Fill、Stroke 或 Effect 类型,而不是笼统的 Record<string, unknown>。

从源码看,PropertyListRoot 是一个极简的“状态 + 事件”容器:它接收 items 并原样交给默认插槽,同时把 isMixed(混合状态)、disabled、keyOf(行身份)与 actions(动作集合)一并暴露给后代组件(见 PropertyListRoot.vue)。

编辑器内的可变性与撤销行为不在原语内部实现,而是集中在 useEditorPropertyList() 或应用自定义适配器里——这一分层正是 OpenPencil 面板组件“可复用、可替换”的关键:原语只做通用契约,编辑器相关的选择集与撤销逻辑全部外置。

propKey 判别器:让插槽与动作获得精确类型

PropertyList 类型系统的核心是 propKey。在 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>>
  • Fill、Stroke、Effect 均来自场景图包 @open-pencil/scene-graph,与节点上的真实属性类型一一对应;
  • 当 prop-key="fills" 时,PropertyListItemFor<'fills'> 被推导为 Fill,patch 动作接收 Partial<Fill>;
  • 同理 "strokes" 对应 Stroke、"effects" 对应 Effect,杜绝了把填充条目误传给描边逻辑的类型事故。

PropertyListRoot 本身是泛型组件(generic="K extends PropertyListKey"),因此插槽里的 items、actions 等全部沿判别器收窄类型。PropertyListIdentity 定义为 string | number,用于行的稳定身份。

Anatomy:五个结构部件

PropertyList 由五个可独立使用的部件组成,它们共享同一个由 PropertyListRoot 通过 provide/inject 提供的上下文(见 context.ts):

部件 职责
PropertyListRoot 受控条目容器:管理 items、行身份(identity)、混合状态与语义事件
PropertyListItem 单个列表行:携带精确条目类型,并暴露 data-hidden 与 data-dragging 状态属性
PropertyListAdd 追加一条类型化条目(触发 add 事件)
PropertyListRemove 删除指定索引的条目(触发 remove 事件)
PropertyListVisibility 切换指定索引条目的可见性,并暴露 aria-pressed 无障碍状态

其中 PropertyListItem 的说明见 property-list-item.md:它把 update、patch、remove、toggleVisibility 四类行级处理器一次性暴露给插槽,适合自建列表行 UI 的场景。

实战示例:一个最小可用的填充列表

以下示例来自 property-list-root.md,展示用 PropertyListRoot + PropertyListItem + PropertyListRemove 拼出一个可删除条目的填充列表。这里 fills 是一个受控的 Fill[] 引用,删除事件通过 @remove 回传给调用方完成数据变更:

<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>

要点:

  • prop-key 在 Root 与各部件上必须保持一致,才能维持泛型推导并匹配上下文;
  • v-for 的 :key 默认使用索引;若你的列表有稳定 ID,可通过 getKey 自定义行身份;
  • 事件载荷即索引(remove 的 $event 是 number),数据在哪里、事件就回到哪里,符合受控组件契约。

更完整的共享交互状态矩阵(open / empty / disabled 等),参见 PropertySection 演示。

PropertyListRoot 的 Props、Emits 与插槽(源码级)

从 PropertyListRoot.vue 的实现可以完整还原它的契约:

Props(默认值见 types.ts)

Prop 类型 默认值 说明
propKey K extends PropertyListKey 必填 判别器,提供精确的 Fill/Stroke/Effect 类型
items PropertyListItemFor<K>[] 必填 受控列表条目
mixed boolean false 标记当前选择集内该属性取值不一致(混合状态)
disabled boolean false 禁用全部条目动作
getKey (item, index) => string | number 索引 为 keyed 行提供稳定身份
label string — 暴露给消费方的无障碍标签

Emits(语义事件)

事件 载荷 含义
add item: PropertyListItemFor<K> 追加一条类型化条目
remove index: number 删除指定索引条目
update (index, item) 整体替换指定索引条目
patch (index, changes: PropertyListPatchFor<K>) 局部合并变更到指定条目
toggleVisibility index: number 切换指定条目可见性
reorder (fromIndex, toIndex) 移动条目(拖拽排序)

实现细节:所有动作在触发前都会检查 disabled 状态,禁用时事件不会向外发射;keyOf 默认回退为索引,有 getKey 时优先使用自定义身份函数。Root 通过 providePropertyList({ propKey, items, isMixed, disabled, keyOf, actions }) 把上下文下发给所有后代部件,同时默认插槽会收到 items、isMixed、disabled、keyOf、actions 五组插槽属性(见 types.ts)。

行级动作与显隐切换的行为细节

PropertyListItem 的插槽会收到 { item, index, hidden, dragging, disabled, actions },其中 actions 为行级处理器集合(types.ts):

export interface PropertyListItemActions<K extends PropertyListKey> {
  update(item: PropertyListItemFor<K>): void
  patch(changes: PropertyListPatchFor<K>): void
  remove(): void
  toggleVisibility(): void
}
  • hidden / dragging 会以 data-hidden、data-dragging 的形式落到 DOM 上,方便你直接用 CSS 属性选择器做显隐与拖拽态样式,无需额外 JS 状态;
  • PropertyListVisibility 会同步维护 aria-pressed,让“眼睛图标”这类按钮具备正确的无障碍语义;
  • PropertyListAdd / PropertyListRemove 等子部件均支持 as(渲染为指定元素)与 asChild(合并到唯一子元素)两种复合模式,默认渲染为 <button>,便于接入你的按钮体系。

编辑器适配器:useEditorPropertyList 的底层实现

原生属性列表接入编辑器时,OpenPencil 面板使用 useEditorPropertyList(propKey) 把受控事件连接到选择集、多节点更新、撤销批处理与排序。其实现位于 use.ts,核心链路如下:

  1. 读取编辑器上下文与节点属性:useEditor() 获取编辑器实例;useNodeProps()(见 node-props/use.ts)提供 selectedNodes、activeNode 与 isArrayMixed(propKey)——后者判断当前选择集内该数组属性是否混合,混合时 items 直接置空并置 isMixed 为 true;
  2. 撤销批处理:useUndoBatch(editor.undo, editor.beginInteractiveEdit) 提供 ensure / flush 两个入口。高频操作(如逐条 update、patch)用 batch.ensure(key, label) 把连续变更合并为一个撤销步骤;一次性操作(add、remove、toggleVisibility、reorder)先用 flush() 切断上一个批,再通过 editor.undo.runBatch(label, apply) 包裹;
  3. 多节点广播:targetNodes() 在单选时返回 [activeNode],多选时返回全部选中节点,每个操作都遍历节点逐个 updateNodeWithUndo(node.id, { [propKey]: next }, label) 写入并记录撤销;
  4. 不可变更新:所有条目变更都基于数组拷贝 + structuredClone 深拷贝实现(见 update、patch、add 中的 next[index] = structuredClone(item)),保证不原地修改受控数据;reorder 通过 moveItem 辅助函数完成“取出—插入”的索引搬运;
  5. 操作命名:撤销标签语义化,如 Add fills、Remove fills、Change fills、Toggle fills visibility、Reorder fills,多节点场景使用 Set fills。

值得注意:toggleVisibility 在回写前会通过 editor.getNode(node.id) 重新获取实时节点,避免陈旧引用;isMulti 时 add 会把新条目作为该属性的唯一值写入所有节点([nextItem]),而不是追加,这是设计上的选择——多选时避免各节点数组长度不一致。

第三方消费者:usePropertyList 与自定义适配器

对于不依赖 OpenPencil 编辑器上下文的应用,usePropertyList() 提供了轻量路径:它仅读取 PropertyListRoot 提供的本地上下文,返回受控条目、混合状态与行级处理器,全程不触碰编辑器(见 use-property-list.md)。

这意味着你可以:

  • 在任意 Vue 应用中用 PropertyListRoot + 自己的 items 与事件处理构建独立的填充/描边/效果列表;
  • 把 useEditorPropertyList(propKey) 放在一个适配器组件里,作为“编辑器态”与“原语态”之间的桥,实现与 OpenPencil 编辑器解耦;
  • 或将两者组合:适配器组件内部调用 useEditorPropertyList,再把 items、actions 作为 props 传给纯原语层,逻辑与 UI 完全分离。

相关 API 与延伸阅读

登录后查看全文
open-pencil