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

package/es/Carousel/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "Carousel",
+    "category": "Data Display",
+    "description": "走马灯，用于一组图片或卡片的轮播",
+    "semantic": {
+        "intent": [
+            "轮播展示",
+            "吸引注意",
+            "节省空间"
+        ],
+        "useCases": [
+            "首页 Banner",
+            "产品展示",
+            "图片画廊"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认轮播"
+        }
+    },
+    "states": [
+        "active"
+    ],
+    "idealProps": {
+        "autoplay": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否自动切换"
+        },
+        "autoplaySpeed": {
+            "type": "number",
+            "default": 3000,
+            "description": "自动播放间隔（ms），需配合 autoplay=true 使用",
+            "required": false
+        },
+        "infinite": {
+            "type": "boolean",
+            "default": true,
+            "description": "无限循环；设为 false 时到最后一张停止",
+            "required": false
+        },
+        "slidesToShow": {
+            "type": "number",
+            "default": 1,
+            "description": "一帧显示幻灯片数",
+            "required": false
+        },
+        "slidesToScroll": {
+            "type": "number",
+            "default": 1,
+            "description": "一次滚动幻灯片数",
+            "required": false
+        },
+        "arrows": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示前后箭头",
+            "required": false
+        },
+        "dotPosition": {
+            "type": "enum",
+            "values": ["top", "bottom", "left", "right"],
+            "default": "bottom",
+            "description": "指示点位置",
+            "required": false
+        },
+        "pauseOnHover": {
+            "type": "boolean",
+            "default": true,
+            "description": "悬停时暂停自动播放",
+            "required": false
+        },
+        "dots": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示指示点"
+        },
+        "effect": {
+            "type": "enum",
+            "values": [
+                "scrollx",
+                "fade"
+            ],
+            "default": "scrollx",
+            "description": "动画效果"
+        },
+        "afterChange": {
+            "type": "function",
+            "signature": "(current: number) => void",
+            "description": "切换面板的回调"
+        }
+    },
+    "do": [
+        "使用高质量的图片",
+        "限制 Carousel 的数量（<5）以保证性能",
+        "需要命令式控制（goTo/next/prev）时通过 forwardRef + useRef<CarouselRef> 获取实例方法"
+    ],
+    "dont": [
+        "在移动端使用非触摸友好的 Carousel",
+        "自动播放速度过快 (<2s) 导致用户无法看清",
+        "不要传 prevArrow / nextArrow prop——这两个 prop 已从 CarouselProps 中移除（TypeScript 会报错）；自定义箭头外观请通过 CSS 覆盖 `.slick-prev` / `.slick-next` 样式"
+    ],
+    "events": {
+        "afterChange": {
+            "signature": "(current: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换后同步外部状态：afterChange={(index) => setActiveIndex(index)}",
+                "切换后更新指示器：afterChange={(index) => setTitle(slides[index].title)}",
+                "切换后埋点：afterChange={(index) => analytics.track('carousel_change', { slide: index })}"
+            ],
+            "commonMistakes": [
+                "期望 beforeChange 回调——CarouselProps 只有 afterChange，beforeChange 来自 react-slick Settings 但未在 CarouselProps 类型覆盖中暴露",
+                "期望 afterChange 在自动播放切换时也触发——autoplay 切换同样会触发 afterChange",
+                "current 参数是 0-based 索引，从 infinite=true 模式下 current 可能超过 children 数量（react-slick 克隆节点）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "prevArrow 和 nextArrow 已从 CarouselProps 中通过 Omit 移除——传入会有 TS 报错",
+            "wrong": "<Carousel prevArrow={<MyPrev />} nextArrow={<MyNext />} />  // TS: Omit<Settings, '...prevArrow | nextArrow'>",
+            "right": "// 通过 CSS 覆盖箭头样式\n// .paraui-v4-carousel .slick-prev { ... }\n// .paraui-v4-carousel .slick-next { ... }"
+        },
+        {
+            "issue": "CarouselRef 的命令式方法（goTo/next/prev/play/pause）需要通过 forwardRef 接收，useRef 泛型必须指定",
+            "wrong": "const ref = useRef(null);\n// ref.current.goTo(2);  // TS: null 上不存在 goTo",
+            "right": "import type { CarouselRef } from '@para-ui/core/Carousel';\nconst ref = useRef<CarouselRef>(null);\n// ref.current?.goTo(2);"
+        },
+        {
+            "issue": "effect prop 值只有 'scrollx' | 'fade'——不是 react-slick 原生的 fade boolean，内部做了映射",
+            "wrong": "<Carousel fade={true} />  // fade 是 react-slick 原生字段，CarouselProps 用 effect 替代",
+            "right": "<Carousel effect='fade' />  // src 内部将 effect='fade' 映射为 newProps.fade=true"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Carousel",
+        "adapter": null
+    }
+}

package/es/Carousel/index.d.ts

@@ -2,7 +2,7 @@ import { default as React } from 'react';
 import { Settings } from 'react-slick';
 export type CarouselEffect = 'scrollx' | 'fade';
 export type DotPosition = 'top' | 'bottom' | 'left' | 'right';
-export interface CarouselProps extends Omit<Settings, 'dots' | 'dotsClass'> {
+export interface CarouselProps extends Omit<Settings, 'dots' | 'dotsClass' | 'prevArrow' | 'nextArrow'> {
     /** 动画效果函数 */
     effect?: CarouselEffect;
     /** style */

package/es/Cascader/component.json

@@ -0,0 +1,196 @@
+{
+    "name": "Cascader",
+    "category": "Data Entry",
+    "description": "级联选择，用于多层级数据的选择",
+    "semantic": {
+        "intent": [
+            "层级选择",
+            "地域选择",
+            "分类选择"
+        ],
+        "useCases": [
+            "省市区选择",
+            "商品分类",
+            "组织架构"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准级联"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "loading"
+    ],
+    "idealProps": {
+        "options": {
+            "type": "array",
+            "itemSchema": {
+                "label": { "type": "ReactNode", "required": true, "description": "选项显示文案" },
+                "value": { "type": "string | number | null", "description": "选项值" },
+                "children": { "type": "DefaultOptionType[]", "description": "子级选项，形成层级结构" },
+                "disabled": { "type": "boolean", "description": "是否禁用该选项" },
+                "disableCheckbox": { "type": "boolean", "description": "禁用 checkbox（checkable 模式）" },
+                "disableTitle": { "type": "string", "description": "禁用时 tooltip 提示文案" }
+            },
+            "description": "数据源，元素类型为 `DefaultOptionType`（包含 `label / value / children / disabled / disableTitle`；⚠️ `loading` 和 `isLeaf` **不在 DefaultOptionType 中**，是 loadData 场景扩展字段，需在业务类型中另声明）。业务自有节点类型对接三种推荐写法：(1) 泛型 `<Cascader<RegionNode> options={tree} />`（首选，Cascader 已暴露 `<OptionType extends BaseOptionType = DefaultOptionType>` 泛型）；(2) 声明合并 `interface RegionNode extends DefaultOptionType { ... }`；(3) as 强转 `options={tree as DefaultOptionType[]}`（快速逃逸）。详见 docs/view/cascader/codeString.ts customOptionTypeCascader 示例。"
+        },
+        "value": {
+            "type": "(string | number)[]",
+            "description": "受控选中值；级联路径数组，每层一个值，如 `['guangdong', 'guangzhou']`。⚠️ 类型是 (string | number)[]，不是 string[] 或 any[]，传纯 string 路径需在调用侧 as string[]"
+        },
+        "defaultValue": {
+            "type": "(string | number)[]",
+            "description": "非受控初始选中值；格式同 value，如 `['guangdong', 'guangzhou']`。不要同时传 value + defaultValue"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(value: (string | number)[], selectedOptions: DefaultOptionType[]) => void",
+            "description": "选中值改变回调。**完整签名**：第一参 value 是选中路径各级节点 value 组成的数组（如 ['guangdong', 'guangzhou']）；第二参 selectedOptions 是路径各级节点完整对象数组。⚠️ **TS7006 陷阱（noImplicitAny）**：内联回调参数必须显式标注类型——`onChange={(value: (string | number)[]) => ...}` ✅；`onChange={(value) => ...}` ❌ 报 TS7006。**桥接 string[] 场景推荐写法**：`onChange={(value: (string | number)[]) => onPathChange(value as string[])}`"
+        },
+        "onDropdownVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "弹出层显示状态改变时的回调，visible=true 表示打开，false 表示关闭"
+        },
+        "changeOnSelect": {
+            "type": "boolean",
+            "default": false,
+            "description": "选择任一级即触发 onChange,无需选到末级"
+        },
+        "expandTrigger": {
+            "type": "enum",
+            "values": [
+                "click",
+                "hover"
+            ],
+            "default": "click",
+            "description": "展开触发方式"
+        },
+        "expandIcon": {
+            "type": "ReactNode",
+            "description": "展开箭头图标"
+        },
+        "loadingIcon": {
+            "type": "ReactNode",
+            "description": "异步加载状态图标"
+        },
+        "expandJoin": {
+            "type": "string",
+            "default": "/",
+            "description": "已选路径文本拼接符"
+        },
+        "fieldNames": {
+            "type": "object",
+            "default": "{ label: 'label', value: 'value', children: 'children' }",
+            "objectShape": {
+                "label": { "type": "string", "description": "数据中作为显示文案的字段名，默认 'label'" },
+                "value": { "type": "string", "description": "数据中作为值的字段名，默认 'value'" },
+                "children": { "type": "string", "description": "数据中作为子级的字段名，默认 'children'" }
+            },
+            "description": "自定义节点字段名映射"
+        },
+        "placeholder": {
+            "type": "string",
+            "default": "请选择",
+            "description": "占位符"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否整体禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "disabled 时悬浮于触发框的 Tooltip 配置"
+        },
+        "optionsTitle": {
+            "type": "Array<string | null>",
+            "default": "[]",
+            "description": "每级面板顶部标题文案,下标对应级数"
+        },
+        "checkable": {
+            "type": "boolean | ReactNode",
+            "default": false,
+            "description": "是否多选;true 显示 checkbox,传 ReactNode 自定义勾选图标"
+        },
+        "displayRender": {
+            "type": "function",
+            "signature": "(label: string[], selectedOptions?: DefaultOptionType[]) => ReactNode",
+            "description": "自定义触发框已选项渲染。label 是路径各级节点 label 的字符串数组（非单一字符串）；selectedOptions 是路径各级节点完整对象数组"
+        },
+        "loadData": {
+            "type": "function",
+            "signature": "(selectedOptions: DefaultOptionType[]) => void",
+            "description": "异步加载下一级数据。触发条件：用户展开 isLeaf=false 且无 children 的节点。selectedOptions 为当前展开路径各级节点数组。在回调内修改数据源并通过外部 setState 更新 options（标准模式：setOptions([...options])）"
+        },
+        "notFoundContent": {
+            "type": "ReactNode",
+            "description": "options 为空或搜索无匹配时的空状态"
+        }
+    },
+    "do": [
+        "用于有明确层级关系的数据选择",
+        "数据量较大会延迟加载（loadData）",
+        "onChange 内联回调必须显式标注类型参数，避免 noImplicitAny 报错：onChange={(value: (string|number)[]) => ...}"
+    ],
+    "dont": [
+        "层级过深（>5级）导致横向滚动过长",
+        "在非层级数据中使用 Cascader（应使用 Select）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: (string | number)[], selectedOptions: DefaultOptionType[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基础用法：onChange={(value) => setPath(value)}  // value 是路径各级 value 数组，如 ['guangdong', 'guangzhou']",
+                "获取完整路径对象：onChange={(value, selectedOptions) => setLabel(selectedOptions.map(o => o.label).join(' / '))}",
+                "桥接 string[] 类型：onChange={(value: (string|number)[]) => onPathChange(value as string[])}"
+            ],
+            "commonMistakes": [
+                "内联回调不标注参数类型导致 TS7006 noImplicitAny 报错——必须显式声明 value: (string|number)[]",
+                "期望 onChange 在 changeOnSelect=false 时每级展开都触发——只有选到末级（或 changeOnSelect=true 时任意级）才触发",
+                "用 value[value.length-1] 取最终叶节点值——这是最后一级的 value，但当 checkable 多选时 value 结构不同（多维数组）"
+            ]
+        },
+        "onDropdownVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "弹出层打开时加载数据：onDropdownVisibleChange={(v) => { if (v && !loaded) fetchOptions(); }}",
+                "弹出层关闭时重置搜索：onDropdownVisibleChange={(v) => { if (!v) setSearch(''); }}",
+                "受控弹层：onDropdownVisibleChange={(v) => setOpen(v)}"
+            ],
+            "commonMistakes": [
+                "期望 onOpen / onClose 独立回调——Cascader 只有 onDropdownVisibleChange，通过 visible 参数区分",
+                "在 onDropdownVisibleChange 里直接 loadData——loadData prop 是每级展开时的异步回调，不是全局弹层回调",
+                "visible=false 时立即清空 options——关闭动画期间 Cascader 仍需 options 数据，过早清空会闪烁"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 内联回调参数必须显式标注类型，否则 noImplicitAny 报 TS7006",
+            "wrong": "<Cascader onChange={(value) => setV(value)} />  // TS7006: 'value' 参数隐式具有 'any' 类型",
+            "right": "<Cascader onChange={(value: (string | number)[]) => setV(value)} />"
+        },
+        {
+            "issue": "业务自有节点类型必须 extends BaseOptionType（含索引签名），否则泛型约束失败",
+            "wrong": "interface Region { label: string; value: string; code: string; }  // 无索引签名\n<Cascader<Region> options={regions} />  // TS 报错：Region 不满足 BaseOptionType",
+            "right": "interface Region extends DefaultOptionType { code: string; }  // 继承 DefaultOptionType 或直接继承 BaseOptionType"
+        },
+        {
+            "issue": "DefaultOptionType 的 loading 和 isLeaf 字段不在类型定义中——loadData 场景需扩展类型",
+            "wrong": "const node: DefaultOptionType = { label: '北京', value: 'bj', isLeaf: false };  // TS: isLeaf 不在 DefaultOptionType",
+            "right": "interface LazyOption extends DefaultOptionType { isLeaf?: boolean; loading?: boolean; }\nconst node: LazyOption = { label: '北京', value: 'bj', isLeaf: false };"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Cascader",
+        "adapter": null
+    }
+}

package/es/Cascader/hooks/useEntities.js

@@ -1,24 +1,24 @@
 import * as o from "react";
-import { convertDataToEntities as c } from "../utils/treeUtil.js";
-import { VALUE_SPLIT as u } from "../utils/commonUtil.js";
-const l = (e, r) => {
+import { convertDataToEntities as u } from "../utils/treeUtil.js";
+import { VALUE_SPLIT as p } from "../utils/commonUtil.js";
+const h = (e, r) => {
   const n = o.useRef({
     options: null,
     info: null
   });
-  return o.useCallback(() => (n.current.options !== e && (n.current.options = e, n.current.info = c(e, {
+  return o.useCallback(() => (n.current.options !== e && (n.current.options = e, n.current.info = u(e, {
     fieldNames: r,
     initWrapper: (t) => ({
       ...t,
       pathKeyEntities: {}
     }),
     processEntity: (t, s) => {
-      const i = t.nodes.map((a) => a[r.value]).join(u);
-      s.pathKeyEntities[i] = t, t.key = i;
+      const c = s, i = t.nodes.map((a) => a[r.value]).join(p);
+      c.pathKeyEntities[i] = t, t.key = i;
     }
   })), n.current.info.pathKeyEntities), [r, e]);
 };
 export {
-  l as default
+  h as default
 };
 //# sourceMappingURL=useEntities.js.map

package/es/Cascader/interface.d.ts

@@ -0,0 +1 @@
+export type { DefaultOptionType, BaseOptionType } from './Cascader';

package/es/Cascader/utils/commonUtil.d.ts

@@ -15,4 +15,4 @@ export declare function toPathValueStr(pathKey: string): string[];
 export declare function fillFieldNames(fieldNames?: FieldNames): InternalFieldNames;
 export declare function isLeaf(option: DefaultOptionType, fieldNames: FieldNames): boolean;
 export declare function scrollIntoParentView(element: HTMLElement): void;
-export declare function getFullPathKeys(options: DefaultOptionType[], fieldNames: FieldNames): any[][];
+export declare function getFullPathKeys(options: DefaultOptionType[], fieldNames: FieldNames): (SingleValueType | undefined)[];

package/es/Cascader/utils/commonUtil.js

@@ -1,20 +1,20 @@
-const r = "__RC_CASCADER_SPLIT__", a = "SHOW_PARENT", f = "SHOW_CHILD", c = "__rc_cascader_search_mark__";
-function s(t) {
-  return t.join(r);
+const l = "__RC_CASCADER_SPLIT__", s = "SHOW_PARENT", f = "SHOW_CHILD", a = "__rc_cascader_search_mark__";
+function c(t) {
+  return t.join(l);
 }
 function i(t) {
-  return t.map(s);
+  return t.map(c);
 }
 function u(t) {
-  return t.split(r);
+  return t.split(l);
 }
 function _(t) {
-  const { label: e, value: o, children: n } = t || {}, l = o || "value";
+  const { label: e, value: n, children: r } = t || {}, o = n || "value";
   return {
     label: e || "label",
-    value: l,
-    key: l,
-    children: n || "children"
+    value: o,
+    key: o,
+    children: r || "children"
   };
 }
 function h(t, e) {
@@ -24,22 +24,22 @@ function p(t) {
   const e = t.parentElement;
   if (!e)
     return;
-  const o = t.offsetTop - e.offsetTop;
-  o - e.scrollTop < 0 ? e.scrollTo({ top: o }) : o + t.offsetHeight - e.scrollTop > e.offsetHeight && e.scrollTo({ top: o + t.offsetHeight - e.offsetHeight });
+  const n = t.offsetTop - e.offsetTop;
+  n - e.scrollTop < 0 ? e.scrollTo({ top: n }) : n + t.offsetHeight - e.scrollTop > e.offsetHeight && e.scrollTo({ top: n + t.offsetHeight - e.offsetHeight });
 }
 function H(t, e) {
-  return t.map((o) => o[c]?.map((n) => n[e.value]));
+  return t.map((n) => n[a]?.map((o) => o[e.value]));
 }
 export {
-  c as SEARCH_MARK,
+  a as SEARCH_MARK,
   f as SHOW_CHILD,
-  a as SHOW_PARENT,
-  r as VALUE_SPLIT,
+  s as SHOW_PARENT,
+  l as VALUE_SPLIT,
   _ as fillFieldNames,
   H as getFullPathKeys,
   h as isLeaf,
   p as scrollIntoParentView,
-  s as toPathKey,
+  c as toPathKey,
   i as toPathKeys,
   u as toPathValueStr
 };

package/es/Cascader/utils/treeUtil.d.ts

@@ -2,8 +2,17 @@ import { SingleValueType, DefaultOptionType, InternalFieldNames, ShowCheckedStra
 import { GetEntities } from '../hooks/useEntities';
 declare type Key = string | number;
 export declare type GetKey<RecordType> = (record: RecordType, index?: number) => Key;
-type DataEntity = any;
-type DataNode = any;
+type DataNode = DefaultOptionType;
+interface DataEntity {
+    node: DataNode;
+    nodes: DataNode[];
+    index?: number;
+    pos: string;
+    key: Key;
+    level: number;
+    parent?: DataEntity;
+    children?: DataEntity[];
+}
 interface TraverseDataNodesConfig {
     childrenPropName?: string;
     externalGetKey?: ExternalGetKey;
@@ -28,7 +37,7 @@ export declare function toPathOptions(valueCells: SingleValueType, options: Defa
     option: DefaultOptionType;
 }[];
 export declare function convertDataToEntities(dataNodes: DataNode[], { initWrapper, processEntity, onProcessFinished, externalGetKey, childrenPropName, fieldNames }?: {
-    initWrapper?: (wrapper: any) => Wrapper;
+    initWrapper?: (wrapper: Wrapper) => Wrapper;
     processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
     onProcessFinished?: (wrapper: Wrapper) => void;
     externalGetKey?: ExternalGetKey;
@@ -37,8 +46,8 @@ export declare function convertDataToEntities(dataNodes: DataNode[], { initWrapp
 }, 
 /** @deprecated Use `config.externalGetKey` instead */
 legacyExternalGetKey?: ExternalGetKey): {
-    posEntities: any;
-    keyEntities: any;
+    posEntities: Record<string, DataEntity>;
+    keyEntities: Record<Key, DataEntity>;
 };
 export declare function traverseDataNodes(dataNodes: DataNode[], callback: (data: {
     node: DataNode;

package/es/Cascader/utils/treeUtil.js

@@ -52,7 +52,7 @@ function E(i, s, l) {
   let y;
   n ? typeof n == "string" ? y = (e) => e[n] : typeof n == "function" && (y = (e) => n(e)) : y = (e, h) => K(e[u], h);
   function a(e, h, p, m) {
-    const v = e ? e[c] : i, g = e ? G(p.pos, h) : "0", x = e ? [...m, e] : [];
+    const v = e ? e[c] : i, g = e ? G(p.pos, h) : "0", x = e ? [...m ?? [], e] : [];
     if (e) {
       const k = y(e, g), r = {
         node: e,

package/es/Checkbox/component.json

@@ -0,0 +1,138 @@
+{
+    "name": "Checkbox",
+    "category": "Data Entry",
+    "description": "多选框，用于在多个选项中选择一个或多个",
+    "semantic": {
+        "intent": [
+            "多项选择",
+            "状态切换",
+            "同意协议"
+        ],
+        "useCases": [
+            "过滤器",
+            "权限配置",
+            "表单录入"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "独立多选框"
+        },
+        "group": {
+            "meaning": "多选框组"
+        }
+    },
+    "states": [
+        "checked",
+        "unchecked",
+        "indeterminate",
+        "disabled"
+    ],
+    "idealProps": {
+        "checked": {
+            "type": "boolean",
+            "description": "是否选中"
+        },
+        "defaultChecked": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否选中"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "description": "变化时回调（src/Checkbox/index.tsx:40 interface 实证：签名为 MouseEvent on HTMLLabelElement；indeterminate=true 时 checked 参数永远为 true；正常场景 checked 为切换后的新状态）"
+        },
+        "indeterminate": {
+            "type": "boolean",
+            "default": false,
+            "description": "不确定状态（src/Checkbox/index.tsx:36,51,90 实证：仅控制样式——追加 paraui-v4-checkbox-indeterminate 类，并使 onChange 固定传 checked=true；不影响内部 checked state 的实际计算）"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "显示的文本（src/Checkbox/index.tsx:20 实证：类型为 ReactNode，支持字符串/ReactNode；label 为 null/''/undefined 时不渲染 Label 组件，src:137-139 实证）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "多选框大小（src/Checkbox/index.tsx:24,48,88 实证：默认 'large'，控制 CSS 类 paraui-v4-checkbox-{size}）"
+        },
+        "width": {
+            "type": "string",
+            "description": "组件外层容器宽度（src/Checkbox/index.tsx:18,52,117 实证：写入根 label 的 style.width，与 style prop 合并）"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "label 旁的帮助图标 tooltip 配置（src/Checkbox/index.tsx:22,47,92-93 实证：tooltipType 字段会追加到根容器类名；className/helpClassName 字段控制额外样式；透传给内部 Label 组件）"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用状态下的 Tooltip 配置（src/Checkbox/index.tsx:34-35,150-156 实证：存在 disabledTooltip 时将整个 Checkbox 包裹在 Tooltip 内，disabled 固定为 true，透传全部 TooltipProps）"
+        },
+        "inputProps": {
+            "type": "React.InputHTMLAttributes<HTMLInputElement>",
+            "description": "内层原生 checkbox input 的额外 props（src/Checkbox/index.tsx:38,133 实证：透传到 `<input type='checkbox' {...props.inputProps} />`）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Checkbox/index.tsx:14,45 实证，追加到根 label 元素）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Checkbox/index.tsx:16,54,116 实证，与 width prop 合并后透传到根 label 元素）"
+        }
+    },
+    "do": [
+        "使用 Checkbox Group 处理一组相关的选项",
+        "明确 Label 的含义",
+        "受控用 checked + onChange，非受控用 defaultChecked；二者不要混用"
+    ],
+    "dont": [
+        "在单选场景中使用 Checkbox（应使用 Radio）",
+        "Checkbox 选项过多导致布局混乱"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基础受控：onChange={(e, checked) => setChecked(checked)}",
+                "indeterminate 模式下 checked 永远为 true：onChange={(e, checked) => { if (indeterminate) setIndeterminate(false); setChecked(checked); }}",
+                "非受控+监听：onChange={(e, checked) => analytics.track('checkbox', { checked })}"
+            ],
+            "commonMistakes": [
+                "期望 onChange 签名是 (e: React.ChangeEvent<HTMLInputElement>) => void（antd 风格）——Checkbox 实际签名第一参是 MouseEvent on HTMLLabelElement，不是 ChangeEvent",
+                "期望通过 e.target.checked 获取新状态——e.target 是 label 元素，checked 字段是第二参，不要从 e.target 取",
+                "indeterminate=true 时期望 checked 随用户操作在 true/false 切换——indeterminate 模式下 src 固定传 checked=true，需业务方在 onChange 里手动管理状态"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 第一参是 MouseEvent on HTMLLabelElement，不是 ChangeEvent on HTMLInputElement",
+            "wrong": "// antd 风格，期望 ChangeEvent\nonChange={(e: React.ChangeEvent<HTMLInputElement>) => setChecked(e.target.checked)}  // 类型不匹配",
+            "right": "// para-ui Checkbox onChange 签名\nonChange={(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => setChecked(checked)}"
+        },
+        {
+            "issue": "defaultChecked 只在 mount 时读取一次（useEffect 依赖 []），后续引用变化不重新初始化",
+            "wrong": "// 期望 defaultChecked 动态更新\n<Checkbox defaultChecked={serverValue} />  // serverValue 异步返回后不会重新初始化",
+            "right": "// 需要动态初始化用受控 checked + 外部 state\n<Checkbox checked={checked} onChange={(e, v) => setChecked(v)} />"
+        },
+        {
+            "issue": "disabledTooltip 类型是 TooltipProps（整个 Tooltip 的 props 对象），不是简单字符串",
+            "wrong": "<Checkbox disabled disabledTooltip='权限不足' />  // 字符串不符合 TooltipProps",
+            "right": "<Checkbox disabled disabledTooltip={{ title: '权限不足', placement: 'top' }} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Checkbox",
+        "adapter": null
+    }
+}