DialKit 是一款用于实时调试界面参数的开源组件库，通过滑块、开关、颜色选择器、XY Pad、弹簧动画等 13 种控件，帮你把任意界面的可调参数"拨"到最舒服的状态。它支持 React、Solid、Svelte、Vue 和原生 JavaScript，一行配置就能在运行的应用里生成一个可拖拽的调参面板。本文用一份完整清单带你逐一认识这 13 种控件：每种怎么定义、返回什么值、适合调什么参数。

13 种控件速览

DialKit 用一个普通对象描述所有控件：键名自动变成标签（camelCase 会转成单词），返回值保持相同的嵌套层级。核心分发逻辑在 ControlRenderer.tsx 中，共识别以下控件类型：

下面按类别逐个讲解 🎛️

滑块三兄弟：数字参数的主力控件

滑块是调参面板里出现频率最高的控件，DialKit 提供了三种写法：

• 元组滑块：[默认值, 最小值, 最大值]，可选第四项作为步进值。
• 步进滑块：[16, 0, 64, 2]，表示以 2 为步长拖动，适合间距这类整数参数。
• 推断滑块：直接写一个裸数字如scale: 1.2，DialKit 会自动推断范围。范围在 0–1 之间时步进 0.01，1–10 时步进 0.1，10–100 时步进 1，超过 100 时步进 10；负数则自动对称扩展。

交互细节同样贴心：点击或拖动调整，聚焦后按Enter可直接输入数值，悬停在数字上点击也能快速编辑；拖出的值会被自动钳制在范围内。

开关、文本与下拉：表单三件套

开关只需给一个布尔值：

const config = { visible: true, title: "Hello", photoShape: { type: "select", options: [{ value: "portrait", label: "Portrait" }], default: "portrait", }, };

• 开关 Toggle：布尔值即默认状态，点按翻转。
• 文本 Text：字符串即默认值，输入框最多长到五行然后滚动，回车换行。如果某个字符串看起来像颜色值（如"#a78bfa"字样本身）却想当文本处理，可显式写{ type: "text" }。
• 下拉 Select：options支持字符串或{ value, label }对象，默认选中第一项；空列表的下拉会被禁用。

颜色选择器：支持 OKLCH 与现代色彩空间

颜色控件的门槛极低——直接写一个 CSS 颜色字符串即可：

accent: "#a78bfa", highlight: "oklch(0.7 0.2 145 / 0.8)",

hex（3/4/6/8 位）、RGB、HSL、OKLCH、Display P3 都会被自动识别。调色器提供 Hex、OKLCH、Display P3 三种输出格式，还带色相和透明度滑杆；当颜色从宽色域转换到窄色域时，会自动降低饱和度以保持亮度和色相不变。需要transparent这类特殊值时，用显式写法{ type: "color", default: "transparent" }。

图片控件：本地上传不上传服务器

图片控件有两种典型用法：给出候选图片列表供切换，或完全留空供用户上传。

cover: { type: "image", options: ["/images/coast.jpg"] }, avatar: { type: "image" }, // 无选项，从空开始，支持上传

支持上传或拖入最大 10 MB的图片，文件会在浏览器本地读成 data URL，不会发送到任何服务器，非常适合调试封面、头像、背景图类参数。

XY Pad 控件：一个旋钮调两个参数

XY Pad 是 DialKit 最有辨识度的控件：在二维面板上拖一个点，同时调节 X 和 Y 两个值。

position: { type: "pad" }, timing: { type: "pad", x: [0.3, 0.1, 1, 0.01], y: [0.2, 0, 1, 0.01], labels: { x: "Duration", y: "Bounce" }, }

• 每条轴复用滑块的[默认, 最小, 最大, 步进?]写法，缺省为[0, -1, 1, 0.01]。
• X 向右增大，Y向上增大；点击靠近网格交点时会自动吸附。
• 按住Shift拖动可锁定一条轴；双击或按Home恢复默认；Escape取消拖动。

返回值始终是{ x, y }对象，坐标轴的自定义标签不影响键名。阴影偏移、动画起点这类双参数场景非常合适。

弹簧与缓动：动画调参专用编辑器

spring和easing两种定义打开的是同一个过渡编辑器，提供三种模式：

spring: { type: "spring", visualDuration: 0.3, bounce: 0.2 }, physics: { type: "spring", stiffness: 200, damping: 25, mass: 1 }, easing: { type: "easing", duration: 0.3, ease: [0.25, 0.1, 0.25, 1] },

切换模式时会保留该模式上次的编辑状态。由于用户可以在模式间切换，返回值类型是TransitionConfig（SpringConfig与EasingConfig的联合）。贝塞尔手柄支持方向键 0.01 步进、Shift + 方向键 0.1 步进。

动作按钮与文件夹：行为与分组

动作 Action不是可写的值，而是一个按钮：点击后以完整点路径调用你传入的onAction回调。

const values = useDialKit("Card", { replay: { type: "action", label: "Replay animation" }, shadow: { _collapsed: true, // 文件夹初始折叠 blur: [12, 0, 40], }, }, { onAction: (path) => { if (path === "replay") replayAnimation(); }, });

文件夹 Folder则是任何嵌套对象都会自动生成的分组容器，可无限嵌套；_collapsed: true让文件夹初始关闭（它只是 UI 元数据，不会出现在返回值里）。面板顶部工具条的"版本菜单"还能把当前所有控件值存为版本（Preset），用Copy可一键复制回生产配置 💪

13 种控件组合起来长什么样

真实项目里，一个面板通常混合使用多种控件。官方示例 PhotoStack.tsx 就是一个缩影：标题用文本控件、照片形状用下拉、阴影色用颜色、偏移和缩放用文件夹内的一组滑块、过渡动画用弹簧、"下一张"用动作按钮——再加上shortcuts选项给滑块绑定快捷键（按住 X 滚动调偏移，按住 O 精细调阴影透明度），整个页面变成了一台"参数调音台"。

面板还支持：

• 快捷键：shortcuts选项按控件路径绑定按键，支持fine / normal / coarse三档精度；
• 持久化：persist: true把值和版本存入localStorage，刷新页面参数不丢；
• 五种框架适配：同一套配置，在 React、Solid、Svelte、Vue、Vanilla 中行为一致。

如何上手 DialKit 控件

安装并挂载根组件后，写一个配置对象就能得到上表全部能力，具体定义格式可查阅 docs/reference.md 的 Controls 一节，类型与默认值的推断规则都来自 DialStore.ts 中的DialConfig。无论你是做产品页面、组件库还是交互动效，这 13 种控件基本覆盖了所有"想在运行中拨一拨"的界面参数 🚀