前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载useStrokeControls()是 OpenPencil 的open-pencil/vue包中面向描边Stroke属性面板的状态与操作组合式 API为对齐方式、四侧边框、端点与连接样式、斜接限制等提供统一的响应式状态与带撤销能力的更新动作。本文将基于 packages/docs/programmable/sdk/api/composables/use-stroke-controls.md及其德语本地化版本 packages/docs/de/programmable/sdk/api/composables/use-stroke-controls.md结合packages/vue的源码实现与编辑器内真实的 StrokeSection 面板完整讲解该组合式的返回值、核心方法与底层原理。读完后你将掌握如何在自定义属性面板中接入描边对齐、单侧描边、独立四侧粗细以及端点/连接/斜接限制的编辑能力。一、概览这个组合式解决什么问题OpenPencil 的 Vue SDK 是 headless无头设计——它只提供逻辑与结构样式与产品级 UI 由你的应用自行掌控参见 packages/vue/README.md。在属性面板这一领域SDK 提供了一组“property-panel composables”useStrokeControls正是其中之一与useFillControls、useEffectsControls、useTypography等并列见 composables 索引 的 “Property panels” 分组以及 packages/vue/ARCHITECTURE.md 对controls/目录的说明。按英文主文档的定义useStrokeControls()提供描边对齐stroke align选项侧边预设全部、上、下、左、右、自定义all / top / bottom / left / right / custom默认描边数据独立四侧粗细per-side border weight的辅助方法混合选择下的 cap端点、join连接、miter limit斜接限制状态支持撤销批处理的 cap / join 更新斜接限制输入框的预览preview与提交commit动作。德语版文档对它的概括更为精炼useStrokeControls()为描边对齐、全部或单侧选择、默认值以及独立的侧边粗细提供函数“stellt Konturausrichtungen, Auswahl aller oder einzelner Seiten, einen Standardwert und Funktionen für unabhängige Seitenstärken bereit”。二、安装与基本引入open-pencil/vue位于 packages/vue 目录安装命令见其 READMEbun add open-pencil/vue open-pencil/core open-pencil/scene-graph canvaskit-wasm在组件中引入import { useStrokeControls } from open-pencil/vue const strokes useStrokeControls()文档给出的解构示例const { alignOptions, sideOptions, currentAlign, currentSides, selectSide } useStrokeControls()useStrokeControls的导出位置在 packages/vue/src/index.ts同时导出了类型守卫isStrokeCapValue。由于组合式内部依赖useEditor()编辑器上下文与useNodeProps()选中节点与混合值解析它必须在provideEditor()提供的编辑器上下文中调用参见 packages/vue/src/controls/stroke/use.ts。三、返回值全览useStrokeControls()的返回对象由 packages/vue/src/controls/stroke/use.ts 组装可整理为下表返回字段类型/取值说明alignOptions{ value: INSIDE \| CENTER \| OUTSIDE; label }[]描边对齐选项label 来自 i18ncapOptions{ value: StrokeCap; label }[]端点样式选项NONE/ROUND/SQUARE/ARROW_LINES/ARROW_EQUILATERALjoinOptions{ value: StrokeJoin; label }[]连接样式选项MITER/BEVEL/ROUNDsideOptionsSIDE_OPTIONS侧边预设ALL/TOP/BOTTOM/LEFT/RIGHT/CUSTOMborderSides[top,right,bottom,left]四个方向的枚举用于渲染四侧粗细输入框defaultStrokeDEFAULT_STROKE新建描边的默认值advancedActiveComputedRefboolean仅当所有选中节点都至少含一条描边时为truecap/join/miterLimitComputedRefStrokeCap \| MIXED等混合选择下返回MIXED否则为共享值updateAlign(align, activeNode)函数为活动节点全部描边设置对齐方式带撤销currentAlign(activeNode)函数读取活动节点当前对齐方式currentSides(activeNode)函数推断当前侧边状态ALL/ 单侧 /CUSTOMselectSide(side, activeNode)函数应用全部/单侧/自定义侧边带撤销updateBorderWeight(side, value, activeNode)函数更新某一侧边框粗细带撤销borderWeight(activeNode, side)函数读取某一侧边框粗细setCap/setJoin函数批量更新端点/连接样式多节点时撤销批处理updateMiterLimit(value)/commitMiterLimit(value)函数斜接限制的预览与提交dashState/toggleDash/setDash/setGap函数虚线模式读取与切换sideMenuOpenRefboolean侧边菜单的开关状态内部使用选项与常量定义对齐、端点、连接选项在 use.ts 中直接定义语义与 scene-graph 类型一一对应对齐INSIDE内侧、CENTER居中、OUTSIDE外侧端点packages/scene-graph/src/types.tsStrokeCap NONE | ROUND | SQUARE | ARROW_LINES | ARROW_EQUILATERAL连接types.tsStrokeJoin MITER | BEVEL | ROUND。侧边预设SIDE_OPTIONS与方向枚举BORDER_SIDES定义在 helpers.ts同时导出了StrokeSides类型ALL | TOP | BOTTOM | LEFT | RIGHT | CUSTOM。四、描边对齐updateAlign 与 currentAlign文档中的第一个实战示例是设置描边对齐strokes.updateAlign(INSIDE, activeNode)其底层实现helpers.ts会把活动节点的所有描边逐条带上新的align字段再通过editor.updateNodeWithUndo(node.id, { strokes }, Change stroke align)提交——即一次操作即可撤销。若activeNode为空则直接返回不做任何修改。读取端strokes.currentAlign(activeNode)实现逻辑是无活动节点或节点没有任何描边时回退为CENTER否则返回第一条描边的alignhelpers.ts。在编辑器内StrokeSection.vue 正是用currentAlign(activeNode)作为AppSelect的model-value再用updateAlign($event, activeNode)处理变更data-propertystroke-align便于自动化测试定位。五、侧边控制全部 / 单侧 / 自定义与独立四侧粗细selectSide是德语文档强调的核心能力之一“Auswahl aller oder einzelner Seiten”。完整签名strokes.selectSide(TOP, activeNode)三种模式的底层语义实现位于 helpers.tsselectSide(side, activeNode)依据side走三条分支ALL关闭独立侧边权重independentStrokeWeights: false并把borderTopWeight/borderRightWeight/borderBottomWeight/borderLeftWeight全部清零粗细统一由strokes[0].weight决定CUSTOM开启independentStrokeWeights: true若节点原本已是独立权重则保留各侧当前值否则用第一条描边的粗细初始化四侧单侧TOP/BOTTOM/LEFT/RIGHT开启独立权重仅把指定侧设为第一条描边的粗细其余三侧置 0撤销标签为Stroke side only。所有分支都通过editor.updateNodeWithUndo提交且每次选择后会把sideMenuOpen复位为false。推断当前侧边状态currentSidescurrentSides(activeNode)helpers.ts用于把节点当前的权重配置映射回预设枚举未开启独立权重 →ALL四侧均大于 0 且数值完全相等 →ALL恰好只有一侧大于 0 → 返回该侧TOP/BOTTOM/LEFT/RIGHT其余情况 →CUSTOM。单侧粗细的读写borderWeight(activeNode, side)按borderSideWeight的命名规则读取如borderTopWeight非数字时返回0helpers.tsupdateBorderWeight(side, value, activeNode)则用同样的规则拼出字段名后提交带撤销的更新helpers.ts。这些字段在 scene-graph 的SceneNode类型中均有明确声明borderTopWeight、borderRightWeight、borderBottomWeight、borderLeftWeight、independentStrokeWeights、strokeMiterLimitpackages/scene-graph/src/types.ts默认值见 packages/scene-graph/src/node-defaults.tsindependentStrokeWeights: false四侧权重为 0。OpenPencil 编辑器属性面板中展开侧边编辑区后即用strokeCtx.borderSides循环渲染四个NumberField分别绑定borderWeight与updateBorderWeightStrokeSection.vue。六、默认描边数据defaultStrokedefaultStroke即DEFAULT_STROKEhelpers.tsconst DEFAULT_STROKE: Stroke { color: BLACK, // 纯黑 weight: 1, // 粗细 1 opacity: 1, // 不透明度 1 visible: true, // 可见 align: CENTER // 默认居中对齐 }它对应 scene-graph 的Stroke接口types.tscolor、weight、opacity、visible、align以及可选的cap、join、dashPattern。在 StrokeSection.vue 中面板的“添加描边”按钮正是调用actions.add(strokeCtx.defaultStroke)来创建新描边。七、几何状态advancedActive 与 MIXED文档特别强调advancedActive只在所有选中节点都至少有一条描边时才为truecap、join、miterLimit在混合选择时返回MIXED。对应实现是createStrokeGeometryStatehelpers.tsadvancedActivenodes.value.length 0 nodes.value.every(n n.strokes.length 0)cap额外检查 vectorNetwork 中是否存在与节点级 cap 不同的顶点级覆盖vertex.strokeCap一旦存在即报告MIXED确保任何选择都会触发setCap避免“旧的一头箭头顶点覆盖静默胜出”join由merged(strokeJoin)解析混合时得MIXEDmiterLimit由merged(strokeMiterLimit)解析。MIXED常量来自 packages/vue/src/controls/node-props/use.ts即useNodeProps的混合值约定。编辑器面板中的端点/连接选择器即据此把MIXED显示为特殊项StrokeGeometryControls.vue。八、几何动作端点、连接与斜接限制文档给出的“编辑描边几何”示例strokes.setCap(ROUND) strokes.setJoin(BEVEL) strokes.updateMiterLimit(8) strokes.commitMiterLimit(8)setCap / setJoin批量更新与撤销批处理createStrokeGeometryActionshelpers.ts内部维护一个“改动运行器”runForSelection选中多个节点时用editor.undo.runBatch(label, run)把所有更新包进同一撤销批次单个节点则直接执行。setCap除了更新节点级strokeCap还会把每条描边的cap同步为新值若 vectorNetwork 中存在顶点级strokeCap覆盖则通过cloneVectorNetwork克隆网络并删除所有顶点覆盖保证选择器表达的是整条路径的意图对导入的一头箭头尤其关键。setJoin同样同步节点级与描边级字段。updateMiterLimit / commitMiterLimit预览-提交模式这是一个典型的“拖动预览、松手提交”交互updateMiterLimit(value)先把每个节点的原始strokeMiterLimit记录进originalMiterLimits映射首次再以Math.max(1, value)钳制后通过editor.updateNode不记撤销即时预览commitMiterLimit(value)若尚无原始记录则先执行一次预览然后用runForSelection把每个节点的值恢复为原始值并记入单个撤销批次标签Change stroke miter limit最后清空映射。所以用户在输入框中的每次输入只是“预览”一旦提交整段连续调整会合并为一次可撤销操作。在 StrokeGeometryControls.vue 中NumberField的update:model-value接updateMiterLimit、commit接commitMiterLimit且:min1与源码钳制逻辑一致。场景图侧strokeMiterLimit的默认值由 packages/scene-graph/src/constants.ts 的DEFAULT_STROKE_MITER_LIMIT 4决定。类型守卫setCap的入参建议先经isStrokeCapValue校验导出自 packages/vue/src/index.ts实现于 helpers.ts面板代码正是这样做的StrokeGeometryControls.vue。九、虚线状态辅助源码补充useStrokeControls返回对象中还包含虚线dash相关辅助helpers.tsdashState(stroke)无dashPattern时返回{ dash: 6, gap: 6, on: false }有则读取首个元素为 dash、第二个元素缺省复用 dash为 gapon: truetoggleDash(stroke)开启/关闭虚线关闭即dashPattern: []数值以Math.max(1, value)保证至少为 1setDash/setGap分别只改 dash 或 gap保持另一值不变。这些函数返回PartialStroke片段由面板的actions.patch合并进节点。编辑器内的虚线控件见 StrokeDashControls.vue它和几何控件一起挂载在 StrokeSettingsPopover.vue 的弹层中。十、在真实属性面板中的接线方式OpenPencil 应用自身的描边面板 StrokeSection.vue 是useStrokeControls最完整的落地示范用useStrokeControls()取得strokeCtx配合PropertyListRootprop-keystrokes渲染描边列表新增按钮使用strokeCtx.defaultStroke对齐下拉用currentAlign(activeNode)updateAlign(...)“侧边”按钮切换expandedSides进入展开态时若节点未开启独立权重则先用selectSide(CUSTOM, ...)以当前粗细初始化四侧收起时再selectSide(ALL, ...)合并StrokeSection.vue仅当advancedActive为真时显示 StrokeSettingsPopover.vue内部再分派给StrokeDashControls与StrokeGeometryControls后者直接消费cap、join、miterLimit与capOptions、joinOptions。PropertyListRoot本身是 SDK 提供的 headless 列表原语propKey判别器会让插槽与动作获得精确的Fill/Stroke/Effect类型其完整说明见 property-list-root 文档即德语文档末尾“Siehe auch”指向的组件。属性面板指南见 guides/property-panels.md其中useStrokeControls被列为描边面板推荐的组合式。十一、小结useStrokeControls()把描边编辑中最容易出错的“状态解析”与“带撤销的变更”封装成一组可组合的函数对齐与侧边的读写、独立四侧粗细、混合选择的MIXED语义、多节点撤销批处理、斜接限制的预览-提交协议以及虚线模式的切换。无论是基于open-pencil/vue构建自定义编辑器还是复用 OpenPencil 的属性面板这套 API 都能让你在不关心场景图细节的前提下用最少的代码获得与内置编辑器一致的交互体验。建议把本文与 composables 索引、property-list-root 以及源码 use.ts / helpers.ts 对照阅读即可完整掌握该领域的设计模式。赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil 属性列表原语深度解析PropertyListRoot 如何驱动填充、描边与效果面板OpenPencil 属性列表原语深度解析PropertyListRoot 如何驱动填充、描边与效果面板 PropertyListRoot 是 OpenPen前端桌面应用AI 应用MCP 服务OpenPencil 设计变量完全指南集合、模式与填充/描边绑定实战OpenPencil 设计变量完全指南集合、模式与填充/描边绑定实战 变量Variables是 OpenPencil 中复用设计令牌Design Tok前端桌面应用AI 应用MCP 服务OpenPencil PropertyListItem 组件详解用 Headless 原语构建填充、描边与效果属性行列表OpenPencil PropertyListItem 组件详解用 Headless 原语构建填充、描边与效果属性行列表 PropertyListItem 是前端桌面应用AI 应用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考