Knob 旋钮
把连续/离散数值编码为圆周角度的旋转输入控件，为参数密集面板（音频/工业/3D）而生：紧凑圆形 + 相对拖拽（无跳变）+ 双极零位。
基础用法
基础用法
旋钮是紧凑的圆形输入控件：拖拽或键盘改值，值域线性映射到扫角（默认 225° → 495°，共 270°，底部留缺口，像面板旋钮的止档）。指针手势是相对语义：按下不写值、拖动跟随手（大范围调节不会像线性滑块的点击落点那样跳变）。
值域与步长
min / max / step（step=0 视为连续）
min/max 定义值域（非法或 min > max 自动交换容错）；step 吸附步长，0 或负数视为连续（不吸附）。越界值自动夹取。
扫角（start-angle / end-angle）
自定义扫角：300° 满圈感 / 半圆仪表
start-angle/end-angle 自定义扫角（0° = 12 点方向、顺时针，默认 225 → 495 即 270°、底部留缺口）；end-angle 可大于 360（如 510 = 210° 起顺时针 300°）；end-angle <= start-angle 时归一化为最小 1° 扫角（防除零）。
三档手势（interaction）
cursor 圆周跟随 / axis 线性拖拽 / auto 自动解析（默认）
cursor：指针绕轴心的方位角增量驱动值（顺时针增值），旋钮标识性手势；axis：线性拖拽（默认axis="vertical"竖直、向上增值，150px 拖满量程；axis="horizontal"切水平向右增值）——专业音频插件的通行惯例；auto（默认）：起手前几像素自动解析——主方向与偏好轴一致走线性、垂直于偏好轴走圆周，解析后一次锁定，同一次拖拽内不再切换（中途切换会跳值）。
所有手势均为相对语义：按下不写值、无移动点按零操作；主指针独占（第二指不接管）；Shift 按住拖拽为 0.2× 精调。
复位（双击 / Ctrl+单击 / default-value）
双击或 Ctrl+单击复位到 default-value（缺省回落 min）
双击或 Ctrl/Cmd + 单击复位到 default-value；未设 default-value 时回落 min。复位派发 oas-reset（detail: { value, defaultValue }），不派发 oas-change（复位不是一次数值确认）；readonly/disabled 下复位手势全封。程序性复位用 el.reset() 方法。
值弧与双极零位（include-arc + start-point）
include-arc 值弧；start-point=中心值即双极（pan/gain）
include-arc 显示值弧（从 start-point 缺省 min 端填到当前值）；start-point 设为中心值即双极弧——值大于起点向一侧延伸、小于向另一侧延伸（pan/gain 以 12 点为中性位的音频惯例）。值与起点重合时值弧隐藏。
指示器（indicator）
line 指针（默认）/ dot 圆点
indicator="line" 为径向指针线（默认），indicator="dot" 为近缘圆点。
显示值（show-value / unit / format）
show-value 值文本 + unit 后缀 / format 模板串
show-value 在旋钮下方显示当前值；unit 作值后缀（Hz/%/dB）；format 为模板串（${value} 占位）。格式化输出同时进 aria-valuetext（读屏播报与视觉同源）；更复杂的格式化用 el.formatValue = (value) => string 函数 property（优先级最高，置 null 清除）。
尺寸
size 三档（sm / md / lg），自定义直径走 CSS 变量
size 三档对应直径 sm=40px / md=56px（默认）/ lg=72px（也接受 small/medium/large 词表，支持 config-provider 全局注入），非法值回落 md；自定义直径直接覆盖 CSS 变量 --oas-knob-size。触屏（粗指针）下 sm 档自动抬到 44px 触控目标下限。
滚轮（wheel）
wheel 悬停滚轮调节（默认关）
wheel 开启后悬停滚轮即可调节（上滚增值、下滚减值，一格 = step；连续模式为量程的 1/50）。滚轮不做修饰键分支（恒按 step）；精细调节用 Shift+拖拽（0.2×）。默认关闭（避免抢占页面滚动）。
反向（reverse）
reverse 反向：值扫描与圆周手势同步镜像（min 从 end-angle 端起）
reverse 反转值扫描方向（min → end-angle、max → start-angle），圆周手势与键盘左右键同步镜像；RTL 书写方向（dir="rtl"）自动镜像，与 reverse 取异或。
键盘
键盘大步进（large-step）
聚焦旋钮后：方向键 ± step（上下键恒为增/减值，左右键随镜像翻转）、Shift + 方向键与 PageUp/PageDown ± large-step（缺省 10 × step）、Home/End 到极值。每次按键即一次完整提交（派发 oas-input + oas-change），极值处按键安静（不派发事件）。
只读与禁用
readonly 只读（不灰显）/ disabled 禁用（灰显、不可聚焦）
readonly 与 disabled 分立（同 slider 约定）：只读旋钮仍可聚焦、值仍参与宿主收集，但拖拽/键盘/滚轮/复位全部拦截，视觉不降饱和；禁用旋钮不可聚焦（移除 tabindex）、aria-disabled="true"、灰显。
可访问名（label）
label 可访问名（不渲染可见标签，可见标签由 oas-form-item 承担）
label 写入旋钮的 aria-label（缺省回落内置文案「旋钮」）。旋钮不内置可见标签——用 oas-form-item 的 label 提供可见标签（点击可聚焦旋钮）。
事件
拖拽 / 键盘 / 复位事件（oas-input 实时、oas-change 提交、oas-drag-* 起止、oas-reset 复位）
事件契约（detail 均带 value）：
oas-input：拖拽中 / 滚轮 / 键盘每次改值（实时）；oas-change：松手提交 / 键盘、滚轮每次完整确认（取消与零变化松手不派发）；oas-drag-start：指针按下并发生有效移动（无移动点按不派发）；oas-drag-end：松手（cancelled: false）或取消（cancelled: true，此时不派发oas-change）；oas-reset：双击 / Ctrl+单击 /reset()复位后（detail: { value, defaultValue }）。
触屏与边界
- Pointer Events 统一鼠标/触屏（
touch-action: none接管拖拽、主指针独占、pointercancel取消回滚）； - 拖拽中按 Esc 取消：回滚到起点值、零提交（不派发
oas-change）； - 拖拽中的复位手势（双击 / Ctrl+单击）被忽略，指针捕获被外部夺走（
lostpointercapture）即取消回滚；程序reset()在拖拽中调用则先取消拖拽再复位； wheel仅响应纵向滚动（deltaY），横向触控板平移不调值；formatValue函数抛错时自动降级到format模板 /unit后缀 / 裸数字（渲染与手势不中断）；- 拖拽中外部写
value：显示保持拖拽值，松手时若拖拽已产生提交则拖拽值落盘，零变化松手则外部值保留显示； - 触屏辅助技术对自定义 slider 手势的支持可能不完整（W3C ARIA APG 提示），移动端生产使用前请做真实 AT 测试。
API
oas-knob
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
axis | 线性拖拽轴：vertical（默认，向上增值、150px 拖满量程）/ horizontal（向右增值）；interaction=auto 下作为偏好轴 | string | — |
default-value | 复位目标值：双击 / Ctrl+单击 / reset() 复位到此值（吸附+夹取）；缺省回落 min；复位派发 oas-reset（不派发 oas-change） | number | null | — |
disabled | 禁用：不可聚焦（移除 tabindex）、拖拽/键盘/滚轮/复位全封、aria-disabled="true"、灰显（opacity .6） | boolean | — |
end-angle | 扫角终点（默认 495，即 270° 扫角、底部留缺口）；可大于 360（如 510 = 210° 起顺时针 300°），sweep 上限 360 | — | — |
format | 值格式化模板串：${value} 占位符替换为当前值（如 "${value} dB"）；输出同时进值文本与 aria-valuetext；优先级低于 formatValue 函数 | string | — |
include-arc | 显示值弧：从 start-point（缺省 min）端填到当前值；值与起点重合时弧隐藏（防 round linecap 出圆点） | boolean | — |
indicator | 指示器形态：line（径向指针线，默认）/ dot（近缘圆点）；非法值回落 line | string | — |
interaction | 手势模型：cursor（指针方位角增量驱动，顺时针增值）/ axis（线性拖拽）/ auto（默认——起手前几像素解析：主方向与偏好轴一致走线性、垂直走圆周，解析后一次锁定不中途切换）；相对语义：按下不写值、无移动点按零操作、主指针独占 | string | auto |
label | 旋钮可访问名（aria-label，不渲染可见标签——可见标签由 oas-form-item 承担）；缺省回落内置 i18n 文案「旋钮」 | string | — |
large-step | 键盘大步步进量（Shift+方向键 / PageUp / PageDown 生效）；缺省为 10 × step（连续模式为量程 / 10） | string | — |
max | 值域上界（默认 100） | string | 100 |
min | 值域下界（默认 0）；非法或 min > max 自动交换容错 | string | 0 |
readonly | 只读（与 disabled 分立）：仍可聚焦、值仍参与宿主收集，拖拽/键盘/滚轮/复位全部拦截，视觉不降饱和，aria-readonly="true" | boolean | — |
reverse | 反向：值扫描镜像（min → end-angle、max → start-angle），圆周手势与键盘左右键同步镜像；与 RTL 书写方向取异或 | boolean | — |
show-value | 在旋钮下方显示当前值文本（经 formatValue 函数 / format 模板 / unit 后缀格式化，与 aria-valuetext 同源） | boolean | — |
size | 尺寸三档：sm（40px）/ md（56px，默认）/ lg（72px），也接受 small / medium / large 词表（支持 config-provider 注入），非法值回落 md；自定义直径走 CSS 变量 --oas-knob-size；触屏下 sm 档自动抬到 44px 触控目标下限 | string | medium |
start-angle | 扫角起点（0° = 12 点方向、顺时针，默认 225）；end-angle <= start-angle 时归一化为最小 1° 扫角 | — | — |
start-point | 值弧起点（缺省/非法回落 min，自动夹取到值域）；设为中心值即双极弧——值大于起点向一侧延伸、小于向另一侧延伸（pan/gain 双向零位） | string | — |
step | 吸附步长（默认 1）；0 或负数视为连续（不吸附） | string | 1 |
unit | 值后缀（如 Hz/%/dB）：输出进 show-value 值文本与 aria-valuetext；优先级低于 format 模板与 formatValue 函数 | string | — |
value | 当前值（受控）：越界自动夹取到 [min, max] 并按 step 吸附；交互后写回属性（宿主可直接读属性取最新值） | number | 0 |
wheel | 悬停滚轮调节（默认关）：上滚增值、下滚减值，一格 = step（连续模式为量程 1/50）；修饰键不改变步长（精调走 Shift+拖拽）；开启后 preventDefault 阻止页面滚动 | boolean | — |
Property（JS property；是否写回 attribute 见各行说明）
| Property | 说明 | 类型 | 默认值 |
|---|---|---|---|
defaultValue | 复位目标值：读 default-value 属性（未设返回 null = 回落 min）；写数值反射到属性，写 null 清除 | number | null | — |
formatValue | 值格式化函数：el.formatValue = (value) => string，输出同时进 show-value 值文本与 aria-valuetext，优先级高于 format 属性与 unit 后缀，置 null 清除 | ((value: number) => string | number | null | undefined) | null | — |
value | 当前值：读返回夹取+吸附后的数值（拖拽中为拖拽实时值），写为受控赋值即生效（写受控属性并强制同步，不派发事件） | number | — |
事件
| 事件 | 说明 |
|---|---|
oas-change | 松手提交 / 键盘与滚轮每次完整确认派发，detail: { value }；取消（Esc/pointercancel）与零变化松手不派发 |
oas-drag-end | 拖拽结束派发，detail: { value, cancelled }；cancelled=true 表示取消路径（已回滚到起点值，不派发 oas-change） |
oas-drag-start | 指针按下并发生有效移动（≥ 阈值）后派发，detail: { value }（起点值）；无移动点按不派发 |
oas-input | 拖拽中 / 滚轮 / 键盘每次改值实时派发，detail: { value }（吸附后的当前值） |
oas-reset | 复位手势（双击 / Ctrl+单击 / reset()）后派发，detail: { value, defaultValue } |
CSS 变量
| CSS 变量 | 说明 | 默认值 |
|---|---|---|
--oas-knob-body | 旋钮盘体颜色 | var(--oas-color-bg-elevated) |
--oas-knob-fill | 值弧颜色（include-arc 开启时） | var(--oas-color-primary) |
--oas-knob-indicator | 指示器（指针线/圆点）颜色 | var(--oas-color-text-secondary-strong) |
--oas-knob-size | 旋钮直径（尺寸档 sm=40px / md=56px / lg=72px 的档值载体，直接覆盖即自定义直径） | 56px |
--oas-knob-track | 轨道弧颜色（全量程扫角弧） | var(--oas-color-border) |
--oas-knob-value-color | show-value 值文本颜色 | var(--oas-color-text-secondary) |