@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.13

package/es/SelectorPicker/component.json

@@ -0,0 +1,179 @@
+{
+    "name": "SelectorPicker",
+    "category": "Data Entry",
+    "description": "选择器弹出框，Selector 的弹出框封装",
+    "semantic": {
+        "intent": [
+            "弹出选择",
+            "下拉选择器"
+        ],
+        "useCases": [
+            "表单选择",
+            "快速选择",
+            "弹出式选择"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "受控选中值;multiple=true 时为对象数组 Record<string,any>[],false 时为单对象 Record<string,any>;清空时 onChange 入参为 null。外部以 string[] key 列表受控时,挂入前用 useMemo data.filter 反查为对象数组(见 api.ts 顶部 C 协议)"
+        },
+        "defaultValue": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "非受控默认值;类型规则同 value"
+        },
+        "onChange": {
+            "type": "(val: Record<string,any>[] | Record<string,any> | null, node: Record<string,any>, rowData: Record<string,any>) => void",
+            "description": "值变化回调;multiple 时 val 为数组,否则为单对象;清空时 val=null(回写外部 string[] 时需 ?? [] 兜底);node=节点处理后数据、rowData=原始数据"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否多选;true 时 value/defaultValue 必须为数组,onChange 入参 val 也为数组"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否支持清除已选值;true 时悬停显示清除按钮,触发顺序:onClear() → onChange(null)"
+        },
+        "selectorProps": {
+            "type": "Omit<SelectorProps, 'layout' | 'disabled' | 'value' | 'defaultValue' | 'onChange' | 'selectMode'>",
+            "description": "透传给底层 Selector 的属性(data/url/fieldConfig/rowKey/breadcrumbsHead/searchOption/backDataFieldConfig 等);Omit 列出的字段已被 SelectorPicker 接管不可透传;常用子字段速查见 api.ts 顶部 E 协议"
+        },
+        "tagRender": {
+            "type": "(item: Record<string, any>) => React.ReactNode",
+            "description": "多选 tag 自定义渲染;入参为已选 list 项对象"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "输入框尺寸"
+        },
+        "placeholder": {
+            "type": "string",
+            "default": "请选择",
+            "description": "未选中时占位文本"
+        },
+        "getPopupContainer": {
+            "type": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "浮层挂载容器;默认 body,Modal 内必传 trigger.parentNode 避免点击穿透"
+        },
+        "label": {
+            "type": "React.ReactNode",
+            "description": "标签文案;支持节点(可嵌图标 / Tooltip 触发器)"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填;true 时 label 前渲染红色 *"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用整个选择器(无法点击展开浮层、无法清除)"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态;输入框边框变红,搭配 helperText 显示错误信息"
+        },
+        "helperText": {
+            "type": "React.ReactNode",
+            "description": "辅助文本;error=true 时显示为错误信息,否则显示为常规说明"
+        },
+        "overLine": {
+            "type": "boolean",
+            "description": "多选时已选项是否换行;true 换行,false 单行折叠显示 +N"
+        }
+    },
+    "do": [
+        "配合 Selector 使用(SelectorPicker 是 Selector 的弹出框封装,所有候选数据走 selectorProps.data 透传给底层 Selector)",
+        "外部以 string[](key 列表)受控时,用 useMemo data.find 反查映射为 Record<string,any>[] 后挂入 value(详见 api.ts §C 反向映射模式)",
+        "二次封装业务组件时,JSX 内 **受控 prop 写在 {...pickerProps} spread 之后**,后写覆盖保护受控状态(详见 api.ts §D)",
+        "提供清空功能(allowClear=true + onClear 监听,onChange 入参 val=null 时回写外部 string[] 用 `?? []` 兜底)"
+    ],
+    "dont": [
+        "传 `visible` / `open` / `show` 显隐控制 prop(本组件不存在;父层条件渲染 `{showPicker && <SelectorPicker ... />}` 控制 mount;见 api.ts §A)",
+        "selectorProps 透传 `layout` / `disabled` / `value` / `defaultValue` / `onChange` / `selectMode`(已被 SelectorPicker 接管,类型已 Omit,透传无效)",
+        "selectorProps 写错字段名:`list`(应为 `data`)/ `keys`(应为 `rowKey`)— 内部不消费会静默失败",
+        "二次封装时 `pickerProps?: any` **作为推荐签名**(❌ 不能阻止外部覆盖受控;✅ 推荐 `Omit<SelectorPickerProps, 'value'|'defaultValue'|'onChange'|'multiple'|'selectorProps'>`);**但若需求模板硬性要求 any 签名,见 interpretivePriority 兼容路径**",
+        "弹窗内容过于复杂",
+        "忽略 placeholder"
+    ],
+    "interpretivePriority": {
+        "principle": "**需求模板接口 `pickerProps: any` 与本组件 §D 协议推荐 Omit<...> 冲突时,严格按需求接口签名(api.ts §D-bis 兼容路径)**",
+        "reason": "需求接口(requirements/*.json)是观察者制定的固定 spec · 优化 AI 无权改;§D 协议 Omit<...> 是组件库的安全推荐 · sub-agent 不应擅自改需求接口签名;但 anti-pattern any 接口在运行时仍需保护受控状态 → 通过 JSX spread 顺序(受控 prop 写在 spread 之后)实现",
+        "resolution": "1. 接口签名照搬需求 `pickerProps: any`(不改) ;2. JSX 写法严格遵 §D 协议(`{...pickerProps} value={...} onChange={...} multiple` — 受控 prop 后写覆盖) ;3. 类型安全靠运行时 spread 顺序,不靠类型层面阻断;详见 api.ts §D-bis 完整代码示例",
+        "dataSourceDecisionTree": "data 来源根据需求接口字段决定:(1)接口含 data prop → 直接 selectorProps={{data}} 透传;(2)接口不含 data 字段,只有 pickerProps → 候选数据从 pickerProps.selectorProps.data 透传(`selectorProps={{ ...(pickerProps?.selectorProps ?? {}) }}`),封装层不内置;(3)需求语义为内置固定数据(如部门选择) → 封装层 const data = [...] 然后 selectorProps={{data}};详见 api.ts §D-ter",
+        "antiPatterns": [
+            "❌ 看到需求接口 `pickerProps: any` 后,擅自改为 Omit<...> 违背需求 spec",
+            "❌ 接口写 any,JSX 把 spread 放在受控 prop 之后(`<SelectorPicker value={...} onChange={...} {...pickerProps} />` — 外部 pickerProps 覆盖受控状态)",
+            "❌ 二次封装时,封装层 hardcode 候选数据而不查需求接口字段(需求接口若含 data prop 应透传,不应硬编码)"
+        ],
+        "correctPatterns": [
+            "✅ 接口签名 `pickerProps: any`(照搬需求) + JSX `<SelectorPicker {...pickerProps} value={...} onChange={...} multiple selectorProps={{ data }} />`(受控后写覆盖)",
+            "✅ 看需求接口:若有 data prop → `selectorProps={{ data }}`;若无 data 字段但有 pickerProps → `selectorProps={{ ...(pickerProps?.selectorProps ?? {}) }}`(透传外部数据);若需求要求'内置部门列表'业务语义 → 封装层 const data = [...] hardcode"
+        ]
+    },
+    "events": {
+        "onChange": {
+            "signature": "(val: Record<string,any>[] | Record<string,any> | null, node: Record<string,any>, rowData: Record<string,any>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选时 val 是单对象，多选时 val 是对象数组，清空时 val 是 null",
+                "受控外部 string[] 场景：onChange={(val) => setIds(val ? (Array.isArray(val) ? val : [val]).map(it => it[rowKey]) : [])}",
+                "清空时兜底：setIds((val ?? []) instanceof Array ? val.map(it => it.key) : [])"
+            ],
+            "commonMistakes": [
+                "清空时期望 val 是 [] 而非 null——清空时 val=null，需 ?? [] 兜底",
+                "multiple=false 期望 val 是数组——单选 val 是单对象，需按模式分支处理",
+                "忽略第二三参 node/rowData——node 是内部处理后的数据，rowData 是原始数据，两者都是对象 Map（key=rowKey）"
+            ]
+        },
+        "onClear": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户点击清除按钮时先触发 onClear，再触发 onChange(null, {}, {})",
+                "受控场景需同时监听 onClear 和 onChange 才能完整捕获清空"
+            ],
+            "commonMistakes": [
+                "只监听 onClear 而不监听 onChange——受控 value 不会自动清空，需在 onChange 里同步 state",
+                "allowClear=false 时期望 onClear 触发——allowClear=false 不显示清除按钮，onClear 不会触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "selectorProps 透传了已被 SelectorPicker 接管的字段（如 layout/disabled/value/onChange/selectMode），TypeScript 报 Omit 类型错误",
+            "wrong": "selectorProps={{ layout: 'lr', value: [...], onChange: handler }}  // 这些字段已 Omit",
+            "right": "selectorProps={{ data: [...], rowKey: 'id', fieldConfig: { mainTitle: 'name' } }}  // 只传未 Omit 的字段"
+        },
+        {
+            "issue": "multiple=true 时 value 传单对象而非数组，受控不生效",
+            "wrong": "multiple={true} value={{ key: '1' }}  // multiple 时 value 必须是 Record<string,any>[]",
+            "right": "multiple={true} value={[{ key: '1' }]}  // 数组包裹"
+        },
+        {
+            "issue": "selectorProps 传 data 字段名拼错（如 list/items），候选数据静默失败",
+            "wrong": "selectorProps={{ list: myData }}  // Selector 内部读 data，不读 list",
+            "right": "selectorProps={{ data: myData }}  // Selector prop 名是 data"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SelectorPicker",
+        "adapter": null
+    }
+}

package/es/SelectorPicker/index.d.ts

@@ -31,15 +31,15 @@ export interface SelectorPickerProps extends HelperTextDetailProps {
     /** 支持清除 */
     allowClear?: boolean;
     /** 值 */
-    value?: Record<string, any>[] | Record<string, any>;
+    value?: Record<string, unknown>[] | Record<string, unknown>;
     /** 默认值 不受控 */
-    defaultValue?: Record<string, any>[] | Record<string, any>;
+    defaultValue?: Record<string, unknown>[] | Record<string, unknown>;
     /** 自定义tag内容 */
-    tagRender?: (item: any) => ReactNode;
+    tagRender?: (item: Record<string, unknown>) => ReactNode;
     /** 清除回调 */
     onClear?: () => void;
     /** 改变事件 val绑定值, node处理过的数据 rowData原始数据 */
-    onChange?: (val: Record<string, any>[] | Record<string, any> | null, node: Record<string, any>, rowData: Record<string, any>) => void;
+    onChange?: (val: Record<string, unknown>[] | Record<string, unknown> | null, node: Record<string, unknown>, rowData: Record<string, unknown>) => void;
     /** 选择器属性 */
     selectorProps?: Omit<SelectorProps, 'layout' | 'disabled' | 'value' | 'defaultValue' | 'disabled' | 'onChange' | 'selectMode'>;
     /** 浮层渲染容器 */
@@ -48,7 +48,7 @@ export interface SelectorPickerProps extends HelperTextDetailProps {
     morePopoverClassName?: string;
     /** 下拉框className */
     overlayClassName?: string;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const SelectorPicker: React.FC<SelectorPickerProps>;
 export default SelectorPicker;

package/es/SelectorPicker/index.js

@@ -1,7 +1,7 @@
 import { j as r } from "../_virtual/jsx-runtime.js";
 import { useState as b, useRef as Q, useEffect as U } from "react";
 import X from "clsx";
-import ye from "../HelperText/index.js";
+import Ne from "../HelperText/index.js";
 import Pe from "../Label/index.js";
 import { Dropdown as $e } from "../Dropdown/index.js";
 import Te, { handFieldConfig as Ve } from "../Selector/index.js";
@@ -20,7 +20,7 @@ const er = (C) => {
     className: Z,
     label: S,
     value: w,
-    defaultValue: N,
+    defaultValue: y,
     required: z = !1,
     labelTooltip: _,
     error: D = !1,
@@ -35,10 +35,10 @@ const er = (C) => {
     allowClear: H = !1,
     overLine: f = !1,
     selectorProps: L,
-    onChange: F,
+    onChange: A,
     onClear: ne,
     tagRender: a,
-    morePopoverClassName: A,
+    morePopoverClassName: F,
     getPopupContainer: oe,
     overlayClassName: se
   } = C, u = {
@@ -48,12 +48,12 @@ const er = (C) => {
     ),
     ...C.selectorProps?.backDataFieldConfig
   }, [K, ce] = b(
-    N || []
-  ), [O, j] = b(!1), [R, q] = b(!1), [s, y] = b(null), h = Q(null), t = Q({ list: [] }), o = `${c}-selector-picker`;
+    y || []
+  ), [O, j] = b(!1), [R, q] = b(!1), [s, N] = b(null), h = Q(null), t = Q({ list: [] }), o = `${c}-selector-picker`;
   t.current.value = w, t.current.valueCom = K, t.current.openMore = R;
   const J = () => t.current.value !== void 0 ? t.current.value : t.current.valueCom, ie = () => {
     const e = J();
-    let l = e ? [e] : [];
+    let l = e ? Array.isArray(e) ? e : [e] : [];
     return e instanceof Array && (l = [...e]), l;
   };
   t.current.list = ie(), U(() => (!f && d ? window.addEventListener("resize", k) : window.removeEventListener("resize", k), () => {
@@ -70,18 +70,18 @@ const er = (C) => {
     if (n)
       if (n.scrollHeight > n.clientHeight) {
         const v = Number(e) - 1;
-        y(v), W(v);
+        N(v), W(v);
       } else
         t.current.list.length <= e && G();
   }, k = () => {
-    if (t.current.list.length === 0) return y(null);
+    if (t.current.list.length === 0) return N(null);
     clearTimeout(t.current.resizeTimer), t.current.resizeTimer = setTimeout(() => {
-      y(t.current.list.length), W();
+      N(t.current.list.length), W();
     }, 50);
   }, B = (e, l, n) => {
     n.stopPropagation(), t.current.list.splice(l, 1), P([...t.current.list], {}, {});
   }, P = (e, l, n) => {
-    F && F(e, l, n), d || j(!1), w === void 0 && ce(e || []);
+    A && A(e, l, n), d || j(!1), w === void 0 && ce(e || []);
   }, ae = () => {
     if (S || z)
       return /* @__PURE__ */ r.jsx(
@@ -98,7 +98,7 @@ const er = (C) => {
       disabled: i,
       selectMode: d ? "check" : "radio",
       value: J(),
-      defaultValue: N,
+      defaultValue: y,
       onChange: P,
       ...L
     });
@@ -131,7 +131,7 @@ const er = (C) => {
               className: T ? "check-select-content-item" : "check-select-content-item check-select-content-item-noclose",
               children: [
                 /* @__PURE__ */ r.jsx("span", { children: /* @__PURE__ */ r.jsx(V, { placement: "top-start", children: we || be }) }),
-                T && /* @__PURE__ */ r.jsx(Y, { onClick: (Ne) => B?.(p, m, Ne) })
+                T && /* @__PURE__ */ r.jsx(Y, { onClick: (ye) => B?.(p, m, ye) })
               ]
             },
             m
@@ -186,7 +186,7 @@ const er = (C) => {
     }) })
   ] }), ge = () => {
     let e = `${c}-selector-more-popover ${c}-scrollbar-small`;
-    return g && (e += ` ${c}-selector-more-popover-${g}`), A && (e += ` ${A}`), e;
+    return g && (e += ` ${c}-selector-more-popover-${g}`), F && (e += ` ${F}`), e;
   }, I = () => /* @__PURE__ */ r.jsx(
     Me,
     {
@@ -238,7 +238,7 @@ const er = (C) => {
         ae(),
         je(),
         /* @__PURE__ */ r.jsx(
-          ye,
+          Ne,
           {
             error: D,
             helperText: re,

package/es/SingleBox/component.json

@@ -0,0 +1,151 @@
+{
+    "name": "SingleBox",
+    "category": "Data Entry",
+    "description": "逐行多值列表输入框(每行一个值,整体以 string[] 数组收集 · 支持自动补全)",
+    "semantic": {
+        "intent": [
+            "多值列表输入(逐行)",
+            "标签集合录入",
+            "自动补全"
+        ],
+        "useCases": [
+            "多关键词输入(每行一个)",
+            "标签批量录入",
+            "多值配置项"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "array",
+            "itemType": "string",
+            "description": "受控值 string[],与 defaultValue 互斥(必须配合 onChange 同步)。**业务 string 单值桥接**(协议 SB1):`value={s ? [s] : []}`;**value=[] 行为**(协议 SB2):自动渲染一个空 input 行"
+        },
+        "defaultValue": {
+            "type": "array",
+            "itemType": "string",
+            "description": "非受控默认值,与 value 互斥,仅首次 mount 生效"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(val: string[]) => void",
+            "description": "值变更回调,val 是当前所有行的完整数组快照。**业务 string 单值桥接**(协议 SB1):`(val) => setKeyword(val[0] ?? '')`;**val 永远至少 [''])**(协议 SB3);**disabled+受控**仍需传 onChange(空函数避免 warning)"
+        },
+        "fetchSuggestions": {
+            "type": "function",
+            "signature": "(val: string, cb: (data: any[]) => void) => void",
+            "description": "自动补全数据源,存在时每行 input 启用联想。cb 数据可为 string[](直接显示)或 {label, value}[](按 label 显示)"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用整组输入,可配合 disabledTooltip 解释原因"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "必填(透传到 Label 显示星号)"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "placeholder": {
+            "type": "ReactNode",
+            "description": "每行 input 占位"
+        },
+        "helperText": {
+            "type": "ReactNode | ReactNode[]",
+            "description": "错误文本,单值=所有行共享;数组=按行下标对应,空串项表示该行无错"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用态下添加按钮的 tooltip 配置(仅 disabled=true 时生效)"
+        },
+        "otherProps": {
+            "type": "(index: number, val: string) => TextFieldProps",
+            "description": "每行 TextField 的额外 props;index 是行下标(0-based),返回对象展开到该行 TextField"
+        }
+    },
+    "crossPropInteractions": [
+        "value=[] / [''] = 渲染一个空 input 行(自动归一化)",
+        "业务 string ↔ SingleBox string[] 桥接 = 入站 [s] + 出站 val[0] ?? ''(协议 SB1)",
+        "disabled=true = 隐藏添加/删除按钮 + 所有 input 只读;受控仍需传 onChange",
+        "helperText[] 按行下标对应 + value[] 行数 = 错误信息可逐行显示",
+        "fetchSuggestions + otherProps = 联想 + 按行定制(如某行 maxLength)"
+    ],
+    "commonMisconceptions": [
+        "❌ SingleBox 是单值输入框 — 实际 value 是 string[](多行)",
+        "❌ value=[] 不显示输入框 — 自动渲染一个空 input 行",
+        "❌ 删除所有行后 onChange 给 [] — 实际最少 [''](组件保留一行)",
+        "❌ disabled+受控可省略 onChange — 仍需传(空函数)避免 React warning",
+        "❌ 业务 string 直接传 value — 必须 [s] 包装,onChange 取 val[0]"
+    ],
+    "do": [
+        "支持自动完成",
+        "提供建议列表",
+        "业务单值场景用 [s] 包装 value + (val) => val[0] ?? '' 出站桥接"
+    ],
+    "dont": [
+        "建议列表过长",
+        "忽略去重",
+        "把 SingleBox 当单值 TextField 用(它是多值列表,建议用 TextField)"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "val 是所有行当前值的完整数组快照，如 ['keyword1', 'keyword2', '']",
+                "业务单值桥接：onChange={(val) => setSingleKeyword(val[0] ?? '')}",
+                "删除最后一行后 val 仍是 ['']（保留至少一行空 input）"
+            ],
+            "commonMistakes": [
+                "期望删除所有行后 onChange 返回 [] ——组件保留最少一行，val 永远是 [''] 或更多",
+                "disabled+受控时省略 onChange——仍需传（可传空函数）否则 React 报 prop 变化 warning",
+                "业务 string 直接传 value——必须 [s] 包装，onChange 取 val[0] ?? ''"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "value 类型是 string[]，传单个 string 报 TS 类型不兼容",
+            "wrong": "value={keyword}  // keyword: string，TS 报不兼容 string[]",
+            "right": "value={keyword ? [keyword] : ['']}  // 桥接：string → string[]"
+        },
+        {
+            "issue": "helperText 传数组时数组下标必须与 value 数组行数对齐",
+            "wrong": "value={['a','b']} helperText={['err0']}  // 仅第 0 行报错，第 1 行错误无文案但不会静默",
+            "right": "value={['a','b']} helperText={['err0', 'err1']}  // 按行下标一一对应"
+        },
+        {
+            "issue": "otherProps 函数需要返回完整 TextFieldProps 对象，类型不对会扩散到每行 TextField",
+            "wrong": "otherProps={(i) => i === 0 ? { maxLength: 10 } : null}  // null 不满足 TextFieldProps",
+            "right": "otherProps={(i) => i === 0 ? { maxLength: 10 } : {}}  // 非目标行返回空对象"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SingleBox",
+        "adapter": null
+    }
+}

package/es/SingleBox/index.d.ts

@@ -37,10 +37,10 @@ export interface SingleBoxProps extends HelperTextDetailProps {
     /** 改变值 */
     onChange?: (val: string[]) => void;
     /** 匹配 */
-    fetchSuggestions?: (val: string, cb: (data: any[]) => void) => void;
+    fetchSuggestions?: (val: string, cb: (data: Record<string, unknown>[]) => void) => void;
     /** 输入框其他参数 */
     otherProps?: (index: number, val: string) => TextFieldProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const SingleBox: FunctionComponent<SingleBoxProps>;
 export default SingleBox;

package/es/Slider/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Slider",
+    "category": "Data Entry",
+    "description": "滑动输入条，用于在给定范围内选择一个值或范围",
+    "semantic": {
+        "intent": [
+            "数值调节",
+            "范围选择",
+            "模糊输入"
+        ],
+        "useCases": [
+            "音量调节",
+            "价格筛选",
+            "亮度调整"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "单滑块"
+        },
+        "range": {
+            "meaning": "双滑块范围选择"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "number | number[]",
+            "description": "当前取值；range 模式下传 [min, max] 数组"
+        },
+        "defaultValue": {
+            "type": "number | number[]",
+            "description": "默认取值"
+        },
+        "min": {
+            "type": "number",
+            "default": 0,
+            "description": "最小值"
+        },
+        "max": {
+            "type": "number",
+            "default": 100,
+            "description": "最大值"
+        },
+        "step": {
+            "type": "number",
+            "default": 1,
+            "description": "步长"
+        },
+        "range": {
+            "type": "boolean | { draggableTrack?: boolean }",
+            "description": "双滑块模式（核心 prop）；传 true 时 value 变为 [min, max] 数组；传 { draggableTrack: true } 时允许拖拽整段轨道",
+            "default": false,
+            "required": false
+        },
+        "vertical": {
+            "type": "boolean",
+            "description": "垂直方向",
+            "default": false,
+            "required": false
+        },
+        "dots": {
+            "type": "boolean",
+            "description": "是否只能拖拽到刻度上（配合 marks 使用）",
+            "default": false,
+            "required": false
+        },
+        "tipFormatter": {
+            "type": "function",
+            "signature": "(value: number) => ReactNode | null",
+            "description": "格式化 Tooltip 显示；传 null 隐藏 Tooltip",
+            "required": false
+        },
+        "onAfterChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "mouseup 时触发；与 onChange 区别：onChange 是拖拽过程中实时触发，onAfterChange 仅在释放后触发一次",
+            "required": false
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "值改变回调（拖拽过程实时触发）；range 模式下 value 是 [min, max] 数组"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "marks": {
+            "type": "object",
+            "objectShape": {
+                "[number]": { "type": "string | ReactNode", "description": "刻度值 → 显示标签，例：{ 0: '0°C', 26: '26°C', 100: '100°C' }" }
+            },
+            "completeExample": "{ 0: '0°C', 26: '26°C', 37: '37°C', 100: { style: { color: '#f50' }, label: <strong>100°C</strong> } }",
+            "description": "刻度标记"
+        },
+        "tooltipVisible": {
+            "type": "boolean",
+            "description": "Tooltip 是否可见"
+        },
+        "tooltipPlacement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight"
+            ],
+            "default": "top",
+            "description": "Tooltip 位置"
+        }
+    },
+    "do": [
+        "在需要快速调节数值且对精度要求不高时使用",
+        "使用 marks 辅助用户定位常用值（配合 dots=true 让用户只能拖到刻度位置）",
+        "受控用法：value + onChange 实现受控；range 模式 value 必须是 number[] 数组（[min, max]）",
+        "高精度场景搭配 InputNumber：onChange 实时同步到 InputNumber，onAfterChange 仅在释放后更新"
+    ],
+    "dont": [
+        "在需要极高精度输入的场景单纯依赖 Slider（应配合 InputNumber）",
+        "范围极小（如 0-1）时使用 Slider——步长精度和 UI 交互体验差",
+        "range 模式 value 传单 number 而非 number[]——会导致 rc-slider 报 PropTypes warning 并功能异常"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单滑块：onChange={(val) => setVolume(val as number)}",
+                "范围滑块（range=true）：onChange={(val) => setRange(val as number[])}",
+                "拖拽过程中实时触发，高频触发时应注意性能（可用 onAfterChange 替代）"
+            ],
+            "commonMistakes": [
+                "range 模式期望 value 是单 number——range=true 时 value 始终是 number[2]",
+                "混淆 onChange 和 onAfterChange——onChange 拖拽过程高频触发，onAfterChange 仅 mouseup 时触发一次",
+                "tipFormatter 传 null 后期望 onChange 仍提供 tooltip 展示——null 表示完全隐藏 tooltip"
+            ]
+        },
+        "onAfterChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户释放滑块时触发一次，适合触发网络请求或昂贵计算",
+                "range 模式：value 是 [min, max] 数组"
+            ],
+            "commonMistakes": [
+                "期望 onAfterChange 在拖拽过程中实时触发——只有 mouseup 时才触发，拖拽中用 onChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "range 模式 value/onChange 类型是 number[]，非 range 模式是 number，混用报 TS 错",
+            "wrong": "range value={50} onChange={(v) => setVal(v)}  // range=true 时 v 是 number[]，赋给 number 报错",
+            "right": "range value={[20, 80]} onChange={(v) => setRange(v as number[])}  // range=true 显式 as number[]"
+        },
+        {
+            "issue": "SliderSingleProps 和 SliderRangeProps 是 union 类型，直接展开 props 时 TS 可能报不兼容",
+            "wrong": "const sliderProps: SliderSingleProps = { range: true, value: [0,50] }  // range=true 应用 SliderRangeProps",
+            "right": "const sliderProps: SliderRangeProps = { range: true, value: [0, 50], onChange: (v) => setRange(v) }"
+        },
+        {
+            "issue": "tipFormatter 传 null 和不传的行为不同",
+            "wrong": "tipFormatter={null}  // 期望默认格式化显示——null 表示完全隐藏 tooltip",
+            "right": "tipFormatter={undefined}  // 不传或 undefined 使用内置 toString 格式化；null 隐藏 tooltip"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Slider",
+        "adapter": null
+    }
+}