npm - @para-ui/core - Versions diffs - 5.0.0-beta.9 → 5.0.1 - Mend

@para-ui/core 5.0.0-beta.9 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3026) hide show

package/Tabs/component.json ADDED Viewed

@@ -0,0 +1,227 @@
+{
+    "name": "Tabs",
+    "category": "Navigation",
+    "description": "选项卡切换组件。**所有 mode 都渲染 data[].content**（src/Tabs/index.tsx:220 把 content 渲染到 TabPane 内部）——不存在『line/track 只渲染 tab 头』的差异，请放心把面板体放进 data[].content。",
+    "semantic": {
+        "intent": [
+            "内容切换",
+            "视图分组",
+            "平级导航"
+        ],
+        "useCases": [
+            "详情页多维度展示",
+            "配置面板",
+            "同级功能切换"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "line": {
+            "meaning": "线条型 (默认) — 底部下划线指示当前激活"
+        },
+        "card": {
+            "meaning": "卡片型 — tab 头本身像独立卡片"
+        },
+        "editable-card": {
+            "meaning": "可编辑卡片型 — 自带新增 + 关闭按钮，与 editable=true 配套"
+        },
+        "track": {
+            "meaning": "轨道滑块型 — segmented control 风格"
+        },
+        "card-container": {
+            "meaning": "页签容器 — 整个面板被卡片包裹"
+        }
+    },
+    "states": [
+        "active",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "TabProps<K>[]",
+            "itemSchema": {
+                "label": { "type": "ReactNode", "required": true, "description": "tab 头文案" },
+                "content": { "type": "ReactNode", "description": "面板内容，所有 mode 都渲染" },
+                "value": { "type": "K extends React.Key", "required": true, "description": "唯一标识，与 Tabs value/onChange 对应" },
+                "disabled": { "type": "boolean", "description": "是否禁用该 tab" },
+                "closable": { "type": "boolean", "description": "是否显示关闭按钮（editable 模式）" },
+                "disabledTooltip": { "type": "TooltipProps", "description": "hover 禁用 tab 时显示的 tooltip 配置" },
+                "showHelp": { "type": "boolean", "description": "是否显示帮助图标" },
+                "helpProps": { "type": "HelpProps", "description": "帮助图标配置" }
+            },
+            "description": "标签页配置数组。**每项 TabProps 完整字段**：label（tab 头文案）/ content（**面板内容，所有 mode 都渲染**）/ value（唯一 key，类型 K）/ disabled / closable / disabledTooltip（TooltipProps，hover 禁用 tab 时显示）/ showHelp / helpProps。content 不要外部用 `{activeKey === 'x' && <Body />}` 二次条件渲染——直接放在 data[].content 里"
+        },
+        "value": {
+            "type": "K extends React.Key",
+            "description": "当前激活的 tab value（受控）。Tabs 是泛型组件 `Tabs<K>`：默认 K = string，需传 string value 时业务端可写 `<Tabs<string>>`；data[].value 与 value 同类型"
+        },
+        "mode": {
+            "type": "enum",
+            "values": [
+                "line",
+                "card",
+                "editable-card",
+                "track",
+                "card-container"
+            ],
+            "default": "line",
+            "description": "外观模式 5 种取值（src/Tabs/index.tsx:19 TabsType）；`type` prop 是 mode 的别名（src 优先 type ?? mode），二选一传"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "line",
+                "card",
+                "editable-card",
+                "track",
+                "card-container"
+            ],
+            "description": "mode 的别名；与 mode 二选一即可"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "description": "尺寸"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(activeKey: K, item?: TabProps<K>) => void",
+            "description": "切换面板的回调。**真实 2 参（activeKey + item）**——首参名 activeKey 不是 value；不带 event 第三参（区别于 antd）。K 默认 string；通过 Tabs<K> 收紧"
+        },
+        "onEdit": {
+            "type": "function",
+            "signature": "(item: TabProps<K>, event?: React.MouseEvent | React.KeyboardEvent | string | React.Key, action?: 'add' | 'remove') => void",
+            "description": "新增/删除面板的回调（3 参：item / event / action）。配合 editable / showAdd / closable"
+        },
+        "onAdd": {
+            "type": "function",
+            "signature": "(event?: React.MouseEvent) => void",
+            "description": "新增按钮回调；showAdd 为 true 或 editable 模式下生效"
+        },
+        "centered": {
+            "type": "boolean",
+            "default": false,
+            "description": "标签居中展示"
+        },
+        "tabPosition": {
+            "type": "'top' | 'right' | 'bottom' | 'left'",
+            "values": ["top", "right", "bottom", "left"],
+            "default": "'top'",
+            "description": "页签位置"
+        },
+        "editable": {
+            "type": "boolean",
+            "default": false,
+            "description": "可编辑标签（关闭 + 新增）；通常与 mode='editable-card' 搭配"
+        },
+        "showAdd": {
+            "type": "boolean",
+            "default": false,
+            "description": "显示新增按钮"
+        },
+        "hideAdd": {
+            "type": "boolean",
+            "default": false,
+            "description": "在 editable 模式下隐藏新增按钮"
+        },
+        "addIcon": {
+            "type": "ReactNode",
+            "description": "自定义新增按钮图标（替换默认 + 图标）；showAdd 或 editable 时生效"
+        },
+        "radio": {
+            "type": "boolean",
+            "default": false,
+            "description": "在每个 tab 头前加 radio 单选框（与 onRadioChange 配套）"
+        },
+        "showPopConfirm": {
+            "type": "boolean",
+            "default": false,
+            "description": "切换/删除 tab 前弹出确认框（src/Tabs/index.tsx:56 实证）。⚠️ **`editable=true` 或 `mode='editable-card'` 时有效**（两者满足其一即可触发可编辑态，src:133 `inType === 'editable-card' || editable` 实证）。配合 `popConfirmProps` 自定义确认框内容"
+        },
+        "popConfirmProps": {
+            "type": "PopConfirmProps",
+            "description": "控制切换确认弹窗的内容（src/Tabs/index.tsx:58 实证，类型 PopConfirmProps）。在 `showPopConfirm=true` 时生效，可配置 title / description / okText / cancelText 等 PopConfirm 支持的所有属性"
+        },
+        "onRadioChange": {
+            "type": "function",
+            "signature": "(radioValue: K) => void",
+            "description": "radio 单选框模式下切换选中项的回调（src/Tabs/index.tsx:72 实证签名）。⚠️ **需配合 `mode='card-container'` + `radio=true`**——Radio 组件仅在 card-container 模式下渲染（src:178 实证），其他 mode 下设置 radio=true 无效。K 类型与 Tabs<K> 泛型一致（默认 string）。**与 `onChange` 区分**：onChange 是 tab 切换回调，onRadioChange 是独立的 radio 选中回调"
+        }
+    },
+    "do": [
+        "把面板内容放在 data[].content——所有 mode 都会渲染 content，不要外部条件渲染",
+        "卡片型外观请直接传 mode='card'（不要退而求其次选 mode='card-container'——后者是『整个面板卡片包裹』，不是『tab 头卡片』）",
+        "可编辑标签使用 mode='editable-card' + editable={true}；自定义新增图标用 addIcon prop",
+        "禁用 tab 的 hover 提示用 TabProps.disabledTooltip（不要给 label 包 <span title>）",
+        "受控用 value + onChange；onChange 第一参数是 activeKey，第二参数是 item，无 event 参数"
+    ],
+    "dont": [
+        "在 TabPane 中渲染过重的非首屏内容（应利用懒加载机制）",
+        "频繁切换 Tabs mode 导致布局抖动",
+        "不要假设『mode='line' 不渲染 content』——所有 mode 都渲染（src 实证）",
+        "不要按 antd 习惯传 onChange={(value, tabData, event) => ...}——本组件 2 参 (activeKey, item)",
+        "不要按 antd 习惯传 columns/items prop——本组件用 data；不要传 children TabPane——本组件用 data[].content"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(activeKey: K, item?: TabProps<K>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换 tab：onChange={(key) => setActiveTab(key)}",
+                "利用第二参取 tab 数据：onChange={(key, item) => setTitle(item?.label)}",
+                "K 泛型约束：<Tabs<'home'|'profile'> onChange={(key) => ...} />，key 类型被收紧"
+            ],
+            "commonMistakes": [
+                "按 antd 习惯传 onChange={(value, tabData, event) => ...}——本组件仅 2 参 (activeKey, item)，无 event 第三参",
+                "误以为首参名是 value——首参名是 activeKey（来自 rc-tabs 层），不是 value",
+                "忘记第二参 item 是可选的（data 为空或切换到非 data 渲染的 key 时 item 可能 undefined）"
+            ]
+        },
+        "onEdit": {
+            "signature": "(item: TabProps<K>, event?: React.MouseEvent | React.KeyboardEvent | string | React.Key, action?: 'add' | 'remove') => void",
+            "asyncSupported": false,
+            "examples": [
+                "新增：action='add', item 是空对象 {}",
+                "删除：action='remove', item 是被关闭的 TabProps<K> 项（包含 value/label 等字段）",
+                "删除实现：onEdit={(item, _, action) => action === 'remove' && setTabs(tabs.filter(t => t.value !== item.value))}"
+            ],
+            "commonMistakes": [
+                "新增分支期望 item.value 有值——add 时 item 是空对象 {}，新 key 需业务侧生成",
+                "onEdit 在 editable=false + mode!='editable-card' 时传了但不触发——需满足 editable=true 或 mode='editable-card'"
+            ]
+        },
+        "onRadioChange": {
+            "signature": "(radioValue: K) => void",
+            "asyncSupported": false,
+            "examples": [
+                "card-container 模式 + radio=true 时，每个 tab 头前有 Radio，点击 radio 触发此回调",
+                "onRadioChange={(val) => setSelected(val)}"
+            ],
+            "commonMistakes": [
+                "不是 card-container + radio=true 模式时传了 onRadioChange——Radio 不渲染，回调永不触发",
+                "与 onChange 混淆——onChange 是 tab 激活切换，onRadioChange 是独立的 radio 选中"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 首参名是 activeKey 不是 value，直接解构 value 时 TS 不报错但语义不清",
+            "wrong": "onChange={(value) => setTab(value)}  // 运行正确但命名误导",
+            "right": "onChange={(activeKey) => setTab(activeKey)}  // 参数名与签名一致"
+        },
+        {
+            "issue": "data 是 TabProps<K>[] 而不是 RcTabsProps.items，两者不可直接互用",
+            "wrong": "// 从 antd 迁移时直接传 items={tabs}——para-ui Tabs 用 data prop 不是 items",
+            "right": "data={tabs}  // TabProps 数组：[{ value: 'home', label: '首页', content: <Home /> }]"
+        },
+        {
+            "issue": "tabPosition prop 在 Omit<RcTabsProps, 'onChange'> 中保留，但 SCSS 可能不支持所有方向",
+            "wrong": "// 传 tabPosition='left' 期望左侧竖排 tab——需确认当前主题 SCSS 是否实现了 left 方向",
+            "right": "// 水平 top 位置已完整实现；非 top 方向使用前需自测 SCSS 效果"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Tabs",
+        "adapter": null
+    }
+}

package/Tag/component.json ADDED Viewed

@@ -0,0 +1,221 @@
+{
+    "name": "Tag",
+    "category": "Data Display",
+    "description": "进行标记和分类的小标签，支持 4 种预设色 + 自定义色、描边/实色、closable 可关闭、editable 内置编辑模式、visible 显隐控制",
+    "semantic": {
+        "intent": [
+            "分类",
+            "标记",
+            "选择"
+        ],
+        "useCases": [
+            "文章标签",
+            "状态展示",
+            "筛选条件"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "normal": {
+            "meaning": "普通标签"
+        },
+        "outline": {
+            "meaning": "描边标签"
+        }
+    },
+    "states": [
+        "default",
+        "closable",
+        "visible",
+        "editable"
+    ],
+    "idealProps": {
+        "children": {
+            "type": "ReactNode",
+            "description": "**标签文案**（src 通过 PropsWithChildren 接收，与 props 分开）。直接作为 children 传入：`<Tag>已激活</Tag>`。**editable 模式下**：当 children 是 string 时会作为内嵌 input 的初始值（src/Tag/index.tsx:118-122 实证）"
+        },
+        "color": {
+            "type": "'blue' | 'green' | 'yellow' | 'red' | string",
+            "description": "标签颜色。**预设色（4 个）**：blue / green / yellow / red——会命中专门 CSS 类生成完整配色方案。**非预设值**（如 'gray' / hex / rgb()）走 tinycolor 解析，渲染为带 0.1 alpha 的对应色背景 + 原色文字（无 hover/active 等专门 CSS）。**状态色推荐语义**（业界常见映射）：green=success/激活、yellow=warning/待处理、red=error/危险、blue=info/默认；灰色场景建议传 hex '#808080' 或 '#999'。需求方若需要灰色等常用色，可以提议加入预设清单（src 改 PresetColors + 加专门样式）",
+            "_presetNote": "DEFECT 反查：src/Tag/index.tsx:67 PresetColors = ['blue','green','yellow','red']；非预设走 tinycolor 通用渲染但视觉效果有差异——不是 bug 是设计取舍"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "normal",
+                "outline"
+            ],
+            "default": "normal",
+            "description": "标签类型——normal 实色填充，outline 描边版（color 仍生效，但作为边框色 + 文字色，背景透明）"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "small",
+            "description": "标签大小。三档统一为 small / medium / large(2026-05-08 跨组件命名 epic §3.1 选项 B 实施,medium 为新增视觉档,默认 small 不变,既有 small/large 调用零回归)"
+        },
+        "closable": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否可关闭——开启后右侧自动渲染 ✕ 图标；自定义关闭图标传 closeIcon prop。**半受控行为**（src/Tag/index.tsx:175-178 实证）：未传 visible prop 时点击 ✕ 自动 setVisible(false) 内部隐藏；传了 visible 后由父组件控制（点击 ✕ 仅触发 onClose 不自动隐藏）"
+        },
+        "onClose": {
+            "type": "function",
+            "signature": "(event: React.MouseEvent) => void",
+            "description": "关闭按钮点击回调（**完整签名带 React MouseEvent 参数**，src/Tag/index.tsx:36 实证）。**事件**：内部已 stopPropagation；如需阻止默认隐藏（visible 未受控场景），调用 event.preventDefault() 即可——src 检查 e.defaultPrevented 后跳过 setVisible(false)"
+        },
+        "closeIcon": {
+            "type": "ReactNode",
+            "description": "自定义关闭图标节点（替代默认 CloseIcon），仅在 closable=true 时渲染"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示标签。**受控**：传入后 Tag 显隐完全跟随 visible（onClose 后不会自动隐藏，由父组件 setState 控制）。**非受控**：不传时 onClose 后 src 内部 setVisible(false) 自动隐藏。如需完全不挂载 DOM，在父组件做条件渲染 `{isShown && <Tag />}` 而非依赖 visible prop（visible=false 时 DOM 仍渲染只是 CSS 隐藏）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "**前置图标**（src/Tag/index.tsx:231-254 实证 icon 渲染在文案左侧；与 closeIcon 在右侧不同）。editable=true 时此 prop 被忽略（前缀位置改渲染 EditIcon）"
+        },
+        "editable": {
+            "type": "boolean",
+            "default": false,
+            "description": "**Tag 内置可编辑模式**——传 editable={true} 后，Tag 在前缀位置自动渲染编辑图标（EditIcon），点击图标会切换为内嵌 input；按 Enter 或失焦提交。**回调通过 tagChange prop 触发**：`tagChange?: (value: string) => void`。**初值来源**：children 为 string 时作为 input 初始值；不是 string 时初值为空字符串。无需手写原生 input。editable 模式下 children 仅作为编辑态进入时的 initialValue；父组件后续更新 children **不会刷新已激活 input**；父组件需通过 tagChange 回调维护 state"
+        },
+        "tagChange": {
+            "type": "function",
+            "signature": "(value: string) => void",
+            "description": "**editable=true 模式下 input 值变化的回调**（src/Tag/index.tsx:259 实证：每次 onChange 触发 = 实时键入回调，**不是 onBlur/Enter 才触发**）。提交动作仅控制是否退出编辑态，与 tagChange 触发频率无关"
+        },
+        "editInputClassName": {
+            "type": "string",
+            "description": "editable 模式下内嵌 input 的类名"
+        },
+        "editInputWidth": {
+            "type": "number",
+            "description": "editable 模式下内嵌 input 的宽度（默认根据内容自适应）"
+        },
+        "maxWidth": {
+            "type": "number | string",
+            "description": "标签最大宽度。超出时配合 AutoTips 显示 tooltip（不截断）"
+        },
+        "tipMaxWidth": {
+            "type": "number | string",
+            "description": "AutoTips tooltip 的最大宽度（src/Tag/index.tsx:56,310 实证：透传给 AutoTips 的 tipMaxWidth prop，控制文案截断时 tooltip 浮层宽度）"
+        },
+        "onEdit": {
+            "type": "function",
+            "signature": "(event: React.MouseEvent) => void",
+            "description": "编辑图标点击回调（src/Tag/index.tsx:38,198 实证：editable=true 时点击前缀 EditIcon 触发，可通过 event.preventDefault() 阻止切换为 input 编辑状态）"
+        },
+        "getWidth": {
+            "type": "function",
+            "signature": "(width: number) => void",
+            "description": "获取标签宽度回调（src/Tag/index.tsx:40,115 实证：挂载及 inputVisible 变化后通过 useEffect 将 tagRef 的 offsetWidth 传出）"
+        },
+        "marginBottom": {
+            "type": "string",
+            "description": "标签下边距（src/Tag/index.tsx:58,136 实证：inline style 直接透传，用于 TagGroup 等批量排列场景控制行间距）"
+        },
+        "marginRight": {
+            "type": "string",
+            "description": "标签右边距（src/Tag/index.tsx:60,137 实证：inline style 直接透传，用于 TagGroup 等批量排列场景控制列间距）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Tag/index.tsx:48 interface 声明，透传到根 span 元素）"
+        }
+    },
+    "do": [
+        "使用颜色区分不同类型的标签——状态徽章推荐：green=激活/成功、yellow=警告/待处理、red=错误/危险、blue=信息/默认、灰色用 hex '#808080'",
+        "使用 closable 实现标签的删除交互（visible 受控时父组件 setState 移除；非受控时 src 内部自动隐藏）",
+        "需要可编辑标签时直接传 editable={true} + tagChange 回调——Tag 内置 EditIcon + input 渲染逻辑，**不需要在 children 内手写原生 <input>**；children 为 string 时作为 input 初始值",
+        "**跨组件引用 Tag 表达状态色**：在 Table render / Form 选项渲染等场景，用 `<Tag color='green'>已激活</Tag>` 而非 inline style 兜底——预设 4 色已覆盖大多数状态语义"
+    ],
+    "dont": [
+        "在 Tag 中放置过长的文本",
+        "滥用 Tag 作为按钮使用",
+        "**不要在 editable 模式同时传 icon**——editable=true 时前缀位置改渲染 EditIcon，icon prop 被忽略；如需图标 + 编辑混用，需自实现",
+        "不要假设非预设色（hex / rgb / 'gray'）有完整 hover/active CSS——非预设走 tinycolor 0.1 alpha 渲染，无专门样式"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "(event: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控关闭：onClose={(e) => setVisible(false)}",
+                "阻止默认隐藏（非受控场景）：onClose={(e) => { e.preventDefault(); /* 自定义逻辑 */ }}",
+                "受控模式父组件删除标签：onClose={() => setTags(prev => prev.filter(t => t.id !== id))}"
+            ],
+            "commonMistakes": [
+                "不传 visible prop 时期望 onClose 后标签仍显示——未传 visible 时 Tag 内部自动 setVisible(false)；要阻止需调 e.preventDefault()",
+                "假设 onClose 只在显式关闭时触发——Tag 本体 stopPropagation，但父元素 onClick 不受影响",
+                "忘记在受控模式（传了 visible）中通过 onClose 更新父 state——Tag 不会自动隐藏，需父组件响应 onClose 更新 visible"
+            ]
+        },
+        "onEdit": {
+            "signature": "(event: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听编辑图标点击：onEdit={(e) => console.log('edit clicked')}",
+                "阻止进入内置编辑态：onEdit={(e) => { e.preventDefault(); openCustomEditModal(); }}"
+            ],
+            "commonMistakes": [
+                "期望 onEdit 是编辑完成后的回调——onEdit 是点击编辑图标时触发；编辑完成回调是 tagChange",
+                "同时传 onEdit 和 editable 却期望自定义完全替代内置 input——onEdit 调 e.preventDefault() 才能阻止切换 input"
+            ]
+        },
+        "tagChange": {
+            "signature": "(value: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "实时同步编辑值：tagChange={(v) => setTagValue(v)}",
+                "受控：在 tagChange 中更新父组件 state，children 随之变化（editable 模式下 children 是初始值）"
+            ],
+            "commonMistakes": [
+                "假设 tagChange 是 onBlur/Enter 确认后触发——实际是实时 onChange（每次键入都触发）",
+                "不传 tagChange 期望 Tag 自己保存编辑值——编辑完成后父组件 children 不更新则下次进入编辑态仍是旧初始值"
+            ]
+        },
+        "getWidth": {
+            "signature": "(width: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取标签实际渲染宽度：getWidth={(w) => setTagWidth(w)}"
+            ],
+            "commonMistakes": [
+                "期望 getWidth 实时响应容器宽度变化——实际只在挂载时和 inputVisible 变化时触发（不是 ResizeObserver）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "TagProps extends React.HTMLAttributes<HTMLSpanElement>，onClick 等原生事件直接透传，不需要单独声明",
+            "wrong": "// 以为 Tag 没有 onClick，外层包一个 div：<div onClick={handleClick}><Tag>文本</Tag></div>",
+            "right": "<Tag onClick={handleClick}>文本</Tag>  // HTMLAttributes 的所有事件都可直接传"
+        },
+        {
+            "issue": "editable 模式下 children 只作为编辑态初始值，不是受控值——父组件更新 children 不刷新已激活 input",
+            "wrong": "// 期望 children 变化实时反映到编辑 input 中\n<Tag editable tagChange={setVal}>{controlledValue}</Tag>  // editInputVisible 激活后 children 更新不生效",
+            "right": "// 用 key 或在 tagChange 回调中维护 state：\nconst [val, setVal] = useState(initialValue);\n<Tag editable tagChange={setVal}>{val}</Tag>  // 父组件维护 val，但注意切换编辑时仍取最新 children 作初始值"
+        },
+        {
+            "issue": "非预设色（hex/rgb/'gray' 等）走 tinycolor 渲染，TS 不报错但无完整 hover/active CSS",
+            "wrong": "color='gray'  // TS 接受（string 类型），但没有专门 CSS，只有 tinycolor 0.1 alpha 背景",
+            "right": "// 预设色（有完整 CSS）：color='blue' | 'green' | 'yellow' | 'red'\n// 非预设色自定义（通用渲染）：color='#808080'  // 接受但无专门 hover/active 样式"
+        },
+        {
+            "issue": "closable 半受控行为：未传 visible 时 onClose 自动隐藏；传了 visible 则需父组件主动响应 onClose",
+            "wrong": "// 传了 visible 但不响应 onClose：\n<Tag closable visible={isVisible} onClose={() => {}}>文本</Tag>  // 点关闭后 Tag 不隐藏",
+            "right": "// 受控：onClose 更新父组件 state\n<Tag closable visible={isVisible} onClose={() => setIsVisible(false)}>文本</Tag>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Tag",
+        "adapter": null
+    }
+}

package/TextEditor/component.json ADDED Viewed

@@ -0,0 +1,186 @@
+{
+    "name": "TextEditor",
+    "category": "Data Entry",
+    "description": "基于 wangEditor 的富文本编辑器，支持图片/视频上传与自定义工具栏",
+    "semantic": {
+        "intent": [
+            "富文本编辑",
+            "内容创作"
+        ],
+        "useCases": [
+            "文章编辑",
+            "邮件编辑",
+            "公告发布"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "readonly"
+    ],
+    "idealProps": {
+        "server": {
+            "type": "string",
+            "required": true,
+            "description": "⚠️ 必传。文件上传服务地址(string 无问号);**即使不上传图片/视频也必须传占位 url(如 /api/noop)**;不传 TS 报错。占位场景安全:仅在用户主动插入图片/视频时才触发上传请求,纯文字编辑不会请求"
+        },
+        "value": {
+            "type": "string",
+            "description": "受控 HTML 字符串(配 onChange)"
+        },
+        "defaultValue": {
+            "type": "string",
+            "description": "非受控初始 HTML 字符串(配 ref 拿值);**也可与 onChange 同时使用监听变化,不互斥**"
+        },
+        "onChange": {
+            "type": "function",
+            "description": "(value: string, text: string) => void 内容变化回调;受控/非受控均可用"
+        },
+        "toolbarKeys": {
+            "type": "array",
+            "description": "完整工具栏菜单白名单(覆盖默认;空数组进入预览模式)。常用 menuKey:bold/italic/underline/bulletedList/numberedList/insertLink/uploadImage;详见 api.ts toolbarKeys 列出的完整 key"
+        },
+        "excludeKeys": {
+            "type": "array",
+            "description": "从默认工具栏排除的菜单 key 数组"
+        },
+        "max": {
+            "type": "number",
+            "description": "纯文本最大字符数"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "编辑器顶部标题"
+        },
+        "placeholder": {
+            "type": "string",
+            "default": "请输入内容",
+            "description": "空内容占位文案"
+        },
+        "required": {
+            "type": "boolean",
+            "default": "false",
+            "description": "UI 必填标记"
+        },
+        "readOnly": {
+            "type": "boolean",
+            "default": "false",
+            "description": "只读模式(展示语义)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "禁用模式(权限语义;内部强制 readOnly)"
+        },
+        "uploadImage": {
+            "type": "object",
+            "description": "图片上传配置 Partial<UpLoadImgConfig>"
+        },
+        "in18": {
+            "type": "enum",
+            "values": [
+                "en",
+                "zh-CN"
+            ],
+            "description": "国际化语言。**⚠️ src prop 名是 in18(历史 typo · 实际应为 i18n);写 i18n 不会切换语言也不报错**"
+        }
+    },
+    "do": [
+        "受控模式传 value + onChange 保持内容同步；非受控模式传 defaultValue + ref 拿值",
+        "server 必传：即使纯文字场景也要传占位 URL（如 /api/noop），否则 TS 报错",
+        "用 ref 调用命令式 API（getContent/getText/clearEditor/setContent）而非直接操控 DOM",
+        "toolbarKeys=[] 可切换到预览模式（只读展示，无工具栏），适合详情页展示富文本内容",
+        "in18 属性控制工具栏语言，注意 prop 名是 in18（历史 typo，不是 i18n）",
+        "需要限制字数时用 max 属性（对应 wangEditor maxLength，按纯文本字符数计算）"
+    ],
+    "dont": [
+        "不要同时传 value + defaultValue（受控/非受控不能混用）",
+        "不要忘记 server 属性——即使不上传图片也必须传占位 URL，否则 TS 类型错误",
+        "不要把 onChange 回调中的 value 直接 dangerouslySetInnerHTML 展示——须经 XSS 过滤",
+        "不要在 onBlur/onFocus 中直接操作 editor 实例的 DOM，应通过 IDomEditor 提供的 API",
+        "不要在组件卸载后访问 ref.current（组件内部已在 useEffect cleanup 中 destroy editor）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: string, text: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "内容变化时触发：value 是 HTML 字符串（getHtml()），text 是纯文本（getText()）",
+                "受控模式：onChange 中调用 setState 更新 value prop，实现受控回路",
+                "字数统计：用 text.length 而非 value.length（HTML 含标签字符会计入 value.length）"
+            ],
+            "commonMistakes": [
+                "假设 value 参数是纯文本——value 实际是 HTML 字符串，纯文本用第二参 text",
+                "受控模式下不在 onChange 中更新 value prop——导致编辑器内容反复跳回",
+                "初始化时 defaultValue 设置后 onChange 也会触发——内部 valueRef 机制防抖，但需注意初始渲染的 HTML 等价性检查"
+            ]
+        },
+        "onBlur": {
+            "signature": "(editor: IDomEditor) => void",
+            "asyncSupported": false,
+            "examples": [
+                "失焦时触发：editor 是 wangEditor IDomEditor 实例，可通过 editor.getHtml() 获取最新内容",
+                "表单校验场景：在 onBlur 中调用父表单的校验方法",
+                "自动保存：onBlur 时发送草稿保存请求"
+            ],
+            "commonMistakes": [
+                "假设 onBlur 时内容一定与 onChange 最后一次触发一致——如果内容没变 onChange 不触发，onBlur 仍会触发",
+                "在 onBlur 中直接调用 editor.destroy()——组件内部有自己的生命周期管理，外部不要手动销毁"
+            ]
+        },
+        "onFocus": {
+            "signature": "(editor: IDomEditor) => void",
+            "asyncSupported": false,
+            "examples": [
+                "聚焦时触发：editor 是 IDomEditor 实例",
+                "显示字数统计 UI：onFocus 时展示计数条"
+            ],
+            "commonMistakes": [
+                "在 onFocus 中调用 editor.focus() 会造成递归触发——已经聚焦不要再次 focus"
+            ]
+        },
+        "onDestroyed": {
+            "signature": "(editor: IDomEditor) => void",
+            "asyncSupported": false,
+            "examples": [
+                "编辑器实例销毁时触发（组件卸载时内部调用 editor.destroy()）",
+                "用于清理与 editor 实例关联的外部副作用（如自定义菜单注册）"
+            ],
+            "commonMistakes": [
+                "在 onDestroyed 中访问 editor.getHtml()——销毁时内部 editor 状态可能已清空"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "prop 名是 in18 不是 i18n（历史拼写 typo）",
+            "wrong": "// 写 i18n 不报错但不生效\n<TextEditor i18n='en' server='/api/upload' />",
+            "right": "<TextEditor in18='en' server='/api/upload' />  // 注意是 in18，不是 i18n"
+        },
+        {
+            "issue": "server 属性是必填的，即使不上传图片也要传",
+            "wrong": "// 缺少 server 会导致 TS 类型错误 'Property server is missing'\n<TextEditor value={html} onChange={setHtml} />",
+            "right": "<TextEditor value={html} onChange={setHtml} server='/api/upload' />"
+        },
+        {
+            "issue": "useRef 拿 TextEditorRef 类型时需正确声明泛型",
+            "wrong": "const ref = useRef(null); ref.current.getContent(); // ref.current 为 null，TS 报错",
+            "right": "import { TextEditorRef } from '@para-ui/core'; const ref = useRef<TextEditorRef>(null); ref.current?.getContent();"
+        },
+        {
+            "issue": "onChange 第一参是 HTML 字符串不是纯文本",
+            "wrong": "onChange={(value) => setCount(value.length)}  // value.length 包含 HTML 标签字符数",
+            "right": "onChange={(value, text) => setCount(text.length)}  // 用第二参 text 获取纯文本长度"
+        }
+    ],
+    "mapping": {
+        "realComponent": "TextEditor",
+        "adapter": null
+    }
+}