前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载导读PositionControlsRoot是open-pencil/vue提供的无样式headless根组件专门用于承载位置、尺寸、旋转、对齐与翻转反射这类属性控制 UI。它的核心价值在于把读取当前选中节点几何属性、把修改写回编辑器并纳入撤销历史这一整套编辑器接线editor wiring封装好让开发者专注于自定义外观与交互而无需重新实现底层逻辑。读完本文你将掌握PositionControlsRoot的 slot 协议、其底层数据来源usePosition()的全部返回值以及如何在属性面板中把它与数字输入框、图标按钮组合成一套可实战的位置控制组件。关联文档与源码位置关联文档意大利语原文position-controls-root.md英文对照版position-controls-root.md组件实现PositionControlsRoot.vueComposable 实现use.ts属性面板指南property-panels.md官方示例应用内置PositionSection.vue核心概念无样式根组件Headless Root PrimitivePositionControlsRoot的定位是无样式headless根组件。它不渲染任何可见 UI只通过默认 slot 把状态与动作暴露给调用方外观完全由使用者决定。这正是open-pencil/vue控制组件体系的设计惯例与PropertyListRoot、LayoutControlsRoot等同属一类。从英文文档的定义看PositionControlsRootexposes position, size, rotation, align, flip, and rotate handlers for the current selection即针对当前选区暴露位置、尺寸、旋转、对齐、翻转和旋转处理器。意大利语文档的表述与之对应PositionControlsRootfornisce valori e azioni di posizione, dimensioni, rotazione, allineamento e riflessione per la selezione corrente.为当前选区提供位置、尺寸、旋转、对齐和反射的值与动作。组件剖析slot 协议详解PositionControlsRoot的完整实现位于 PositionControlsRoot.vue核心逻辑只有几十行内部调用usePosition()获取状态再通过一个默认 slot 透出以下属性Slot 属性类型含义activeboolean当前是否处于可编辑/激活状态来自useNodePropsis-multiboolean当前是否为多选多个节点被选中idsstring[]当前选中节点的 id 列表x-valuenumber \| MIXEDX 坐标值多选且值不一致时为MIXEDy-valuenumber \| MIXEDY 坐标值w-valuenumber \| MIXED宽度值h-valuenumber \| MIXED高度值rotation-valuenumber \| MIXED旋转角度值mixedSymbol多选混合值标志即MIXED符号actionsobject动作集合updateProp、commitProp、cancelProp、align、flip、rotateMIXED是一个Symbol定义于 helpers.tsexport const MIXED Symbol(mixed)。当多个被选节点的同一属性值不一致时对应字段即为该符号用于在 UI 上显示混合值占位例如输入框显示空或横线。注意组件内部对数值的取整处理单选时xValue、yValue、rotationValue都经过Math.round()确保输入框显示整洁的整数值而wValue、hValue直接透出multiProp(width)/multiProp(height)保留了原始精度。为什么单选用node、多选用prop在 use.ts 中可以清楚看到两种读取路径单选node.value?.x ?? 0直接读取当前节点属性多选multiProp(x).value经由useNodeProps的prop(key)方法读取——当各节点值不一致时返回MIXED符号。这种设计保证了混合值语义只在多选时出现单选永远返回具体数值。底层数据usePosition() 完整 APIusePosition()是PositionControlsRoot的数据源也可以脱离组件单独使用。完整返回如下来自 use.ts状态editor、nodes选中节点数组、node单节点、active、isMulti、prop、ids数值x、y、width、height、rotation动作updateProp、commitProp、cancelProp、align、flip、rotaterotation在 composable 层同样被取整Math.round(node.value?.rotation ?? 0)。对齐alignposition.align(horizontal, center) position.align(vertical, min)轴horizontal | vertical位置min | center | max底层调用editor.alignNodes(ids, axis, pos)作用于当前所有选中节点use.ts。翻转flipposition.flip(horizontal) position.flip(vertical)底层调用editor.flipNodes(ids, axis)use.ts。旋转rotateposition.rotate(90)底层调用editor.rotateNodes(ids, degrees)use.ts。数值修改与撤销updateProp / commitProp / cancelProp这三个方法构成完整的预览-确认交互周期全部经由 usePropScrub 实现updateProp(key, value)拖拽过程中持续更新属性预览commitProp(key, value, previous)交互结束时提交最终值并把整次修改合并为单条撤销历史记录cancelProp(key)取消未提交的预览修改。key的类型是NumericNodeProperty来自open-pencil/scene-graph包括x、y、width、height、rotation等数值型节点属性。使用方式文档示例import { usePosition } from open-pencil/vue const position usePosition() const { x, y, width, height, rotation, updateProp, commitProp } usePosition()变量链接规则属性面板集成前提在open-pencil/vue的属性面板体系中凡是支持变量绑定variable binding的字段必须遵守以下规则见 property-panels.md聚焦与打开选择器不得移除已有绑定只有首次真实修改才会解除绑定即分离显式动作才会移除绑定分离、修改以及多选下的更新必须属于同一条撤销历史操作。NumberField在未激活时显示变量名编辑时显示解析后的数值。usePosition之所以推荐配合NumberField使用正是因为它的updateProp/commitProp/cancelProp协议天然满足一次交互 一条历史记录的约束。实战示例组装一个位置控制面板官方内置的属性面板 PositionSection.vue 是PositionControlsRoot的真实使用范本template PositionControlsRoot v-slot{ isMulti, actions, xValue, yValue, wValue, hValue, rotationValue, mixed } NumberField :model-valuexValue :mixedisMulti xValue mixed update:model-valueactions.updateProp(x, $event) commit(v, p) actions.commitProp(x, v, p) / !-- y、width、height、rotation 同理 -- IconButton label水平翻转 clickactions.flip(horizontal) / IconButton label垂直翻转 clickactions.flip(vertical) / IconButton label旋转 90° clickactions.rotate(90) / /PositionControlsRoot /template关键接线方式源码 PositionSection.vue数值输入update:model-value绑定actions.updateProp(key, $event)commit绑定actions.commitProp(key, v, p)。前者负责拖拽/输入预览后者在交互结束时写入撤销历史混合值展示通过isMulti xValue mixed判断当前字段是否处于混合状态按钮动作click直接调用actions.flip(horizontal)、actions.flip(vertical)、actions.rotate(90)。组件 vs Composable何时用哪个根据属性面板指南的总体建议当面板需要计算值并对外提供动作时直接用 composable如usePosition()当需要结构化组件如属性列表时用PropertyListRoot/PropertyListItem这类结构性组件。PositionControlsRoot恰好处于两者之间它是一个薄根组件本质上只是usePosition()的模板层封装——把值计算好、动作收集好再通过 slot 交给你。因此如果你要写一个独立的可复用位置控制组件用PositionControlsRoot如果你要把位置逻辑内嵌到自定义面板中例如与PropertyListRoot混排直接调用usePosition()更灵活。总结PositionControlsRoot的核心价值是少写接线、多写 UI通过一个默认 slot 输出x/y/width/height/rotation五个数值含多选混合值语义以及align/flip/rotate/updateProp/commitProp/cancelProp六个动作底层由usePosition()→useNodeProps()usePropScrub()→ 编辑器alignNodes/flipNodes/rotateNodes串起完整链路并保证修改可预览、可取消、可合并进单条撤销历史。配合 属性面板指南 中关于变量链接的规则即可在open-pencil/vue生态中快速构建出符合编辑器行为规范的自定义位置控制面板。相关 API 延伸阅读usePositionusePropScrubuseNodePropsNumberFielduseLayout、useAppearance赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐open-pencil open-pencil/vue Composables用 provideEditor、useEditor 与 useCanvas 构建自定义设计编辑器界面open pencil open pencil/vue Composables用 provideEditor、useEditor 与 useCanvas 构前端桌面应用AI 应用MCP 服务open-pencil Vue SDK 无头组件 PageListRoot 深度解析构建自定义页面列表面板open pencil Vue SDK 无头组件 PageListRoot 深度解析构建自定义页面列表面板 PageListRoot 是 open penci前端桌面应用AI 应用MCP 服务open-pencil open-pencil/vue 无头组件体系用无样式原语构建自定义设计编辑器界面open pencil open pencil/vue 无头组件体系用无样式原语构建自定义设计编辑器界面 本篇基于 open pencil 仓库中 pack前端桌面应用AI 应用MCP 服务上一篇3分钟搞定Fay框架数据同步从单库到高可用实践指南下一篇Ant Design X代码质量报告分析从报告中提取AI应用改进点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考