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

package/es/TextEditor/component.json

@@ -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
+    }
+}

package/es/TextEditor/index.d.ts

@@ -34,19 +34,19 @@ export interface UpLoadImgConfig {
     /** 5 * 1024(5kb) */
     base64LimitSize: number;
     /** 单个文件上传成功之后 */
-    onSuccess: (file: File, res: any) => void;
+    onSuccess: (file: File, res: unknown) => void;
     /** 单个文件上传失败 */
-    onFailed: (file: File, res: any) => void;
+    onFailed: (file: File, res: unknown) => void;
     /** 上传进度回调 */
     onProgress: (progress: number) => void;
     /** 上传之前触发 */
-    onBeforeUpload: (file: File) => any;
+    onBeforeUpload: (file: File) => unknown;
     /** 上传错误，或者触发 timeout 超时 */
-    onError: (file: File, err: any, res: any) => void;
+    onError: (file: File, err: unknown, res: unknown) => void;
     /** 用户自定义图片上传 */
     customUpload: (file: File, insertFn: InsertFnType) => void;
     /** 用户自定义图片插入 */
-    customInsert: (res: any, insertFn: InsertFnType) => void;
+    customInsert: (res: unknown, insertFn: InsertFnType) => void;
 }
 export type UpLoadVideoConfig = Omit<UpLoadImgConfig, 'base64LimitSize'>;
 export interface TextEditorProps extends HelperTextDetailProps {

package/es/TextField/component.json

@@ -0,0 +1,290 @@
+{
+    "name": "TextField",
+    "category": "Form",
+    "description": "用于文本输入的表单组件",
+    "semantic": {
+        "intent": [
+            "输入文本",
+            "搜索",
+            "密码输入",
+            "多行文本"
+        ],
+        "useCases": [
+            "表单填写",
+            "搜索栏",
+            "评论区",
+            "信息录入"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "standard": {
+            "meaning": "标准输入框"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "focus"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string | number",
+            "description": "受控模式：输入框的值。与 onChange 配合使用"
+        },
+        "defaultValue": {
+            "type": "string | number",
+            "description": "非受控模式：初始值（不传 value 时生效）"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(event: React.ChangeEvent<HTMLInputElement>) => void",
+            "description": "值变化回调。从 event.target.value 取新值"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "输入框标题"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "占位文本"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示错误状态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "辅助提示文本或错误信息（error=true 时显示红色）"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "text",
+                "password",
+                "number"
+            ],
+            "default": "text",
+            "description": "输入框类型。password 类型内置显示/隐藏切换图标"
+        },
+        "multiline": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否为多行文本域（textarea）"
+        },
+        "rows": {
+            "type": "number",
+            "default": 4,
+            "description": "多行文本域的行数（multiline=true 时生效）"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示清除按钮"
+        },
+        "limitLength": {
+            "type": "number",
+            "description": "最大字符长度限制(同步 api.ts 协议 A:**onBlur 失焦时**截断到 limitLength + 触发新 onChange,**输入阶段不阻断**;需实时阻断请用 onChange slice。同时在输入框右下渲染 current/limitLength 计数)"
+        },
+        "addonBefore": {
+            "type": "ReactNode",
+            "description": "前置内容（图标或文字）"
+        },
+        "addonAfter": {
+            "type": "ReactNode",
+            "description": "后置内容（图标或文字）"
+        },
+        "autoComplete": {
+            "type": "string",
+            "description": "浏览器自动填充控制。React 使用 camelCase 的 autoComplete（不是 autocomplete），对应 HTML autocomplete 属性。R5 §A1 升级：旧字段名 autocomplete 已废弃，必须使用 autoComplete。常用值：'off'=禁用自动填充；'on'=启用；'new-password'=禁用密码自动填充；'email'/'username' 等=按字段类型提示。❌ 错误：autocomplete='off'（旧写法，React 忽略）；✅ 正确：autoComplete='off'"
+        },
+        "autoFocus": {
+            "type": "boolean",
+            "description": "自动获得焦点"
+        },
+        "name": {
+            "type": "string",
+            "description": "input name 属性，表单提交时使用"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示 * 标记）"
+        },
+        "labelMode": {
+            "type": "enum",
+            "values": ["outside", "inside"],
+            "default": "outside",
+            "description": "标题位置:outside(默认 · 标题在输入框上方)/ inside(标题作 floating label 嵌在输入框内,空态时与 placeholder 视觉位置重叠 · 聚焦或有值时上浮至框顶部 · 详见 api.ts 协议 H)"
+        },
+        "rightIcon": {
+            "type": "ReactNode",
+            "description": "输入框内部右侧图标。**与 onClickIcon 自动联动**(协议 F):点击此图标会触发 onClickIcon 回调,无需额外配置 showRightIcon=true"
+        },
+        "showRightIcon": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示 rightIcon(默认 true · 仅在需要隐藏时传 false)"
+        },
+        "onClickIcon": {
+            "type": "function",
+            "signature": "(event: React.PointerEvent<HTMLSpanElement>) => void",
+            "description": "点击 rightIcon 区域回调。仅传 rightIcon 不传此 prop → 图标只装饰;两者配对使用语义清晰"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击清空按钮回调(配合 allowClear=true 使用)。受控模式下 onClear 触发后**还会自动触发 onChange('')**;推荐 onClear 内显式 setKeyword('') 作为兜底"
+        },
+        "onEnter": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "按下回车键回调(独立于 onKeydown · 仅在 keyCode 13 时触发,便于实现回车搜索)"
+        },
+        "fetchSuggestions": {
+            "type": "function",
+            "signature": "(val: string, cb: (data: any[]) => void) => void",
+            "description": "返回输入建议的方法(异步搜索 / 联想)。在 cb 回调中传入数据数组;数据元素可为对象(配 showSelectName 指定回填字段)或单值"
+        },
+        "renderSelectItem": {
+            "type": "function",
+            "signature": "(item: any) => ReactNode",
+            "description": "自定义下拉列表每项的渲染(例如显示 name + 部门组合)。**与 showSelectName 互不影响** — 此 prop 控制下拉显示,showSelectName 独立控制回填字段"
+        },
+        "showSelectName": {
+            "type": "string",
+            "default": "value",
+            "description": "选中下拉项后回填到输入框的字段名(默认取 item.value;若数据结构是 {name, ...} 则传 'name')。与 renderSelectItem 协同时:下拉显示由 renderSelectItem 自定义,回填字段由 showSelectName 独立控制"
+        },
+        "onSelect": {
+            "type": "function",
+            "signature": "(item: any) => void",
+            "description": "选择下拉项回调。item 类型即为 fetchSuggestions cb 传入的数据元素(业务自定义,需 cast)"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "default": false,
+            "description": "true=非错误态不渲染 helperText 占位行(节省垂直空间);false=都渲染(默认 · 保持表单各行高度一致);null=完全不渲染该 dom 节点"
+        }
+    },
+    "protocolSummary": {
+        "A_limitLength": "字符计数 + onBlur 失焦截断(**非实时阻断**),实时阻断改用 onChange slice",
+        "B_allowClear_addonAfter": "可共存 — allowClear 在框内右侧,addonAfter 在框外独立后缀盒,不重叠",
+        "C_rightSlot_order": "渲染顺序 allowClear → limitMemo → rightIcon(框内),addonAfter 在框外",
+        "D_multiline_eventType": "multiline=true 时 event.target 实际是 HTMLTextAreaElement(api 表声明 InputElement 是简化),业务 cast 即可 — 对 onChange/onKeyUp/onKeydown/onFocus/onBlur 五个事件一致适用",
+        "E_onClear_controlled": "受控 onClear 触发后会自动触发 onChange(''),推荐父层兜底 setState('')",
+        "F_rightIcon_onClickIcon": "传入 rightIcon 后点击自动触发 onClickIcon(无需 showRightIcon=true)",
+        "G_no_inputProps_passthrough": "**TextField 不支持 inputProps 透传** — 原生 HTML 属性(如 maxLength)需用组件显式 prop 或 onChange 控制",
+        "H_labelMode_inside": "inside 模式 = floating label:空态 label 在框中央 · 聚焦/有值时上浮至框顶 · 与 placeholder 空态视觉重叠"
+    },
+    "crossPropInteractions": [
+        "rightIcon + onClickIcon = 配对使用(自动联动)",
+        "allowClear + addonAfter = 完全可共存(框内 + 框外)",
+        "fetchSuggestions + renderSelectItem + showSelectName = 三件套协同(取数 + 自定义渲染 + 回填字段)",
+        "limitLength = 失焦截断 + 计数显示(实时阻断请用 onChange slice)",
+        "multiline=true + 所有 event = event.target 实际是 HTMLTextAreaElement(api 简化为 InputElement,需 cast 才能用 textarea 特性)"
+    ],
+    "commonMisconceptions": [
+        "❌ inputProps={{ maxLength: N }} 透传 — 不支持,改用 onChange slice",
+        "❌ limitLength 会实时阻断键入 — 实际是 onBlur 截断",
+        "❌ allowClear 与 addonAfter 不能共存 — 完全可以共存",
+        "❌ rightIcon 需要 showRightIcon=true 才显示 — 默认即 true",
+        "❌ labelMode='inside' 时同时传 label 和 placeholder — 空态视觉重叠,推荐二选一"
+    ],
+    "do": [
+        "使用 label 清晰描述输入内容",
+        "输入错误时提供 clear 的 helperText 提示",
+        "密码输入框应使用 type='password'",
+        "multiline=true 时 event.target 实际是 HTMLTextAreaElement，需要 cast：`(e.target as HTMLTextAreaElement).value`",
+        "受控模式下 onClear 触发后还会自动触发 onChange('')，推荐在 onClear 中显式 setState('') 兜底"
+    ],
+    "dont": [
+        "在没有 label 的情况下仅依赖 placeholder",
+        "在单行输入框中输入过长内容（应切换 multiline）",
+        "不要用 inputProps={{ maxLength: N }} 透传 HTML 属性——TextField 不支持 inputProps 透传，实时字数限制用 onChange slice",
+        "不要期望 limitLength 实时阻断键入——limitLength 是 onBlur 失焦后截断，输入阶段不拦截"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(event: React.ChangeEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式：onChange={(e) => setValue(e.target.value)}——从 event.target.value 取新值",
+                "multiline=true 时 event.target 实际是 HTMLTextAreaElement，需 cast：`(e.target as HTMLTextAreaElement).value`",
+                "与 limitLength 配合实时截断：onChange={(e) => setValue(e.target.value.slice(0, MAX_LEN))}"
+            ],
+            "commonMistakes": [
+                "假设 onChange 接收 value 字符串而非 React.ChangeEvent——与 antd Input 不同，这里签名是 event 对象，需 e.target.value 取值",
+                "multiline=true 时对 event.target 用 HTMLInputElement 方法（如 .selectionStart）——此时 event.target 是 HTMLTextAreaElement（src 实证：onChange 内部 cast 为 React.FocusEvent<HTMLInputElement>，但实际 target 是 textarea）",
+                "在 limitLength 场景只监听 onChange 而不处理 onBlur——limitLength 截断发生在 onBlur，onChange 阶段不截断",
+                "假设 onClear 点击后不触发 onChange——受控模式下点清空会先触发 onClear 再触发 onChange('')（src/TextField/index.tsx clickClean 函数实证）"
+            ]
+        },
+        "onEnter": {
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "按 Enter 键触发搜索：onEnter={(e) => handleSearch(e.currentTarget.value)}",
+                "回车提交表单：onEnter={() => formRef.current.check?.()}"
+            ],
+            "commonMistakes": [
+                "与 onKeydown 混淆——onEnter 只在 keyCode===13 时触发，相当于 onKeydown 的 Enter 子集；如需监听所有键，用 onKeydown",
+                "multiline=true 时期望 onEnter 换行——onEnter 总是触发，需业务侧自行判断是否阻止换行（e.preventDefault()）"
+            ]
+        },
+        "onBlur": {
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "失焦校验：onBlur={() => validate(value)}",
+                "limitLength 截断时机：onBlur 后组件自动截断并触发 onChange（src 实证 handValueLimit）"
+            ],
+            "commonMistakes": [
+                "在 onBlur 里读 e.target.value 期望得到截断后的值——onBlur 触发时截断还没完成，截断结果通过后续 onChange 回来"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名是 React.ChangeEvent<HTMLInputElement> 而非 (value: string)，直接传 setter 会报类型错误",
+            "wrong": "onChange={setValue}  // setValue: (v: string) => void，签名不匹配",
+            "right": "onChange={(e) => setValue(e.target.value)}"
+        },
+        {
+            "issue": "multiline=true 时 event.target 实际是 HTMLTextAreaElement，但 Props 声明为 HTMLInputElement",
+            "wrong": "onChange={(e) => { const len = e.target.selectionStart; }}  // selectionStart 在 multiline 时类型检查通过，但 cast 可能出错",
+            "right": "onChange={(e) => { if (multiline) { const ta = e.target as unknown as HTMLTextAreaElement; } else { const inp = e.target as HTMLInputElement; } }}"
+        },
+        {
+            "issue": "onKeydown（小写 d）不是 onKeyDown（驼峰 D），React 标准事件名不同",
+            "wrong": "onKeyDown={handleKey}  // React 标准 prop，TextField 不接受——组件封装的 prop 是 onKeydown",
+            "right": "onKeydown={handleKey}  // src/TextField/index.tsx TextFieldProps 接口定义的 prop 名是 onKeydown（小写 d）"
+        },
+        {
+            "issue": "autoComplete 必须驼峰（不是 autocomplete），否则 React 忽略",
+            "wrong": "autocomplete='off'  // HTML 属性小写写法，React 会警告并忽略",
+            "right": "autoComplete='off'  // src/TextField/index.tsx 实证：prop 名为 autoComplete（驼峰）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "TextField",
+        "adapter": null
+    }
+}

package/es/TextField/index.d.ts

@@ -91,8 +91,8 @@ export interface TextFieldProps extends HelperTextDetailProps {
     onSelect?: (item: Record<string, unknown>) => void;
     /** name */
     name?: string;
-    /** autocomplete */
-    autocomplete?: string;
+    /** 浏览器自动填充控制；React 要求 camelCase，对应 HTML autocomplete 属性 */
+    autoComplete?: string;
 }
 export declare const TextField: FunctionComponent<TextFieldProps>;
 export default TextField;