前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载useOkHCL()是 OpenPencil 的open-pencil/vueSDK 中面向编辑器场景的 OkHCL 适配器它读取节点填充fill与描边stroke上持久化的 OkHCL 颜色意图intent通过带撤销记录的编辑器更新写入节点报告预览时的色域信息并记住每个填充/描边当前选中的字段格式。读完本文你将掌握如何用useOkHCL()在自定义取色器中读写 OkHCL 颜色、管理 RGB/OkHCL 格式切换、处理超出目标色域的色域映射gamut mapping提示以及它和纯转换层useColorModel()的分工边界。为什么需要useOkHCL()OkHCL 意图与可渲染颜色的分离OpenPencil 的场景图节点中填充和描边存储的是可渲染的 RGBA 颜色值它本身无法保留一个超出 sRGB/Display-P3 色域的 OkHCL 源值。为了在编辑体验上保留“用户在 OkHCL 空间里选中的颜色意图”同时让画布渲染始终落在可显示色域内OpenPencil 采用双轨设计可渲染 RGBA存储在Fill.color/Stroke.color上直接参与画布渲染OkHCL 意图以序列化 JSON 载荷的形式写入节点的pluginData键为okhcl常量OKHCL_PLUGIN_KEY见 packages/core/src/color/okhcl.ts。useOkHCL()正是这个“编辑器感知”的适配层它把上述两个轨道绑定到一起任何 OkHCL 修改都会同时更新节点的 RGBA 颜色与pluginData中的意图载荷并通过editor.updateNodeWithUndo()写入撤销栈。文档原文对它的定位是一句话“useOkHCL()读取并修改填充与描边的颜色模型启用/停用 OkHCL 并更新其数值适用于同时接受 RGBA 与感知模型 OkHCL 的高级取色器。”packages/docs/fr/programmable/sdk/api/advanced/use-okhcl.md它与不依赖编辑器上下文、只做转换的useColorModel()的区别是前者负责持久化到 OpenPencil 编辑器后者负责框架无关的转换、通道编辑与滑块呈现。安装与引入useOkHCL属于open-pencil/vue的进阶 APIAdvanced API层级从包根导出import { useOkHCL } from open-pencil/vue导出声明位于 packages/vue/src/index.ts实现位于 packages/vue/src/controls/okhcl/use.tsopen-pencil/vue的安装方式按 packages/vue/README.mdbun add open-pencil/vue open-pencil/core open-pencil/scene-graph canvaskit-wasm该 SDK 是无头headless设计只提供逻辑与结构样式和产品化 UI 由你的应用自行负责。useOkHCL()内部通过useEditor()获取当前编辑器实例因此调用方必须位于provideEditor(editor)提供的组件树内。核心用法读取与更新 OkHCL 颜色读取当前颜色意图import { useOkHCL } from open-pencil/vue const okhcl useOkHCL() const color okhcl.getFillOkHCLColor(node, 0) // 读取节点第 0 个填充的 OkHCL 意图 const strokeColor okhcl.getStrokeOkHCLColor(node, 0) // 读取第 0 个描边返回的OkHCLColor结构定义于 packages/core/src/color/okhcl.tsinterface OkHCLColor { h: number // 色相归一化到 [0, 360) c: number // 色度chroma非负 l: number // 明度clamp 到 [0, 1] a?: number // 透明度clamp 到 [0, 1] }在实现层面读取路径是getFillOkHCLColor()→ 从node.pluginData中过滤pluginId open-pencil且key okhcl的条目反序列化并匹配kind fill与对应index见 packages/core/src/color/okhcl.ts 的getNodeOkHCLPayloads/getFillOkHCL/getStrokeOkHCL。载荷格式为版本化的 JSONinterface OkHCLPayload { version: 1 kind: fill | stroke index: number color: OkHCLColor }解析时parseOkHCLPayload会严格校验version 1、kind合法、index为数字且h/c/l均为数字非法载荷返回null。更新颜色带撤销的增量修改okhcl.updateFillOkHCL(node, 0, { c: 0.2 }) // 只改第 0 个填充的色度其余通道不变 okhcl.updateStrokeOkHCL(node, 0, { h: 210, l: 0.6 })updateFillOkHCL(node, index, patch)接受PartialOkHCLColor增量补丁其流程见 packages/vue/src/controls/okhcl/helpers.ts 的createOkHCLActions以“当前意图优先、RGBA 回退”的方式取得当前值fallbackFillOkHCL若节点尚无 OkHCL 载荷则用rgbaToOkHCL(node.fills[index].color)从当前 RGBA 反向推导颜色缺失时回退到BLACK与补丁合并后调用setNodeFillOkHCL(node, index, merged, colorSpace)通过editor.updateNodeWithUndo(node.id, changes, Change fill OkHCL)写入编辑器——每次修改都进入撤销栈这是它与纯useColorModel最本质的差异。setNodeFillOkHCL底层packages/core/src/color/okhcl.ts会做三件事复制 fills、把合并后的 OkHCL 经okhclToRGBA转回 RGBA 写入fill.color与fill.opacity、然后把序列化后的OkHCLPayload追加回pluginData同时按kindindex过滤掉旧载荷避免重复。颜色空间参数文档配置文件的考量转换方向都以colorSpace: OkHCLColorSpace srgb | display-p3为参数默认srgbokhclToRGBA(color, colorSpace)把 OkHCL 先经toGamut(rgb|p3, oklch)映射进目标色域再converter(rgb|p3)得到具体分量rgbaToOkHCL(color, colorSpace)把 RGBA 按给定色域反解回 OkHCL 坐标。在useOkHCL()的适配层里实际使用的颜色空间并不是写死的createOkHCLActions通过editor.graph.documentColorSpace取文档自身配置文件文档的存储数值即处于该配置文件并在源码注释中明确“颜色按文档配置文件存储两个方向的转换都使用它”。因此当文档配置为 Display-P3 时OkHCL 转换会自动走 P3 分支保证高色域内容不被过早压到 sRGB。字段格式管理RGB 与 OkHCL 之间的记忆useOkHCL()会为每个“填充/描边 节点 下标”组合记住当前选择的字段格式方便构建格式选择器format selectorconst format okhcl.getFieldFormat(node, 0, fill) // rgb | hsl | hsb | okhcl okhcl.setFillFieldFormat(node, 0, okhcl) okhcl.setStrokeFieldFormat(node, 0, rgb)行为细节packages/vue/src/controls/okhcl/helpers.ts 的createOkHCLFieldFormats格式状态保存在 composable 内部的ref(new Mapstring, ColorFieldFormat())键为${kind}:${nodeId}:${index}getFieldFormat优先返回本地记忆的格式若没有记忆则回退为“该槽位已存在 OkHCL 载荷则返回okhcl否则返回rgb”——这让既有 OkHCL 节点在重新打开面板时仍以 OkHCL 呈现切到okhcl是幂等初始化setFillFieldFormat(node, 0, okhcl)会触发ensureFillOkHCL把当前 RGBA 反解出的 OkHCL 意图写入节点撤销记录名为Update fill color model。这正是文档所说的“选择okhcl会从填充/描边当前的 RGBA 颜色初始化意图”。可用的格式选项来自导出的fieldOptionsfieldOptions: [ { value: rgb, label: RGB }, { value: hsl, label: HSL }, { value: hsb, label: HSB }, { value: okhcl, label: OkHCL } ]预览信息渲染色彩空间与色域裁剪画布/预览需要知道当前节点的 OkHCL 意图在目标渲染色彩空间下是否被裁剪const preview okhcl.getFillPreviewInfo(node, 0) // { previewColorSpace: srgb | display-p3, clipped: boolean }previewColorSpace反映文档渲染色彩空间editor.graph.documentColorSpaceclipped表示存储的 OkHCL 意图是否需要经过色域映射才能显示。实现路径packages/core/src/color/management.ts 的resolveOkHCLForPreview目标空间为display-p3时先判断inGamut(p3)超出则clipped true再经toGamut(p3, oklch)映射后输出 P3 坐标的 RGBA 与 CSS 颜色串目标空间为srgb默认时以inGamut(rgb)判断、toGamut(rgb, oklch)映射输出 sRGB 坐标两种路径都返回{ color, cssColor, sourceSpace: oklch, targetSpace, clipped }。从代码结构看getFillPreviewInfo/getStrokePreviewInfo在 packages/vue/src/controls/okhcl/helpers.ts 中只是把“是否已有 OkHCL 载荷”与上述解析结果包装成{ previewColorSpace, clipped }没有载荷时返回{ previewColorSpace: 文档色域, clipped: false }。UI 层可以用clipped显示“该颜色在目标色域外”的警告角标这正是感知色彩模型如 OkHCL相对传统 RGB 编辑器的体验增益。返回 API 全景useOkHCL()完整返回packages/vue/src/controls/okhcl/use.ts成员签名说明getFillOkHCLColor(node, index) OkHCLColor \| null读填充意图getStrokeOkHCLColor(node, index) OkHCLColor \| null读描边意图getFillPreviewInfo(node, index) { previewColorSpace, clipped }填充预览信息getStrokePreviewInfo(node, index) { previewColorSpace, clipped }描边预览信息getFieldFormat(node, index, kind) ColorFieldFormat当前字段格式setFillFieldFormat(node, index, format)设置填充格式切 OkHCL 时初始化意图setStrokeFieldFormat(node, index, format)设置描边格式updateFillOkHCL(node, index, patch)增量修改填充带撤销updateStrokeOkHCL(node, index, patch)增量修改描边带撤销fieldOptionsColorFieldOption[]格式选择器选项RGB/HSL/HSB/OkHCLColorFieldFormat类型为hex | rgb | hsl | hsb | okhcl | (string {})即内置格式之上保持可扩展packages/vue/src/controls/color-model/types.ts。与 useColorModel 的分工转换 vs 持久化文档packages/docs/programmable/sdk/api/advanced/use-okhcl.md明确建议框架无关的转换、通道编辑与滑块呈现请用useColorModel()只有需要把修改持久化到 OpenPencil 编辑器时才用useOkHCL()。useColorModel()packages/vue/src/controls/color-model/use.ts配套文档 use-color-model不需要编辑器上下文接受一个场景图颜色并暴露 Reka 兼容的 RGB/HSL/HSB 计算属性与可选的 OkHCL 意图通过回调对接外部状态import { ref } from vue import { useColorModel } from open-pencil/vue import type { Color } from open-pencil/scene-graph const color refColor({ r: 0.25, g: 0.5, b: 0.9, a: 1 }) const storedOkhcl ref{ h: number; c: number; l: number } | null(null) const model useColorModel({ color, okhcl: () storedOkhcl.value, onUpdateOkHCL: (patch) { storedOkhcl.value { ...storedOkhcl.value, ...patch } }, }) model.updateOkHCLChannel(c, 0.24)两者的典型协作方式从仓库应用层可以印证src/components/properties/FillSection.vue与src/components/properties/stroke/StrokeSection.vue中调用useOkHCL()获取控制对象再经 src/components/properties/paint/okhcl.ts 的createFillOkhclAdapter/createStrokeOkhclAdapter适配为{ fieldFormat, fieldOptions, okhcl, previewColorSpace, clipped, setFieldFormat, updateOkHCL }喂给底层取色 UI 消费——适配层把getFieldFormat的第三个参数按fill/stroke固定下来UI 组件只面对统一的OkHCLControls形状该形状即 packages/vue/src/controls/color-model/types.ts 中的OkHCLControls接口。无 OkHCL 回调时useColorModel的 OkHCL 通道编辑会把补丁经okhclToRGBA转成场景颜色经onUpdate发出即只持久化 RGBA、不保留意图有回调时则走onUpdateOkHCL保留完整意图。转换与色域处理统一复用 OpenPencil 的 culori 后端核心 APIpackages/core/src/color/index.ts重新导出./okhcl与./management的全部函数。在 ColorPickerRoot 中使用组合示例ColorPickerRootpackages/vue/src/primitives/ColorPicker/ColorPickerRoot.vue配套文档 color-picker-root是无头的弹层取色器骨架trigger 槽接收当前 swatch 样式默认槽接收当前场景图颜色。把useOkHCL接入后即可构成“RGBA OkHCL 双模型”的高级取色器script setup langts import { ref } from vue import type { SceneNode } from open-pencil/scene-graph import { ColorPickerRoot, useOkHCL } from open-pencil/vue const okhcl useOkHCL() const node refSceneNode | null(null) const fillIndex 0 const fillColor ref({ r: 0.2, g: 0.5, b: 0.9, a: 1 }) function applyPatch(patch: Partial{ h: number; c: number; l: number; a?: number }) { if (!node.value) return okhcl.updateFillOkHCL(node.value, fillIndex, patch) } /script template ColorPickerRoot :colorfillColor updatefillColor $event template #trigger{ style } button :stylestyle aria-labelEdit fill color / /template template #default select :valueokhcl.getFieldFormat(node, fillIndex, fill) changeokhcl.setFillFieldFormat(node!, fillIndex, ($event.target as HTMLSelectElement).value as any) option v-foropt in okhcl.fieldOptions :keyopt.value :valueopt.value {{ opt.label }} /option /select !-- 亮度滑块示例修改 l 通道 -- input typerange min0 max1 step0.01 :valueokhcl.getFillOkHCLColor(node, fillIndex)?.l ?? 0.5 inputapplyPatch({ l: Number(($event.target as HTMLInputElement).value) }) / span v-ifokhcl.getFillPreviewInfo(node, fillIndex).clipped⚠ 颜色超出当前色域/span /template /ColorPickerRoot /template要点回顾打开/聚焦取色器本身不会触发颜色更新ColorPickerRoot只在update时发出新颜色因此格式切换与意图初始化的时机完全由setFillFieldFormat控制每次滑块输入都经updateFillOkHCL带撤销写入节点同时刷新节点的 RGBA 与pluginData意图clipped信息让 UI 可以即时提示用户“当前意图在文档色域之外”这是 OkHCL 编辑器才有的能力。通道取值范围速查无论是useOkHCL的补丁路径还是useColorModel的通道编辑通道归一化规则一致packages/vue/src/controls/color-model/model.ts 的normalizeOkHCLPatch/applyOkHCLPatch以及 packages/core/src/color/okhcl.ts 的normalizeOkHCLColor通道范围越界处理h色相[0, 360)% 360取模负数加 360c色度[0, ∞)Math.max(0, c)负值截为 0l明度[0, 1]clampa透明度[0, 1]clamp缺省视为 1滑块呈现层的参考常量供自定义滑块 UI 取用chroma 渐变上界OKHCL_CHROMA_MAX 0.4、明度渐变中点OKHCL_LIGHTNESS_MID 0.5、色相预览最小 chroma0.15与退化明度回退值0.7packages/vue/src/controls/color-model/model.ts 第 28–31 行。RGB 通道在 UI 呈现上使用0–255HSL/HSB 饱和度与明度使用0–100OkHCL 明度与透明度使用0–1见 use-color-model 文档 的 Update behavior 一节。相关 API 导航useColorModel框架无关的颜色状态、转换与滑块呈现层无编辑器上下文useFillControls填充面板组合式 API提供defaultFill等useStrokeControls描边面板组合式 API对齐、单边、端点/连接、miter 等ColorPickerRoot无头弹层取色器骨架swatch trigger popover含openChange/cancel交互生命周期应用层集成范例src/components/properties/FillSection.vueconst okhcl useOkHCL()的调用方式、src/components/properties/paint/okhcl.ts填充/描边 OkHCL 适配器。赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐用 useOkHCL 在 OpenPencil 中持久化 OkHCL 感知色彩填充与描边的色空间感知编辑用 useOkHCL 在 OpenPencil 中持久化 OkHCL 感知色彩填充与描边的色空间感知编辑 useOkHCL 是 OpenPencil Vue前端桌面应用AI 应用MCP 服务OpenPencil useOkHCL API将 OkHCL 感知均匀色彩意图持久化到编辑器节点OpenPencil useOkHCL API将 OkHCL 感知均匀色彩意图持久化到编辑器节点 useOkHCL 是 OpenPencil SDK 中面向编前端桌面应用AI 应用MCP 服务OpenPencil 设计变量完全指南集合、模式与填充/描边绑定实战OpenPencil 设计变量完全指南集合、模式与填充/描边绑定实战 变量Variables是 OpenPencil 中复用设计令牌Design Tok前端桌面应用AI 应用MCP 服务上一篇5分钟告别Windows自动休眠NoSleep轻量级防休眠工具全攻略下一篇AMD Ryzen SMU调试工具从硬件黑盒到精细掌控的技术实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考