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

package/es/FormItem/compoments/defaultCompoments/index.d.ts

@@ -1,13 +1,13 @@
-import { FC } from 'react';
+import { FC, ReactNode } from 'react';
 interface DefaultCompomentsProps {
-    moudle: any;
+    moudle: (props: object) => ReactNode;
     error: boolean;
     placeholder: string;
-    defaultValue: any;
+    defaultValue: unknown;
     disabled?: boolean;
-    onChange: (e: any) => void;
+    onChange: (e: unknown) => void;
     inputProps?: {
-        [name: string]: any;
+        [name: string]: unknown;
     };
 }
 /**

package/es/FormItem/compoments/defaultCompoments/index.js

@@ -1,22 +1,23 @@
+import { j as r } from "../../../_virtual/jsx-runtime.js";
 import l from "react";
-const h = (u) => {
-  const { error: r, placeholder: n, defaultValue: e, disabled: s, onChange: d, inputProps: c, moudle: f } = u, [m, t] = l.useState(e);
+const g = (u) => {
+  const { error: n, placeholder: s, defaultValue: e, disabled: d, onChange: m, inputProps: c, moudle: f } = u, [p, t] = l.useState(e);
   return l.useEffect(() => {
     t(e);
-  }, [e]), f({
-    error: r,
-    placeholder: n,
-    value: m,
-    disabled: s,
+  }, [e]), /* @__PURE__ */ r.jsx(r.Fragment, { children: f({
+    error: n,
+    placeholder: s,
+    value: p,
+    disabled: d,
     hideErrorDom: null,
     ...c,
     onChange: (a) => {
-      const o = a?.target?.value || a;
-      t(o), d(o);
+      const o = a?.target?.value ?? a;
+      t(o), m(o);
     }
-  });
+  }) });
 };
 export {
-  h as default
+  g as default
 };
 //# sourceMappingURL=index.js.map

package/es/FormItem/compoments/formCheckboxGroup/index.d.ts

@@ -1,8 +1,8 @@
 import { FC } from 'react';
 import { CheckboxGroupProps } from '../../../CheckboxGroup';
 export interface FormCheckboxGroupProps extends CheckboxGroupProps {
-    defaultValue?: any[];
-    change?: (value: any) => any;
+    defaultValue?: (string | number)[];
+    change?: (value: unknown) => unknown;
 }
 declare const FormCheckboxGroup: FC<FormCheckboxGroupProps>;
 export default FormCheckboxGroup;

package/es/FormItem/compoments/formFile/index.js

@@ -9,12 +9,12 @@ import y from "../../../GlobalContext/useFormatMessage.js";
 import C from "../../lang/index.js";
 import './index.css';/* empty css           */
 const B = (m) => {
-  const { fileType: o = "", defaultValue: t, onChange: p, disabled: l, buttonLabel: u, inputProps: d, buttonProps: x } = m, j = y("FormItem", C), s = c.useRef(null), h = () => {
-    s.current?.click();
+  const { fileType: o = "", defaultValue: t, onChange: p, disabled: l, buttonLabel: u, inputProps: d, buttonProps: x } = m, j = y("FormItem", C), i = c.useRef(null), h = () => {
+    i.current?.click();
   }, f = (r) => {
-    const a = r !== void 0 ? r : s.current.files;
-    n(a), p && p(a), r === null && (s.current.value = null);
-  }, [i, n] = c.useState();
+    const a = r !== void 0 ? r : i.current?.files ?? null;
+    n(a), p && p(a), r === null && i.current && (i.current.value = "");
+  }, [s, n] = c.useState();
   return c.useEffect(() => {
     t && n(t);
   }, [t]), /* @__PURE__ */ e.jsxs("div", { className: "form-file", children: [
@@ -32,16 +32,16 @@ const B = (m) => {
       "input",
       {
         ...d,
-        ref: s,
+        ref: i,
         type: "file",
         onInput: () => f(),
         hidden: !0,
         accept: typeof o == "string" ? o : o.join(",")
       }
     ),
-    i && i[0] && /* @__PURE__ */ e.jsx("div", { className: `file-tips ${l && "file-tips-disabled" || ""}`, children: /* @__PURE__ */ e.jsxs("div", { className: "file-tips-item", children: [
+    s && s[0] && /* @__PURE__ */ e.jsx("div", { className: `file-tips ${l && "file-tips-disabled" || ""}`, children: /* @__PURE__ */ e.jsxs("div", { className: "file-tips-item", children: [
       /* @__PURE__ */ e.jsx(g, {}),
-      /* @__PURE__ */ e.jsx("span", { className: "file-tips-context", children: /* @__PURE__ */ e.jsx(b, { children: typeof i == "string" ? i : i[0].name }) }),
+      /* @__PURE__ */ e.jsx("span", { className: "file-tips-context", children: /* @__PURE__ */ e.jsx(b, { children: typeof s == "string" ? s : s[0].name }) }),
       !l && /* @__PURE__ */ e.jsx(F, { onClick: () => f(null) })
     ] }) })
   ] });

package/es/FormItem/compoments/formRadioGroup/index.d.ts

@@ -2,7 +2,7 @@ import { FC } from 'react';
 import { RadioGroupProps } from '../../../RadioGroup';
 export interface FormRadioGroupProps extends RadioGroupProps {
     defaultValue?: string;
-    change?: (value: any) => any;
+    change?: (value: unknown) => unknown;
 }
 declare const FormRadioGroup: FC<FormRadioGroupProps>;
 export default FormRadioGroup;

package/es/FormItem/compoments/formSelect/index.d.ts

@@ -8,7 +8,7 @@ export type FormSelectProps = Omit<SelectProps, 'value' | 'defaultValue' | 'onCh
     /**
      * 改变方法
      */
-    change?: (value: any) => any;
+    change?: (value: unknown) => unknown;
     /**
      * 绑定值
      */

package/es/FormItem/component.json

@@ -0,0 +1,171 @@
+{
+    "name": "FormItem",
+    "category": "Data Entry",
+    "description": "表单项,通常作 FieldForm 子组件使用,形成\"校验/收集值/提交\"链路。可独立用但脱离 FieldForm 时不会自动校验。需 FormItem 自渲染控件请用 InputType prop。",
+    "semantic": {
+        "intent": [
+            "字段包装",
+            "表单控制"
+        ],
+        "useCases": [
+            "表单字段",
+            "校验绑定",
+            "布局控制"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "error",
+        "validating"
+    ],
+    "idealProps": {
+        "name": {
+            "type": "string",
+            "description": "字段名（**仅 string，不支持 array 路径写法**）。需在 Form/FieldForm 上下文中保持唯一；不要传 `['user','address','city']`——会触发 TS2322。\n\n**字符串点路径协议**：`name` 可以写成 `'user.address.city'` 形式（TS 合法，不报错），但 FormItem 和 Form 均**不解析点路径**——表单聚合值是 `{ 'user.address.city': value }`（扁平 key，含字面量点），而**不是** `{ user: { address: { city: value } } }`（深度嵌套对象）。点路径字段可以正常传值、校验、回填，仅聚合 key 保持原字符串。这与 antd / rc-field-form 的 `name=['a','b','c']` 深度路径解析行为**不同**——本组件不做路径解析，只做 key 直传。若业务提交需要深度嵌套对象，在提交前自行将扁平结果转换（如 `{ 'user.address.city': 'Beijing' }` → `{ user: { address: { city: 'Beijing' } } }`），或改用 `FieldForm.Item`（支持 `name={['user','address','city']}` 数组路径）。"
+        },
+        "label": {
+            "type": "string | (props: FormItemProps) => ReactNode",
+            "description": "标签文案；可传字符串或函数式渲染。**不支持 null**——传 label={null} 会触发 TS2322。要『无 label』请使用 hideLabel。"
+        },
+        "hideLabel": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏 label 区块（连同 label 占位一起去掉）。这是『无 label 字段』的正确写法。"
+        },
+        "rules": {
+            "type": "ruleType",
+            "description": "校验规则。**这是单个对象不是数组**（与 antd 的 rules: Rule[] 不同）。结构为 `{ validate: { required, maxlength, minLength, pattern, min, max, disOnlySpace, [自定义key]: fn }, message?: { required: '...', pattern: '...' } }`。 message 与 validate 中的 key 一一对应。校验函数签名 `(item, val, intl) => true | string`：返回 true 表示通过、返回字符串表示报错文案。**⚠️ 重要：脱离 FieldForm 独立使用时，rules 不会自动触发校验**——rules 仅渲染必填红星等视觉提示，required/pattern 等不会在 children 失焦/变更时执行；完整校验链路必须配合 FieldForm 上下文。"
+        },
+        "InputType": {
+            "type": "'default' | 'select' | 'switch' | 'textarea' | 'number' | 'file' | 'radioGroup' | 'checkGroup' | 'comboSelect' | ReactNode | FC",
+            "description": "FormItem 自动渲染输入控件的类型；不传 children 时按此类型渲染对应 paraui 组件。传 children 时 InputType 不生效（外部受控）。"
+        },
+        "inputProps": {
+            "type": "Record<string, any>",
+            "description": "InputType 渲染的内部控件透传 props（如 placeholder、options 等）。"
+        },
+        "type": {
+            "type": "'horizontal' | 'vertical'",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "'horizontal'",
+            "description": "label 与表单项的横纵布局。"
+        },
+        "labelWidth": {
+            "type": "number",
+            "description": "label 区块宽度（仅 type='vertical' 时生效）。"
+        },
+        "tips": {
+            "type": "string",
+            "description": "label 旁的 tooltip 提示文案。"
+        },
+        "hideError": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏校验错误提示（不影响校验逻辑本身）。"
+        },
+        "defaultValue": {
+            "type": "any",
+            "description": "默认值。会被 FieldForm 的回填数据 backData 覆盖。"
+        },
+        "disabled": {
+            "type": "boolean",
+            "description": "InputType 渲染的控件是否禁用（仅自动渲染场景生效）。"
+        },
+        "change": {
+            "type": "(value: any) => void",
+            "description": "值变化回调（仅 InputType 自动渲染场景由内部 ItemType 触发；外部 children 受控时不会自动触发——需自己监听）。"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "自定义渲染输入控件——FormItem **不会自动注入 value/onChange**，使用方需自行受控。传了 children 时 InputType 自动渲染分支会被跳过。"
+        },
+        "errorMessage": {
+            "type": "string",
+            "description": "**脱离 FieldForm 独立使用时的受控错误文案（父组件接管 pattern）**。独立使用时 FormItem 不会自动触发 rules 校验——rules 仅渲染必填红星。错误文案必须由父组件主动驱动：① 父组件自行执行校验逻辑（如在 onBlur 中判断）；② 把校验结果写入 `errorMessage` prop（非空字符串 → 显示错误外壳；`''`/`null`/`undefined` → 清除错误状态）。不要同时传 `error` 或 `helperText`——独立使用场景统一用 `errorMessage`。"
+        },
+        "hide": {
+            "type": "boolean",
+            "description": "是否隐藏该表单项（src/FormItem/index.tsx:109 interface 实证）。hide=true 时 FormItem 不渲染（不占位），且 form.current.check() 和 form.current.getValidValues() 会跳过该字段。**与 CSS display:none 不同**——hide=true 时字段值不参与校验也不出现在提交结果中"
+        },
+        "className": {
+            "type": "string",
+            "description": "表单项容器自定义类名（src/FormItem/index.tsx:170 interface 实证）"
+        },
+        "itemType": {
+            "type": "'default' | 'select' | 'switch' | 'textarea' | 'number' | 'file' | 'radioGroup' | 'checkGroup' | 'comboSelect' | ReactNode | FC",
+            "description": "InputType 的别名（src/FormItem/index.tsx:74 interface 实证：itemType 与 InputType 同义，src 内部两者都检查）。**推荐用 InputType**——itemType 是历史命名，两者功能完全相同"
+        }
+    },
+    "do": [
+        "把 FormItem 作为 FieldForm 的子组件使用——形成完整的校验 + 提交链路",
+        "字段名仅传 string；嵌套字段在 FieldForm 层面用 schema 表达",
+        "校验规则用 paraui 自有 schema：`{ validate: { required: true, minLength: 8 }, message: { required: '请输入', minLength: '至少 8 位' } }`，不要传 `[{ required, message }]` 数组形式（会触发 TS2559）",
+        "无 label 字段使用 `hideLabel` 而不是 `label={null}`",
+        "需要自定义控件时把控件放在 children；需要自动渲染时用 InputType + inputProps",
+        "脱离 FieldForm 独立使用时:由父组件管理 children 的 value/onChange + 在父组件主动调用业务校验函数,把校验结果写入 FormItem 的 `errorMessage` prop 受控显示"
+    ],
+    "dont": [
+        "不要嵌套 FormItem",
+        "不要传 `name={['user', 'address', 'city']}`——name 仅 string",
+        "不要传 `label={null}`——会触发 TS2322；要无 label 用 `hideLabel`",
+        "不要按 antd 风格写 `rules={[{ required: true, message: '...' }]}`——会触发 TS2559；本组件 rules 是单对象 ruleType",
+        "不要假设 FormItem 自动给 children cloneElement 注入 value/onChange——本组件不做注入",
+        "不要期望 FormItem 在脱离 FieldForm 时自动触发 rules.validate.required 等校验——独立模式下 rules 仅作类型描述,业务校验需父组件主动驱动"
+    ],
+    "events": {
+        "change": {
+            "signature": "(value: any) => void",
+            "asyncSupported": false,
+            "examples": [
+                "change={(val) => setValue(val)} — 仅 InputType 自动渲染场景由内部 ItemType 触发；外部 children 受控时不会自动触发",
+                "InputType='select' 时 change 在用户选中选项时触发，value 为选中项的 value 字段值",
+                "InputType='switch' 时 change 在用户 toggle 时触发，value 为布尔值 true/false"
+            ],
+            "commonMistakes": [
+                "传了 children 还期望 change 自动触发——children 受控时 ItemType 不渲染，change 永不触发，需在 children 中自己监听",
+                "假设 change 签名与 onChange 相同是 (e) => void 原生事件——实际签名是 (value: any) => void，直接是值而非 event",
+                "脱离 FieldForm 独立使用时期望 change 携带字段名——change 只传 value，字段名需父组件通过 name 自行关联"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FormItem.name 只接受 string，不能传数组路径",
+            "wrong": "const fieldName: string[] = ['user', 'address']; <FormItem name={fieldName} /> // TS2322 string[] 不能赋给 string",
+            "right": "<FormItem name='user.address' /> // 点路径字符串是合法的 string，但不会被解析为嵌套对象，聚合 key 保持原字符串形态"
+        },
+        {
+            "issue": "rules 是单对象不是数组——antd 风格写法 rules={[{required}]} 触发 TS2559",
+            "wrong": "<FormItem name='email' rules={[{ required: true, message: '必填' }]} /> // TS2559: Type '...[]' has no properties in common with ruleType",
+            "right": "<FormItem name='email' rules={{ validate: { required: true }, message: { required: '必填' } }} />"
+        },
+        {
+            "issue": "label 不支持传 null，要无 label 应用 hideLabel",
+            "wrong": "<FormItem name='code' label={null} /> // TS2322: Type 'null' is not assignable to 'string | (props: FormItemProps) => ReactNode'",
+            "right": "<FormItem name='code' hideLabel /> // 正确隐藏 label 区块"
+        },
+        {
+            "issue": "InputType 和 itemType 同时存在时，src 优先取 InputType（itemType 是别名）",
+            "wrong": "// 同时传两个不同值，期望 itemType 生效\n<FormItem name='x' itemType='select' InputType='default' /> // InputType 优先，select 不生效",
+            "right": "// 统一用 InputType，itemType 是历史别名\n<FormItem name='x' InputType='select' />"
+        },
+        {
+            "issue": "select 子项的 list 字段用 value，radioGroup/checkGroup 用 name——混用导致选中后 change 不传值",
+            "wrong": "InputType='select' list={[{label: 'A', name: 'a'}]} // select 读 value 字段，name 被忽略",
+            "right": "InputType='select' list={[{label: 'A', value: 'a'}]} // 而 radioGroup/checkGroup 用 name 字段"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FormItem",
+        "adapter": null
+    }
+}

package/es/FormItem/index.d.ts

@@ -8,7 +8,7 @@ export type formInputType = 'checkGroup' | 'select' | 'radioGroup' | 'textarea'
  * 表单操作项的其他配置
  */
 interface inputProps {
-    [name: string]: any;
+    [name: string]: unknown;
 }
 /**
  * 校验规则
@@ -73,7 +73,7 @@ export interface FormItemProps {
     /**
      * 值改变传出
      */
-    change?: (value: any) => void;
+    change?: (value: unknown) => void;
     /**
      * 不显示 该选项
      */
@@ -114,7 +114,7 @@ export interface FormItemProps {
      * 回填数据
      */
     backData?: {
-        [name: string]: any;
+        [name: string]: unknown;
     };
     /**
      * 是否启用必填框，不允许输入纯空格
@@ -131,7 +131,7 @@ export interface FormItemProps {
     /**
      * 其他配置
      */
-    [name: string]: any;
+    [name: string]: unknown;
     /**
      * 自定义class
      */
@@ -140,7 +140,7 @@ export interface FormItemProps {
      * 默认值
      * 会被backData，回填数据替换
      */
-    defaultValue?: any;
+    defaultValue?: unknown;
     /**
      * 是否是paraui表单组件
      * */

package/es/FormItem/index.js

@@ -1,8 +1,8 @@
-import { j as r } from "../_virtual/jsx-runtime.js";
-import p from "react";
+import { j as e } from "../_virtual/jsx-runtime.js";
+import h from "react";
 import L from "./itemType.js";
 import R from "./errorTips.js";
-import h from "clsx";
+import p from "clsx";
 import k from "../Label/index.js";
 import { $prefixCls as c } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
@@ -30,51 +30,51 @@ const C = {
     backData: a = {},
     defaultValue: $,
     name: t,
-    hideError: y = !1,
+    hideError: j = !1,
     className: d = "",
-    labelProps: j,
+    labelProps: y,
     helperTextProps: T,
     requiredElement: E,
     disRequiredElement: N = !1
   } = l;
   a[t] === void 0 && (a[t] = $);
-  const m = p.useRef(), I = (e) => {
-    m.current && m.current(e);
-  }, g = (e) => s === "vertical" ? /* @__PURE__ */ r.jsx(
+  const m = h.useRef(), g = (r) => {
+    m.current && m.current(r);
+  }, I = (r) => s === "vertical" ? /* @__PURE__ */ e.jsx(
     "div",
     {
       className: `form-content-vertical form-content-vertical-${t}`,
       style: { width: `calc(100% - ${n}px)` },
-      children: e.children
+      children: r.children
     }
-  ) : e.children, q = p.useCallback(() => i ? typeof i == "string" ? i : i(l) : "", [i]), w = () => {
-    let e = `${c}-form-item ${c}-form-item-${t}`;
-    return d && (e += ` ${d}`), typeof o == "string" && C[o] && (e += ` ${c}-form-item-${o}`), e;
+  ) : /* @__PURE__ */ e.jsx(e.Fragment, { children: r.children }), q = h.useCallback(() => i ? typeof i == "string" ? i : i(l) : "", [i]), w = () => {
+    let r = `${c}-form-item ${c}-form-item-${t}`;
+    return d && (r += ` ${d}`), typeof o == "string" && C[o] && (r += ` ${c}-form-item-${o}`), r;
   };
-  return /* @__PURE__ */ r.jsxs("div", { className: w(), children: [
-    !v && /* @__PURE__ */ r.jsx(
+  return /* @__PURE__ */ e.jsxs("div", { className: w(), children: [
+    !v && /* @__PURE__ */ e.jsx(
       "div",
       {
-        className: h(`form-label form-label-${t}`, s === "vertical" && "form-label-vertical"),
+        className: p(`form-label form-label-${t}`, s === "vertical" && "form-label-vertical"),
         style: { width: s === "vertical" ? `${n}px` : "" },
-        children: /* @__PURE__ */ r.jsx(
+        children: /* @__PURE__ */ e.jsx(
           k,
           {
-            className: h("form-labe-text", f && "form-labe-text-hastips"),
+            className: p("form-labe-text", f && "form-labe-text-hastips"),
             label: q(),
             required: !!l?.rules?.validate?.required,
             tooltip: f,
             tooltipIcon: N ? "" : E,
-            ...j
+            ...y
           }
         )
       }
     ),
-    /* @__PURE__ */ r.jsxs(g, { children: [
-      /* @__PURE__ */ r.jsx("div", { className: `form-edit form-edit-${t}`, children: l.children ? l.children : /* @__PURE__ */ r.jsx(
+    /* @__PURE__ */ e.jsxs(I, { children: [
+      /* @__PURE__ */ e.jsx("div", { className: `form-edit form-edit-${t}`, children: l.children ? l.children : /* @__PURE__ */ e.jsx(
         L,
         {
-          setError: I,
+          setError: g,
           error: !!u,
           itemType: o,
           backData: a,
@@ -82,10 +82,10 @@ const C = {
           setValue: b
         }
       ) }),
-      !y && /* @__PURE__ */ r.jsx("div", { className: `form-error form-error-${t}`, children: /* @__PURE__ */ r.jsx(
+      !j && /* @__PURE__ */ e.jsx("div", { className: `form-error form-error-${t}`, children: /* @__PURE__ */ e.jsx(
         R,
         {
-          getSetError: (e) => m.current = e,
+          getSetError: (r) => m.current = r,
           helperTextProps: T,
           errorMessage: u
         }

package/es/FormItem/itemType.js

@@ -179,7 +179,7 @@ const Z = (u) => {
           x,
           {
             defaultValue: t[r] || "",
-            autocomplete: "off",
+            autoComplete: "off",
             error: m,
             placeholder: c,
             onChange: (e) => {