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

package/lib/Image/component.json

@@ -0,0 +1,165 @@
+{
+    "name": "Image",
+    "category": "Data Display",
+    "description": "图片组件,基于 rc-image 封装。支持点击预览(放大 / 旋转 / 翻转 / 切换 / 关闭)、加载失败 fallback、占位 placeholder、PreviewGroup 多图轮播。**Props 继承自 rc-image ImageProps,包含所有原生 <img> 属性 + 预览/失败/占位扩展字段**",
+    "semantic": {
+        "intent": [
+            "图片展示",
+            "点击预览大图",
+            "多图轮播预览组"
+        ],
+        "useCases": [
+            "产品详情图(单图 + 预览)",
+            "图片墙 / 相册(多图 + PreviewGroup 轮播)",
+            "用户头像(disabled preview)",
+            "需要 fallback 的弱网场景"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**3 个核心 import 入口**:\n1. `import Image from '@para-ui/core/Image'` (默认) 或 `import { Image } from '@para-ui/core'` (barrel)\n2. `Image.PreviewGroup` —— 复合组件,包裹多张 <Image> 实现轮播预览\n3. `import type { ImageProps } from '@para-ui/core/Image'` —— TS 类型\n\n**Props 来源**:Props 继承自 rc-image 的 ImageProps,**包含全部原生 <img> HTML 属性**(width / height / alt / src / loading 等)+ 4 个 rc-image 扩展字段(preview / fallback / placeholder / onError)。para-ui 在此基础上加了 `prefix-cls` 配置和默认 preview icons / mask",
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换;尺寸用 width/height 控)"
+        }
+    },
+    "states": [
+        "loading",
+        "loaded",
+        "error"
+    ],
+    "idealProps": {
+        "src": {
+            "type": "string",
+            "description": "图片地址(透传给底层 <img>)"
+        },
+        "alt": {
+            "type": "string",
+            "description": "替代文本(透传给底层 <img>,无障碍 + 加载失败前显示)"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "图片宽度(透传给底层 <img>;数字默认 px,字符串可带单位)"
+        },
+        "height": {
+            "type": "string | number",
+            "description": "图片高度"
+        },
+        "preview": {
+            "type": "boolean | PreviewType",
+            "default": true,
+            "description": "**预览开关 + 配置**:\n- `true`(默认): 点击图片触发全屏预览(支持放大/旋转/翻转/重置/关闭,icons 已内置)\n- `false`: 关闭预览(点击图片无反应,适合纯展示 / 头像)\n- `{ mask?: ReactNode, getContainer?: () => HTMLElement, ... }`: 对象形式,自定义遮罩/挂载容器等(透传 rc-image PreviewType)"
+        },
+        "fallback": {
+            "type": "string",
+            "description": "**加载失败时显示的图片 URL**。底层 <img> onError 自动切换,无需手动传 onError"
+        },
+        "placeholder": {
+            "type": "ReactNode",
+            "description": "**加载中占位**(可以是文字 / 骨架屏 / 旋转图标 / Spin 组件等任意 JSX)。仅在 loading 阶段渲染"
+        },
+        "onError": {
+            "type": "(event: React.SyntheticEvent<HTMLImageElement>) => void",
+            "description": "原生 <img> onError 事件透传。**注意**:fallback 已经在 rc-image 内部监听 onError 自动切换 src,通常不需要再传 onError(除非有额外逻辑)"
+        },
+        "className": {
+            "type": "string",
+            "description": "应用到 <img> 元素的 className(不是外层 wrapper)"
+        },
+        "rootClassName": {
+            "type": "string",
+            "description": "应用到外层 wrapper <div> 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "<img> 元素的 style(数字 width/height 也可写在 style 里)"
+        }
+    },
+    "subComponents": {
+        "Image.PreviewGroup": {
+            "import": "// 通过 Image 复合属性访问: <Image.PreviewGroup>...</Image.PreviewGroup>",
+            "purpose": "多张 Image 包裹在一起实现轮播预览(打开任一张图后,可左右切换浏览组内其他图)",
+            "props": "GroupConsumerProps (来自 rc-image),preview 字段同 Image.preview"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "认为 preview prop 需要配合 onPreview 回调或外部 Modal 才能工作: `<Image src={url} onPreview={...} />`",
+            "result": "Image **没有 onPreview prop** —— 预览功能完全内置(rc-image 内部弹层 + 内置 icons)。传 onPreview 会被 TS 忽略",
+            "fix": "只要 preview=true(默认),点击图片自动弹出预览。需要自定义遮罩内容用 `preview={{ mask: <CustomMask /> }}` 对象形式"
+        },
+        "M2": {
+            "wrong": "想关闭预览写 `<Image src={url} preview={null} />` 或 `preview={undefined}`",
+            "result": "**只有显式 `preview={false}` 才关闭预览** —— null/undefined 都被当作 truthy(走默认 true 分支)",
+            "fix": "关闭预览:`preview={false}`(布尔字面量)。条件性关闭:`preview={shouldDisable ? false : true}`"
+        },
+        "M3": {
+            "wrong": "为加载失败 fallback 手动写 onError 切换 src: `<Image src={url} onError={e => e.target.src = fallbackUrl} />`",
+            "result": "可以工作但**冗余且容易出 bug**(setState 时机问题、TS 类型问题)",
+            "fix": "用 fallback prop:`<Image src={url} fallback={'/img/broken.png'} />` —— rc-image 内部 onError 自动切换"
+        },
+        "M4": {
+            "wrong": "认为 Image 只接受 component.json idealProps 列出的 4 个字段(src / alt / preview / fallback),width/height/style 不接受",
+            "result": "Image 实际继承 rc-image 的 ImageProps,**全部原生 <img> 属性都接受**(width/height/loading/decoding/crossOrigin/referrerPolicy/sizes/srcSet 等)",
+            "fix": "需要的 img 属性直接传即可。component.json idealProps 是常用字段,不是完整 props 清单"
+        },
+        "M5": {
+            "wrong": "用 PreviewGroup 时给每张 Image 单独设 preview prop: `<Image.PreviewGroup>{imgs.map(u => <Image src={u} preview />)}</Image.PreviewGroup>`",
+            "result": "可以工作,但 PreviewGroup 自己的 preview prop 才是统一控制入口。单个 Image 的 preview 在 Group 上下文中会被合并",
+            "fix": "推荐:`<Image.PreviewGroup preview={{ ...sharedConfig }}>{imgs.map(u => <Image src={u} />)}</Image.PreviewGroup>` —— 组级配置一次写,所有图共享"
+        }
+    },
+    "completeExample": "// 1. 基本单图 + 预览\nimport Image from '@para-ui/core/Image';\n\nconst BasicDemo = () => (\n    <Image\n        src='https://example.com/photo.jpg'\n        alt='示例图片'\n        width={200}\n        height={150}\n        fallback='https://example.com/broken.png'\n    />\n);\n\n// 2. 多图轮播组 (PreviewGroup)\nconst GalleryDemo = () => (\n    <Image.PreviewGroup>\n        <Image src='https://example.com/1.jpg' width={120} />\n        <Image src='https://example.com/2.jpg' width={120} />\n        <Image src='https://example.com/3.jpg' width={120} />\n    </Image.PreviewGroup>\n);\n\n// 3. 关闭预览的头像\nconst AvatarDemo = () => (\n    <Image\n        src='https://example.com/avatar.jpg'\n        alt='用户头像'\n        width={48}\n        height={48}\n        preview={false}  // 头像通常不需要预览\n        style={{ borderRadius: '50%' }}\n    />\n);\n\n// 4. 加载占位 + 失败 fallback\nconst RobustDemo = () => (\n    <Image\n        src='https://maybe-slow.example.com/photo.jpg'\n        alt='可能慢的图'\n        width={300}\n        height={200}\n        placeholder={<div style={{ background: '#eee', width: 300, height: 200 }}>加载中...</div>}\n        fallback='/img/default-broken.png'\n    />\n);",
+    "do": [
+        "**单图预览**:`<Image src={url} preview />` 即可(默认 preview=true,无需配置)",
+        "**多图轮播**:用 `<Image.PreviewGroup>` 包裹,自动支持左右切换",
+        "**关闭预览**:必须显式传 `preview={false}`(头像 / 装饰图 / 纯展示)",
+        "**加载失败兜底**:用 `fallback` prop 而不是手动写 onError(M3)",
+        "需要的原生 img 属性(width/height/loading 等)直接传(M4)"
+    ],
+    "dont": [
+        "**不要**写 onPreview / showPreview prop——它不存在,预览完全内置(M1)",
+        "**不要**用 preview={null} / preview={undefined} 关预览——只有 false 生效(M2)",
+        "**不要**手动写 onError 实现 fallback——用 fallback prop(M3)",
+        "**不要**以为 Image 只接受 idealProps 4 字段——它继承全部原生 img + rc-image 字段(M4)",
+        "**不要**在 PreviewGroup 内给每张图独立设 preview——用 Group 级别配置(M5)",
+        "忽略 alt(无障碍 + SEO + 失败前显示)",
+        "不设置 width/height(避免布局跳动)"
+    ],
+    "events": {
+        "onError": {
+            "signature": "(event: React.SyntheticEvent<HTMLImageElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onError={(e) => console.error('图片加载失败', e)} — 用于上报/监控，通常配合 fallback 使用",
+                "只需要兜底图不需要监听：直接用 fallback prop，不需要手写 onError",
+                "需要额外逻辑（如记录 404 url）：onError={(e) => { reportBrokenImage(src); }} 和 fallback='/broken.png' 共存"
+            ],
+            "commonMistakes": [
+                "手写 onError 切换 src: onError={(e) => (e.target as HTMLImageElement).src = fallbackUrl} — 冗余且有 setState 时机问题，用 fallback prop 替代",
+                "期望 onError 在 preview 打开时大图失败触发——onError 绑定在缩略图 <img> 上，预览大图的错误无法捕获",
+                "传了 fallback 又传 onError 期望双重兜底——fallback 内部会先触发 onError 切换 src，自定义 onError 也会同时触发，注意不要重复处理"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "preview={null} 或 preview={undefined} 不会关闭预览——只有 preview={false} 才关闭",
+            "wrong": "const noPreview = null; <Image src={url} preview={noPreview} /> // null 被视为 truthy 条件的对象分支，预览仍开启",
+            "right": "<Image src={url} preview={false} /> // 布尔字面量 false，或条件写法: preview={shouldDisable ? false : true}"
+        },
+        {
+            "issue": "Image 的 props 继承自 rc-image ImageProps，不是自定义 Props 类型，部分原生 img 属性可能有类型差异",
+            "wrong": "import { ImageProps } from '@para-ui/core'; const props: ImageProps = { onLoad: () => {} }; // onLoad 在 rc-image 里类型和原生 img 略有差异",
+            "right": "import type { ImageProps } from '@para-ui/core/Image'; // 从子路径导入精确类型，避免 barrel 导出类型不一致"
+        },
+        {
+            "issue": "Image.PreviewGroup 是复合属性，不能从 @para-ui/core 直接解构",
+            "wrong": "import { Image, ImagePreviewGroup } from '@para-ui/core'; <ImagePreviewGroup> // ImagePreviewGroup 不是导出名",
+            "right": "import Image from '@para-ui/core/Image'; <Image.PreviewGroup> // 通过复合组件访问"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Image",
+        "adapter": null
+    }
+}

package/lib/InputCode/component.json

@@ -0,0 +1,191 @@
+{
+    "name": "InputCode",
+    "category": "Data Entry",
+    "description": "验证码输入组件，分两个子组件：InputCode.Card（独立多格卡片/下划线样式）+ InputCode.Input（含获取验证码按钮的一行式输入框）。两者均支持受控/非受控、倒计时、错误提示",
+    "semantic": {
+        "intent": [
+            "安全验证",
+            "验证码输入"
+        ],
+        "useCases": [
+            "短信验证",
+            "邮箱验证",
+            "双因素认证"
+        ],
+        "riskLevel": "high"
+    },
+    "protocolSummary": "**两个子组件差异对比**:\n- `InputCode.Card`：多格卡片式（每格一个字符），type='card'|'underline'，value/onChange 是 string[]，onFinish 在最后一格输入完成时触发，onReset 重新发送（返回 Promise<boolean>，true 才启动倒计时）\n- `InputCode.Input`：一体式（带获取验证码按钮），type='btnIntegrated'|'btnSplit'，value/onChange 是 string（整串），onGetCode 点击获取验证码按钮时触发（返回 Promise<boolean>，true 才启动倒计时）\n\n**import 方式**: `import { InputCode } from '@para-ui/core'`，然后用 `<InputCode.Card />` 或 `<InputCode.Input />`",
+    "variants": {
+        "card": {
+            "meaning": "卡片样式（InputCode.Card type='card'）"
+        },
+        "underline": {
+            "meaning": "下划线样式（InputCode.Card type='underline'）"
+        },
+        "btnIntegrated": {
+            "meaning": "按钮与输入框合一（InputCode.Input type='btnIntegrated'）"
+        },
+        "btnSplit": {
+            "meaning": "按钮与输入框分离（InputCode.Input type='btnSplit'）"
+        }
+    },
+    "states": [
+        "default",
+        "error",
+        "countdown"
+    ],
+    "subComponents": {
+        "InputCode.Card": {
+            "description": "多格卡片/下划线验证码输入；每格一字符，自动聚焦下一格，支持粘贴",
+            "props": "InputCodeCardProps",
+            "keyProps": "cardNumber(格数,默认6), type('card'|'underline'), value(string[]), onChange((val:string[])=>void), onFinish((val:string)=>void), onReset(()=>Promise<boolean>|boolean), refreshCountdown(触发倒计时), countdown(秒数), sendText(倒计时区域标题)"
+        },
+        "InputCode.Input": {
+            "description": "一行式验证码输入框 + 获取验证码按钮；value 是整串字符串",
+            "props": "InputCodeInputProps",
+            "keyProps": "type('btnIntegrated'|'btnSplit'), value(string), onChange((val:string)=>void), onGetCode(()=>Promise<boolean>|boolean), countdown(秒数), getCodeWidth(获取验证码按钮宽度), inputProps(TextField透传), label, required"
+        }
+    },
+    "idealProps": {
+        "cardNumber": {
+            "type": "number",
+            "default": 6,
+            "description": "（InputCode.Card）验证码格数"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "card",
+                "underline",
+                "btnIntegrated",
+                "btnSplit"
+            ],
+            "default": "card",
+            "description": "样式类型：Card 子组件用 card/underline，Input 子组件用 btnIntegrated/btnSplit"
+        },
+        "value": {
+            "type": "string[] (Card) | string (Input)",
+            "description": "受控值：Card 是 string[]（每格一项），Input 是 string（完整验证码串）"
+        },
+        "onChange": {
+            "type": "(val: string[]) => void (Card) | (val: string) => void (Input)",
+            "description": "值变化回调；类型随子组件不同"
+        },
+        "onFinish": {
+            "type": "(val: string) => void",
+            "description": "（InputCode.Card）最后一格输入完成时触发，val 是所有格拼接的完整字符串"
+        },
+        "onReset": {
+            "type": "() => Promise<boolean> | boolean",
+            "description": "（InputCode.Card）点击重新发送时触发；返回 true 才启动倒计时"
+        },
+        "onGetCode": {
+            "type": "() => Promise<boolean> | boolean",
+            "description": "（InputCode.Input）点击获取验证码按钮时触发；返回 true 才启动倒计时"
+        },
+        "countdown": {
+            "type": "number",
+            "default": 60,
+            "description": "倒计时秒数"
+        },
+        "refreshCountdown": {
+            "type": "number | undefined",
+            "description": "（InputCode.Card）变更为非 undefined 时触发倒计时重置；通常传递递增计数器触发"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误提示文案"
+        }
+    },
+    "do": [
+        "自动聚焦下一个输入框（InputCode.Card 内置行为）",
+        "支持粘贴完整验证码（InputCode.Card 自动拆分到各格）",
+        "验证码位数与后端接口保持一致，通过 cardNumber 配置",
+        "onReset/onGetCode 配合接口请求：return await sendSMS() 成功才启动倒计时"
+    ],
+    "dont": [
+        "验证码位数与后端不一致——cardNumber 默认 6，后端 4 位时必须显式传 cardNumber={4}",
+        "没有倒计时限制——必须配置 countdown + onReset/onGetCode 防止频繁请求",
+        "Card 和 Input 子组件混用 value 类型——Card 是 string[]，Input 是 string，混用导致类型错误"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string[]) => void (Card) | (val: string) => void (Input)",
+            "asyncSupported": false,
+            "examples": [
+                "InputCode.Card: onChange={(val) => setCode(val)} — val 是 string[]，如 ['1','2','3','4','5','6']",
+                "InputCode.Input: onChange={(val) => setCode(val)} — val 是整串字符串，如 '123456'",
+                "受控模式：需同时传 value 和 onChange，否则输入会被重置"
+            ],
+            "commonMistakes": [
+                "Card 子组件把 onChange 当 string 类型使用——Card.onChange 是 (val: string[]) => void 而不是 (val: string) => void",
+                "只传 onChange 不传 value 期望半受控——两者都传或都不传，半受控（有 onChange 无 value）在 rc 体系里行为不稳定",
+                "期望 onChange 在初始化时触发——组件 mount 时不触发 onChange，只在用户输入/粘贴时触发"
+            ]
+        },
+        "onFinish": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onFinish={(code) => verifyCode(code)} — 最后一格输入完成时触发，val 是 cardNumber 个字符拼接的字符串",
+                "onFinish={(code) => { if (code.length === cardNumber) submit(code); }} — 可在回调里额外校验长度",
+                "onFinish 不在 InputCode.Input 上——Input 子组件无 onFinish，需自己判断 onChange 的 val.length === 期望长度"
+            ],
+            "commonMistakes": [
+                "在 InputCode.Input 上找 onFinish——Input 子组件没有 onFinish prop，只有 onChange",
+                "期望 onFinish 触发时验证码一定全填——用户可能粘贴后再清除，建议在 onFinish 里再次校验 val.length",
+                "传了 value 受控但 onFinish 里直接调接口不等 onChange 更新——受控模式 onChange 触发后父组件需更新 value，onFinish 里的 val 是当前内部状态"
+            ]
+        },
+        "onReset": {
+            "signature": "() => Promise<boolean> | boolean",
+            "asyncSupported": true,
+            "examples": [
+                "onReset={async () => { const ok = await sendSMS(); return ok; }} — 返回 true 时启动倒计时，false 时不启动",
+                "onReset={() => true} — 测试用，直接返回 true 立即启动倒计时",
+                "onReset={async () => { try { await api.resend(); return true; } catch { return false; } }} — 接口失败时返回 false 不重置倒计时"
+            ],
+            "commonMistakes": [
+                "onReset 没有 return 值——隐式返回 undefined，被当作 falsy，倒计时不启动",
+                "在 InputCode.Input 上传 onReset——Input 子组件的对应 prop 是 onGetCode，不是 onReset",
+                "期望 onReset 触发时自动清空验证码格——src 不自动清空 value，需父组件在 onReset 里手动 setValue(new Array(cardNumber).fill(''))"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "InputCode.Card 和 InputCode.Input 的 value/onChange 类型不同，不能共用同一个 state",
+            "wrong": "const [code, setCode] = useState<string>(''); <InputCode.Card value={code} onChange={setCode} /> // Card value 是 string[]，TS2322",
+            "right": "const [code, setCode] = useState<string[]>([]); <InputCode.Card value={code} onChange={setCode} /> // Card 用 string[]"
+        },
+        {
+            "issue": "onReset/onGetCode 返回类型是 Promise<boolean> | boolean，必须有明确返回值",
+            "wrong": "onReset={async () => { await sendSMS(); }} // 没有 return，隐式 undefined，倒计时不启动",
+            "right": "onReset={async () => { await sendSMS(); return true; }} // 明确 return true 才启动倒计时"
+        },
+        {
+            "issue": "refreshCountdown 触发倒计时的是「值变化」不是「变成非 undefined」，传固定值无效",
+            "wrong": "// 用 boolean 控制：refreshCountdown={shouldRefresh ? 1 : undefined} // 只在第一次 undefined→1 时触发，第二次不变",
+            "right": "const [counter, setCounter] = useState(0); // 每次重置递增\nonReset={async () => { setCounter(c => c+1); return true; }}\n<InputCode.Card refreshCountdown={counter} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "InputCode",
+        "adapter": null
+    }
+}

package/lib/InputCode/index.d.ts

@@ -34,7 +34,7 @@ export interface InputCodeCardProps extends HelperTextDetailProps {
     onFinish?: (val: string) => void;
     /** 重新发送 */
     onReset?: () => Promise<boolean> | boolean;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface InputCodeInputProps extends HelperTextDetailProps {
     /** 样式class */
@@ -66,7 +66,7 @@ export interface InputCodeInputProps extends HelperTextDetailProps {
     onChange?: (val: string) => void;
     /** 获取验证码事件 */
     onGetCode?: () => Promise<boolean> | boolean;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 type MergedInputCode = {
     Card: typeof InputCodeCard;

package/lib/InputLang/component.json

@@ -0,0 +1,205 @@
+{
+    "name": "InputLang",
+    "category": "Data Entry",
+    "description": "多语言输入框,支持多语种内容录入 + 语种切换。内部维护多语对象 `{[langKey]: string}`,通过 typeOutput 控制输出形态(对象 / JSON 字符串)",
+    "semantic": {
+        "intent": [
+            "多语言内容录入",
+            "国际化字段管理",
+            "翻译数据编辑"
+        ],
+        "useCases": [
+            "i18n 产品名 / 标签 / 描述录入",
+            "翻译管理后台",
+            "多语种 SEO 字段"
+        ],
+        "riskLevel": "normal"
+    },
+    "keyFormatBehavior": {
+        "supportedFormats": "**支持任意字符串作为 langKey**:短码('zh'/'en')、BCP 47('zh-CN'/'en-US'/'ja-JP')、自定义键名都可以。组件**不校验键名格式**,只把 langList 条目当作 value 对象的 key 使用",
+        "examples": "// 都合法:\n<InputLang langList={['zh', 'en']} value={{zh: '你好', en: 'Hello'}} />\n<InputLang langList={['zh-CN', 'en-US']} value={{'zh-CN': '你好', 'en-US': 'Hello'}} />\n<InputLang langList={['simplified', 'traditional']} value={{simplified: '你好', traditional: '妳好'}} />",
+        "warning": "**value 对象的 key 必须与 langList 字符串/value 字段完全匹配**(区分大小写 + 区分连字符)。例如 langList=['zh-CN'] 但 value={zh: '你好'} 时,InputLang 切到 zh-CN 标签后读不到值"
+    },
+    "langListDisplayBehavior": {
+        "stringMode": "**简写 string[] 模式**:每个字符串既是 value(内部 key)又是 label(弹层显示文本)。例 `langList={['zh-CN', 'en-US']}` 时,弹层切换 tab 显示的是 'zh-CN' / 'en-US' 字符串本身,**不是 '中文' / '英文' 本地化名称**",
+        "objectMode": "**对象 `{label, value}[]` 模式**:label 用于弹层显示,value 用于 value 对象的 key。例 `langList={[{label: '中文', value: 'zh-CN'}, {label: 'English', value: 'en-US'}]}`,弹层显示 '中文' / 'English' 友好文本,内部 value 对象用 'zh-CN' / 'en-US' 作 key",
+        "useWhen": "纯开发场景(配置 / 调试):用 string[] 简洁。**用户面向场景:用 {label, value}[] 配本地化文本**(string[] 显示原始 key 不友好)"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "标题旁帮助提示;对象,见 Label 组件 LabelTooltipProps"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入值的提示语(非语言键)"
+        },
+        "placeholderKey": {
+            "type": "string",
+            "description": "语言键侧的提示语;label='国际化' 模式常配合 placeholder 使用"
+        },
+        "placeholderValue": {
+            "type": "string",
+            "description": "翻译值侧的提示语"
+        },
+        "langList": {
+            "type": "(string | { label: string; value: string })[]",
+            "default": "['zh', 'en']",
+            "description": "**支持的语种列表**。两种形态:① 简写 string[] 如 `['zh', 'en']` —— 弹层显示原始 key 字符串(非本地化名);② 对象 `{label, value}[]` 如 `[{label:'中文',value:'zh'}]` —— 弹层显示 label 文本,内部用 value 作 key。**任意字符串都可作 langKey**(短码 / BCP 47 / 自定义,见 keyFormatBehavior)"
+        },
+        "value": {
+            "type": "string | { [name: string]: string }",
+            "description": "**受控值,形态由 typeOutput 控制**:typeOutput='object'(默认)→ `{zh:'输入框', en:'...'}` 多语对象;typeOutput='string' → JSON 字符串如 `'{\"zh\":\"输入框\",\"en\":\"...\",\"_i18n\":1}'`。**注:不是 Record<string,string>**(虽然语义上等价,签名是 `{[name]: string}` 索引签名形态),业务用 Record<string,string> 时需要 `as unknown as` 中转"
+        },
+        "defaultValue": {
+            "type": "string | { [name: string]: string }",
+            "description": "非受控初始值;形态同 value。可与 langList string[] 简写组合使用(两者正交)"
+        },
+        "onChange": {
+            "type": "(val: string | { [name: string]: string }) => void",
+            "description": "值变化回调;val 形态随 typeOutput 变化(string 或对象)。**业务签名 (val: Record<string, string>) => void**:可用 typeof 守卫 + `as unknown as Record<string,string>` 处理"
+        },
+        "typeOutput": {
+            "type": "enum",
+            "values": [
+                "string",
+                "object"
+            ],
+            "default": "object",
+            "description": "输出类型;'object' 输出多语对象,'string' 输出 JSON 字符串(含 _i18n 标识位)"
+        },
+        "required": {
+            "type": "boolean",
+            "default": "false",
+            "description": "是否必填"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "是否禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用态 hover 提示。**常用字段**:`title: ReactNode`(提示内容,最常用)、`placement?: 'top'|'bottom'|'left'|'right'|...`(方向)、`arrow?: boolean`(显示箭头)。完整字段见 Tooltip 组件文档"
+        },
+        "error": {
+            "type": "boolean",
+            "default": "false",
+            "description": "错误态视觉"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误文本/辅助文本"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "description": "true=无错误时不渲染占位;false=都渲染;null=不渲染直接返回 null。见 HelperText 同名 prop"
+        },
+        "limitLength": {
+            "type": "number",
+            "description": "输入长度上限"
+        },
+        "i18n": {
+            "type": "boolean",
+            "description": "i18n 标识;typeOutput='string' 时默认 true(向输出 JSON 注入 _i18n=1)"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "传 langList=['zh-CN', 'en-US'] 但 value={{ zh: '你好', en: 'Hello' }}(value 用短码 key)",
+            "result": "InputLang 切换到 'zh-CN' / 'en-US' 标签时读不到 value(因为 value 对象用的是 'zh'/'en' 短码 key) → 显示空内容",
+            "fix": "**langList 字符串/value 字段与 value 对象 key 必须完全一致**:要么都用短码(`langList=['zh','en']` + `value={{zh:'',en:''}}`),要么都用 BCP 47(`langList=['zh-CN','en-US']` + `value={{'zh-CN':'','en-US':''}}`)"
+        },
+        "M2": {
+            "wrong": "用 langList=['zh-CN', 'en-US'] 期望弹层显示 '中文' / 'English' 友好文本",
+            "result": "**string[] 简写模式弹层显示原始字符串**(显示 'zh-CN' / 'en-US' 而非翻译名)",
+            "fix": "用对象形式 `langList={[{label: '中文', value: 'zh-CN'}, {label: 'English', value: 'en-US'}]}` —— label 是显示文本,value 是内部 key"
+        },
+        "M3": {
+            "wrong": "在 onChange 回调签名是 `(val: Record<string, string>) => void` 的业务接口里直接接 InputLang.onChange,期望 TS 自动兼容",
+            "result": "**InputLang.onChange 签名是 `(val: string | { [name: string]: string }) => void`**,有 string 联合分支。直接传业务 callback 会因 string 分支不兼容 → TS 报错",
+            "fix": "用 typeof 守卫 + cast: `onChange={(val) => { if (typeof val !== 'string') businessCallback(val as unknown as Record<string, string>); }}` 或者用 typeOutput='object' 保证不会出现 string 分支"
+        },
+        "M4": {
+            "wrong": "假设 langList 默认值是空数组",
+            "result": "**默认值是 `['zh', 'en']`**(代码 L114 实证)。不传 langList 时 InputLang 仍然显示 zh/en 两个语种 tab",
+            "fix": "需要纯空白:显式传 `langList={[]}`(罕见)。需要完全自定义语种:传完整 langList 覆盖默认"
+        }
+    },
+    "do": [
+        "**langList 字符串/value 字段与 value 对象 key 一致**(全短码或全 BCP 47,见 M1)",
+        "**用户面向场景用对象形式 langList**(配 label 本地化文本,M2)",
+        "**业务 callback Record<string,string>**:typeof 守卫 + as unknown as 中转(M3)",
+        "**typeOutput 默认 'object'** —— 直接用对象形态;只在需要 JSON 持久化时用 'string'",
+        "禁用态配合 disabledTooltip={{title: '已归档,不可编辑'}} 给业务语义化提示"
+    ],
+    "dont": [
+        "**不要**让 langList key 与 value 对象 key 不一致 —— 读不到值(M1)",
+        "**不要**用 string[] langList 期望本地化显示 —— 显示原始 key(M2)",
+        "**不要**直接对接 Record<string,string> 业务 callback —— 联合签名不兼容(M3)",
+        "**不要**忘记不传 langList 时默认 ['zh','en'] —— 不是空数组(M4)",
+        "语言列表过多(>5)导致下拉过长 —— 考虑分组",
+        "忽略默认语言设置"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string | { [name: string]: string }) => void",
+            "asyncSupported": false,
+            "examples": [
+                "typeOutput='object'(默认): onChange={(val) => { if (typeof val !== 'string') setState(val as Record<string,string>); }} — 对象形态，{zh:'内容', en:'content'}",
+                "typeOutput='string': onChange={(val) => { if (typeof val === 'string') setState(val); }} — JSON 字符串形态，'{\"zh\":\"内容\",\"_i18n\":1}'",
+                "弹窗关闭时触发（不是实时）：用户在弹窗内修改其他语种值，关闭弹窗后 onChange 才触发一次完整 val"
+            ],
+            "commonMistakes": [
+                "onChange 签名写成 (val: Record<string, string>) => void 直接接入——TypeScript 报错，InputLang.onChange 联合 string 分支，需 typeof 守卫",
+                "期望每次按键都触发 onChange——主语言（当前展示语言）实时触发，其他语言在弹窗关闭时批量触发一次",
+                "typeOutput='string' 时期望 onChange 返回的 val 是纯 JSON——实际含 _i18n 标识位，需 JSON.parse 后 delete _i18n 才是干净数据"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名是联合类型，直接接业务 Record<string,string> 回调触发 TS 不兼容",
+            "wrong": "const handler = (val: Record<string, string>) => setState(val); <InputLang onChange={handler} /> // 报 TS2322：string 分支和 Record 不兼容",
+            "right": "<InputLang onChange={(val) => { if (typeof val !== 'string') setState(val as unknown as Record<string,string>); }} />"
+        },
+        {
+            "issue": "value 类型签名是 `string | { [name: string]: string }` 不是 `Record<string, string>`，在 TS 5.x 可能触发 TS2352 直接 as cast 失败",
+            "wrong": "const data: Record<string,string> = {zh: '你好'}; <InputLang value={data as { [name: string]: string }} /> // TS5 strict 模式下拒绝结构兼容 as",
+            "right": "<InputLang value={data as unknown as { [name: string]: string }} /> // 用 unknown 中转"
+        },
+        {
+            "issue": "langList 默认值是 ['zh', 'en']，不传时已经有两个语种 tab，不是空列表",
+            "wrong": "// 期望没有多语切换，不传 langList\n<InputLang value={val} onChange={onChange} /> // 实际显示 zh/en 两个 tab，点击地球图标弹出语种选择",
+            "right": "// 需要禁用多语：传 langList={[]}（无弹出语种）或 disabledAdd + disabledDelete + disabledKey 锁定行为"
+        }
+    ],
+    "mapping": {
+        "realComponent": "InputLang",
+        "adapter": null
+    }
+}

package/lib/InputLang/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const u=require("../_virtual/jsx-runtime.js"),r=require("react"),be=require("../TextField/index.js"),he=require("../HelperText/index.js"),me=require("../MultiBox/index.js"),ve=require("../AutoTips/index.js"),je=require("../Popover/index.js"),ye=require("../node_modules/@para-ui/icons/Internet/index.js"),K=require("../Utils/snack-kit-shims.js"),g=require("../GlobalContext/constant.js"),Ce=require("../Hooks/useGlobalProps.js");;/* empty css            */const W=f=>{const{className:$,style:z,label:H,labelTooltip:F,size:v="large",placeholder:q,placeholderKey:G,placeholderValue:J,error:L=!1,hideErrorDom:w,helperText:Q="",required:U=!1,popoverClassName:N,value:M,onChange:O,langList:x=["zh","en"],limitLength:E,disabled:S=!1,disabledTooltip:X,defaultLang:j,disabledDelete:_,disabledAdd:Y,disabledKey:R,typeOutput:V="object",i18n:k}=Ce.default(f,"InputLang"),[Z,D]=r.useState(!1),[o,ee]=r.useState(K.GetLanguage()||"zh"),[I,te]=r.useState({}),[b,T]=r.useState({}),[d,A]=r.useState([]),a=r.useRef({lang:o,valueCom:b,langMapping:{},langLabelMapping:{}}),P=r.useRef(null);a.current.lang=o,a.current.disabledDelete=_,a.current.typeOutput=V,a.current.i18n=V==="string"&&k===void 0?!0:k,r.useEffect(()=>{f.defaultValue!==void 0&&y(f.defaultValue)},[]),r.useEffect(()=>{M!==void 0&&y(M)},[M]),r.useEffect(()=>{j!==void 0&&(ee(j),a.current.lang=j,y())},[j]),r.useEffect(()=>{if(x){const e={},t={};for(let l=0,i=x.length;l<i;l++){const n=x[l];typeof n=="string"?(e[n]={label:n,value:n},t[n]={label:n,value:n}):(e[n.value]=n,t[n.label]=n)}a.current.langMapping=e,a.current.langLabelMapping=t,te(e),y()}},[f.langList]);const y=e=>{let t;if(e){try{typeof e=="string"?t=JSON.parse(e):t=e||{}}catch{t={}}a.current.i18n===!0&&(a.current._i18n=t._i18n||1,delete t._i18n)}const l={...t||a.current.valueCom},i=[],n={};if(a.current.disabledDelete){const s=Object.keys(a.current.langMapping)||[];for(let h=0,p=s.length;h<p;h++){const C=a.current.langMapping[s[h]]||{},m=C.value,fe=C.label,xe=l[m];m!==a.current.lang&&(n[m]=!0,i.push({label:fe,value:xe||""}))}}const c=Object.keys(l);for(let s=0,h=c.length;s<h;s++){const p=c[s],C=l[p];if(!n[p]&&p!==a.current.lang){const m=a.current.langMapping[p]||{};i.push({label:m.label||p,value:C||""})}}a.current.valueCom={...l},A(i),T(l)},B=e=>{let t={...e};if(f.value===void 0&&(a.current.valueCom={...t},T(t)),a.current.typeOutput==="string")try{a.current.i18n===!0&&(t._i18n=a.current._i18n||1),t=JSON.stringify(t)}catch{}O&&O(t)},ne=e=>{b[o]=e.target.value;const t={...b};B(t)},le=e=>{A([...e])},ae=(e,t)=>{const l=[],i=K.ArrayToObject("label",d);for(let n=0,c=x.length;n<c;n++){let s=x[n];typeof s=="object"&&(s=s.label),!i[s]&&s!==(I[o]?.label||o)&&l.push({label:s,value:s})}t(l)},se=()=>{D(!0)},re=e=>{if(e)return;D(!1);const t={};t[o]=b[o]||"";for(let l=0,i=d.length;l<i;l++){const n=d[l],c=a.current.langLabelMapping[n.label]?.value||n.label||"";c.trim()!==""&&(t[c]=n.value||"")}B(t)},ie=()=>u.jsxRuntimeExports.jsx("div",{className:"lang-key",children:u.jsxRuntimeExports.jsx(ve.default,{tipMaxWidth:"none",children:I[o]?.label||o})}),oe=r.useMemo(()=>u.jsxRuntimeExports.jsx("div",{className:"lang-list-icon",children:u.jsxRuntimeExports.jsx(ye.Internet,{})}),[]),ue=()=>{let e=`${g.$prefixCls}-input-lang-popover`;return N&&(e+=` ${N}`),Y&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-add`),_&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-delete`),e},ce=()=>{if(S===!0)return!0;const e=[];if(R){const t=typeof R=="object";for(let l=0,i=d.length;l<i;l++){const n=d[l].label||"",c=a.current.langLabelMapping[n]||{};t?e.push({[n]:R.indexOf(c.value||n)!==-1}):n.trim()!==""&&e.push({[n]:!0})}}return e},pe=(e,t)=>{const l={};return E&&(l.limitLength=E),l},de=()=>u.jsxRuntimeExports.jsx("div",{className:"input-lang-list",children:u.jsxRuntimeExports.jsx(me.MultiBox,{className:"input-lang-multi-box",size:v,disabled:ce(),value:d,onChange:le,fetchSuggestionsKey:ae,placeholderKey:G,placeholderValue:J||q,valueOtherProps:pe})}),ge=()=>{let e=`${g.$prefixCls}-input-lang`;return v&&(e+=` ${g.$prefixCls}-input-lang-${v}`),L&&(e+=` ${g.$prefixCls}-input-lang-error`),$&&(e+=` ${$}`),e};return u.jsxRuntimeExports.jsxs("div",{className:ge(),style:z,ref:P,children:[u.jsxRuntimeExports.jsx(je.Popover,{placement:"bottom-end",visible:Z,content:de(),onVisibleChange:re,overlayClassName:ue(),maxWidth:"none",overlayInnerStyle:{minWidth:"440px",width:`${P.current?.offsetWidth}px`},children:u.jsxRuntimeExports.jsx(be.TextField,{className:"input-lang-text-field",size:v,error:L,disabled:S,disabledTooltip:X,required:U,label:H,labelTooltip:F,placeholder:q,value:b[o]||"",rightIcon:oe,addonBefore:ie(),hideErrorDom:!0,limitLength:E,onClickIcon:se,onChange:ne})}),u.jsxRuntimeExports.jsx(he.default,{className:"input-lang-error-text",error:L,helperText:Q,hideErrorDom:w})]})};exports.InputLang=W;exports.default=W;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const u=require("../_virtual/jsx-runtime.js"),r=require("react"),be=require("../TextField/index.js"),he=require("../HelperText/index.js"),me=require("../MultiBox/index.js"),ve=require("../AutoTips/index.js"),je=require("../Popover/index.js"),ye=require("../node_modules/@para-ui/icons/Internet/index.js"),K=require("../Utils/snack-kit-shims.js"),g=require("../GlobalContext/constant.js"),Ce=require("../Hooks/useGlobalProps.js");;/* empty css            */const W=f=>{const{className:$,style:z,label:H,labelTooltip:F,size:v="large",placeholder:q,placeholderKey:G,placeholderValue:J,error:L=!1,hideErrorDom:w,helperText:Q="",required:U=!1,popoverClassName:S,value:M,onChange:N,langList:x=["zh","en"],limitLength:E,disabled:O=!1,disabledTooltip:X,defaultLang:j,disabledDelete:_,disabledAdd:Y,disabledKey:R,typeOutput:V="object",i18n:k}=Ce.default(f,"InputLang"),[Z,D]=r.useState(!1),[o,ee]=r.useState(K.GetLanguage()||"zh"),[I,te]=r.useState({}),[b,T]=r.useState({}),[d,A]=r.useState([]),a=r.useRef({lang:o,valueCom:b,langMapping:{},langLabelMapping:{}}),P=r.useRef(null);a.current.lang=o,a.current.disabledDelete=_,a.current.typeOutput=V,a.current.i18n=V==="string"&&k===void 0?!0:k,r.useEffect(()=>{f.defaultValue!==void 0&&y(f.defaultValue)},[]),r.useEffect(()=>{M!==void 0&&y(M)},[M]),r.useEffect(()=>{j!==void 0&&(ee(j),a.current.lang=j,y())},[j]),r.useEffect(()=>{if(x){const e={},t={};for(let l=0,i=x.length;l<i;l++){const n=x[l];typeof n=="string"?(e[n]={label:n,value:n},t[n]={label:n,value:n}):(e[n.value]=n,t[n.label]=n)}a.current.langMapping=e,a.current.langLabelMapping=t,te(e),y()}},[f.langList]);const y=e=>{let t;if(e){try{typeof e=="string"?t=JSON.parse(e):t=e||{}}catch{t={}}a.current.i18n===!0&&(a.current._i18n=t._i18n||1,delete t._i18n)}const l={...t||a.current.valueCom},i=[],n={};if(a.current.disabledDelete){const s=Object.keys(a.current.langMapping)||[];for(let h=0,p=s.length;h<p;h++){const C=a.current.langMapping[s[h]]||{},m=C.value,fe=C.label,xe=l[m];m!==a.current.lang&&(n[m]=!0,i.push({label:fe,value:xe||""}))}}const c=Object.keys(l);for(let s=0,h=c.length;s<h;s++){const p=c[s],C=l[p];if(!n[p]&&p!==a.current.lang){const m=a.current.langMapping[p]||{};i.push({label:m.label||p,value:C||""})}}a.current.valueCom={...l},A(i),T(l)},B=e=>{let t={...e};if(f.value===void 0&&(a.current.valueCom={...t},T(t)),a.current.typeOutput==="string")try{a.current.i18n===!0&&(t._i18n=String(a.current._i18n||1)),t=JSON.stringify(t)}catch{}N&&N(t)},ne=e=>{b[o]=e.target.value;const t={...b};B(t)},le=e=>{A([...e])},ae=(e,t)=>{const l=[],i=K.ArrayToObject("label",d);for(let n=0,c=x.length;n<c;n++){let s=x[n];typeof s=="object"&&(s=s.label),!i[s]&&s!==(I[o]?.label||o)&&l.push({label:s,value:s})}t(l)},se=()=>{D(!0)},re=e=>{if(e)return;D(!1);const t={};t[o]=b[o]||"";for(let l=0,i=d.length;l<i;l++){const n=d[l],c=a.current.langLabelMapping[n.label]?.value||n.label||"";c.trim()!==""&&(t[c]=n.value||"")}B(t)},ie=()=>u.jsxRuntimeExports.jsx("div",{className:"lang-key",children:u.jsxRuntimeExports.jsx(ve.default,{tipMaxWidth:"none",children:I[o]?.label||o})}),oe=r.useMemo(()=>u.jsxRuntimeExports.jsx("div",{className:"lang-list-icon",children:u.jsxRuntimeExports.jsx(ye.Internet,{})}),[]),ue=()=>{let e=`${g.$prefixCls}-input-lang-popover`;return S&&(e+=` ${S}`),Y&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-add`),_&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-delete`),e},ce=()=>{if(O===!0)return!0;const e=[];if(R){const t=typeof R=="object";for(let l=0,i=d.length;l<i;l++){const n=d[l].label||"",c=a.current.langLabelMapping[n]||{};t?e.push({[n]:R.indexOf(c.value||n)!==-1}):n.trim()!==""&&e.push({[n]:!0})}}return e},pe=(e,t)=>{const l={};return E&&(l.limitLength=E),l},de=()=>u.jsxRuntimeExports.jsx("div",{className:"input-lang-list",children:u.jsxRuntimeExports.jsx(me.MultiBox,{className:"input-lang-multi-box",size:v,disabled:ce(),value:d,onChange:le,fetchSuggestionsKey:ae,placeholderKey:G,placeholderValue:J||q,valueOtherProps:pe})}),ge=()=>{let e=`${g.$prefixCls}-input-lang`;return v&&(e+=` ${g.$prefixCls}-input-lang-${v}`),L&&(e+=` ${g.$prefixCls}-input-lang-error`),$&&(e+=` ${$}`),e};return u.jsxRuntimeExports.jsxs("div",{className:ge(),style:z,ref:P,children:[u.jsxRuntimeExports.jsx(je.Popover,{placement:"bottom-end",visible:Z,content:de(),onVisibleChange:re,overlayClassName:ue(),maxWidth:"none",overlayInnerStyle:{minWidth:"440px",width:`${P.current?.offsetWidth}px`},children:u.jsxRuntimeExports.jsx(be.TextField,{className:"input-lang-text-field",size:v,error:L,disabled:O,disabledTooltip:X,required:U,label:H,labelTooltip:F,placeholder:q,value:b[o]||"",rightIcon:oe,addonBefore:ie(),hideErrorDom:!0,limitLength:E,onClickIcon:se,onChange:ne})}),u.jsxRuntimeExports.jsx(he.default,{className:"input-lang-error-text",error:L,helperText:Q,hideErrorDom:w})]})};exports.InputLang=W;exports.default=W;
 //# sourceMappingURL=index.js.map