前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载GradientEditorStop是 OpenPencil开源、AI 原生的 Figma 替代设计编辑器Vue SDK 中用于构建渐变编辑器的核心原语组件它封装了一个渐变停靠点gradient stop的位置、透明度、颜色与激活状态并提供更新与删除动作。本文基于官方 SDK 文档页 gradient-editor-stop.md 及其英文对照文档 gradient-editor-stop.md结合 组件源码 与配套组合式函数 useGradientStops.ts完整讲解该组件的 Props、事件、插槽、键盘交互与 ARIA 细节帮助你在自定义编辑器外壳editor shell中直接复用这套渐变停靠点 UI。组件定位渐变编辑器三件套之一OpenPencil 的 Vue SDK 将渐变编辑器拆分为三个原语组件并在 packages/vue/src/index.ts 中统一导出GradientEditorRoot编辑器根容器负责整体布局与状态聚合GradientEditorBar渐变色条展示渐变预览并承载停靠点GradientEditorStop单个停靠点。它是多态polymorphic元素渲染一个可选中、可拖拽的渐变停靠点并带有文档化的选中态selected与拖拽态dragginguseGradientStops配套的组合式函数composable为渐变编辑器提供停靠点的状态管理与变更辅助方法。从文档页的组织方式看这三个组件共享同一套 API 文档生成管线文档侧通过 gradient-editor-stop.data.ts 声明import { defineComponentMetaLoader } from #docs/sdk/component-meta export default defineComponentMetaLoader([ packages/vue/src/primitives/GradientEditor/GradientEditorStop.vue ])再由页面中的SdkComponentAPI :componentsdata.components /组件自动从.vue源码中提取并渲染 API 参考表。也就是说文档中的 API 表格并非手写而是由 组件元数据加载器 直接从真实源码推导而来保证了文档与实现的一致性。底层数据模型GradientStop组件操作的数据结构定义在 packages/scene-graph/src/types.tsexport interface GradientStop { color: Color position: number }其中Color定义在 packages/scene-graph/src/primitives.ts是一个r/g/b/a四通道分量0–1 浮点数。停靠点的position是 0–1 的归一化比例GradientStop作为可选字段gradientStops挂在场景图的Fill类型上与gradientTransformGradientTransform Matrix一起完整描述一个渐变填充。组件内部在 0–1 比例与 0–100 百分比之间做换算positionPercent Math.round(stop.position * 100)、opacityPercent Math.round(stop.color.a * 100)对外事件如update-position也统一以百分比为参数避免调用方处理浮点比例。Props停靠点的完整输入组件基于 reka-ui 的Primitive构建因此继承了多态渲染能力可通过as/asChild改变渲染元素。Props 类型GradientEditorStopProps定义在 packages/vue/src/primitives/GradientEditor/types.ts默认值来自 .vue 源码的解构Prop类型默认值说明stopGradientStop必填停靠点数据含color四通道颜色与position0–1 比例indexnumber必填停靠点在列表中的索引随所有事件一并回传activeboolean必填当前是否被选中映射到data-selected与selected插槽属性draggingbooleanfalse是否处于拖拽中映射到data-dragginginteractivebooleantrue是否进入滑块 Tab 顺序并响应键盘false时仅保留视觉与插槽能力removablebooleantrue是否允许 Delete / Backspace 触发remove事件positionStepnumber1方向键每次微调的百分比步长按住 Shift 时放大 10 倍labelstring—无障碍标签缺省回退为Gradient stop ${index 1}asstringdiv多态渲染元素asChildbooleanfalse将行为合并到唯一子元素上reka-ui PrimitiveProps事件Emits五个以索引为上下文的动作组件发出的每个事件都携带停靠点索引调用方无需自行维护是哪个点的上下文事件载荷触发时机select[index: number]点击或获得焦点时update-position[index: number, position: number]键盘微调后position为 0–100 的百分比update-color[index: number, hex: string]通过插槽actions.updateColor提交十六进制颜色update-opacity[index: number, opacity: number]通过插槽actions.updateOpacity提交不透明度0–100remove[index: number]Delete / Backspace需removable或行内删除按钮源码中这些 emit 被封装进actions对象GradientEditorStopActions类型通过默认插槽暴露给模板因此即便不依赖键盘交互也可以为每个动作绑定自定义 UItemplate #default{ stop, index, active, positionPercent, hex, css, actions } button clickactions.select :aria-pressedactive {{ positionPercent }}% /button /template插槽属性与 actions默认插槽GradientEditorStopSlotProps一次性给出渲染与操作所需的全部派生值stop/index原始数据active与selected两者同义selected是active的别名便于模板语义化dragging拖拽态配合data-dragging属性做 CSS 联动positionPercent/opacityPercent取整后的百分比可直接用于left: X%定位或文本展示hex/css由open-pencil/core/color的colorToHexRaw/colorToCSS计算得出的颜色字面量可直接填入样式actions{ select, updatePosition, updateColor, updateOpacity, remove }五个方法均已绑定好index。组件根元素自身还固定输出data-slotstop方便外部样式以[data-slotstop]选择器精准命中。键盘交互与 ARIA可访问性实现细节交互式停靠点interactive默认开启使用slider 角色进入无障碍树roleslider、tabindex0并暴露aria-label、aria-valuemin0、aria-valuemax100、aria-valuenow当前百分比与aria-valuetext如50%原生 Tab 顺序在各停靠点之间循环。键盘行为由源码中的onKeydown实现要点如下ArrowLeft/ArrowDown位置减去positionStepArrowRight/ArrowUp位置加上positionStep按住Shift时步长放大 10 倍positionStep * 10Home/End直接跳到 0% / 100% 两端边界Delete/Backspace在removable为真时触发remove新位置统一经Math.max(0, Math.min(100, nextPosition))钳制所有已处理的按键都执行preventDefault()stopPropagation()避免编辑器的全局删除、移动快捷键被误触发interactive为false时整个onKeydown直接短路返回元素也不设置role、tabindex与 ARIA 值属性。interactivefalse非交互模式当你在组合式停靠点行composite stop row例如色块 数值输入 删除按钮的列表行中复用该原语时应设置interactivefalse。此时组件仍会暴露完整的插槽actions与data-selected/data-dragging状态属性但不进入 slider 的 Tab 顺序、不响应方向键——把键盘语义交给外层容器避免嵌套焦点混乱。实战示例官方英文文档页给出的最小可运行示例依赖open-pencil/vue与open-pencil/scene-graph两个 workspace 包script setup langts import type { GradientStop } from open-pencil/scene-graph import { GradientEditorStop } from open-pencil/vue const stop: GradientStop { color: { r: 0.4, g: 0.2, b: 0.9, a: 1 }, position: 0.5 } /script template GradientEditorStop :stopstop :index0 active labelMiddle gradient stop update-position(_index, position) console.log(position) / /template该组件是受控组件update-position只发出新百分比真正的状态写入由父级通常经由useGradientStops完成后再回传新的stop形成单向数据流。与 useGradientStops 组合状态管理与边界保护useGradientStops.ts 提供了将GradientEditorStop事件接入场景图Fill的完整状态层。其签名是useGradientStops(fill: RefFill, onUpdate: (fill: Fill) void)内部实现了几条值得注意的边界规则addStop()新停靠点插入在最后两个停靠点位置的中点不足两个时取 0.5颜色继承当前激活停靠点插入后按position排序并选中removeStop(index)当停靠点数量 2时拒绝删除渐变至少保留两端点删除后修正activeStopIndex避免越界updateStopPosition(index, position)把组件发出的 0–100 百分比换算回 0–1 比例并写回fill.gradientStopsupdateStopOpacity(index, opacity)不透明度同样以百分比输入、0–1 钳制后写回stop.color.asetSubtype(type)支持GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND四种渐变类型切换切换时自动应用DEFAULT_TRANSFORMS中对应的默认渐变矩阵barBackground计算linear-gradient(...)的 CSS 预览字符串供GradientEditorBar渲染渐变预览颜色编辑复用useColorModel组合式函数updateStopColor会先selectStop(index)再更新 hex。从源码结构看推荐的接线方式是将useGradientStops返回的stops/activeStopIndex/addStop/removeStop等绑定到GradientEditorRootGradientEditorBar 多个GradientEditorStop事件载荷中的index与 composable 的方法参数一一对应即可实现一个数据流清晰、键盘完全可用的渐变编辑器。参见GradientEditorRoot 文档GradientEditorBar 文档组件类型定义packages/vue/src/primitives/GradientEditor/types.ts组件实现packages/vue/src/primitives/GradientEditor/GradientEditorStop.vue场景图数据模型packages/scene-graph/src/types.ts赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil SDK useGradientStopsVue Composable 驱动的渐变停止点状态管理与变更逻辑OpenPencil SDK useGradientStopsVue Composable 驱动的渐变停止点状态管理与变更逻辑 useGradientStop前端桌面应用AI 应用MCP 服务深入 OpenPencil Vue SDK 的 Locale API低层国际化状态与语言切换机制深入 OpenPencil Vue SDK 的 Locale API低层国际化状态与语言切换机制 本文基于 OpenPencil 官方文档 locale ap前端桌面应用AI 应用MCP 服务open-pencil GradientEditorBar 详解用 Headless Vue 原语构建可拖拽的渐变 Stop 条open pencil GradientEditorBar 详解用 Headless Vue 原语构建可拖拽的渐变 Stop 条 本文基于 open penc前端桌面应用AI 应用MCP 服务上一篇英雄联盟Akari助手免费开源的游戏效率提升神器完整使用指南下一篇dbt-core 中的 MiniJinja minimal 示例零默认特性下的模板引擎最小化接入实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考