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

package/lib/Form/index.d.ts

@@ -11,6 +11,50 @@ type FormHtmlProps = FormHTMLAttributes<HTMLFormElement>;
  * 配置项项类型
  */
 export type configListProps = Array<FormItemProps>;
+/**
+ * form ref 暴露的命令式 API（Form-DEFECT-001 起公开导出，业务方可 `import { FormRefObject } from '@para-ui/core/Form'`）
+ */
+export interface FormRefObject {
+    /**
+     * 校验表单方法，校验成功返回表单的键值对；失败返回 false（src jsdoc 实证）
+     * @return {false | {[name: string]: unknown}}
+     */
+    check?: Function;
+    /**
+     * 存储所有表单item最后的配置，方便提交时做总的校验
+     */
+    items?: {
+        [name: string]: ItemTypeProps;
+    };
+    /**
+     * 所有值
+     */
+    values?: {
+        [name: string]: unknown;
+    };
+    /**
+     * 强制刷新表单状态方法
+     */
+    refreshForm?: (list: Array<FormItemProps> | '', bData?: {
+        [name: string]: unknown;
+    }) => void;
+    /**
+     * 对象数据集合
+     */
+    refData?: RefDataProps;
+    /**
+     * 获取生效项目的值对象，会过滤掉不显示或是不启用的项目的值
+     */
+    getValidValues?: Function;
+    /**
+     * 重置表单
+     */
+    reset?: Function;
+    /**
+     * 清空表单数据，允许清空单个
+     */
+    clear?: (name?: string | string[]) => void;
+}
 /**
  * form 表单组件属性
  * @typedef {object} FormProps
@@ -20,51 +64,10 @@ export interface FormProps {
      * form 表单对象存储关键数据和校验方法
      * @property {Function} check 表单校验方法
      * @property {configListProps} items 配置项，最后经过加工的合计
-     * @property {{ [name: string]: any }} values 已经保存的值的键值对
+     * @property {{ [name: string]: unknown }} values 已经保存的值的键值对
      * @property {Function} refreshForm 强制刷新表单状态
      */
-    form?: React.MutableRefObject<{
-        /**
-         * 校验表单方法，校验成功返回表单的键值对
-         * @return {false | {[name: string]: any}}
-         */
-        check?: Function;
-        /**
-         * 存储所有表单item最后的配置，方便提交时做总的校验
-         */
-        items?: {
-            [name: string]: ItemTypeProps;
-        };
-        /**
-         * 所有值
-         */
-        values?: {
-            [name: string]: any;
-        };
-        /**
-         * 强制刷新表单状态方法
-         */
-        refreshForm?: (list: Array<FormItemProps> | '', bData?: {
-            [name: string]: any;
-        }) => void;
-        /**
-         * 对象数据集合
-         */
-        refData?: RefDataProps;
-        /**
-         * 获取生效项目的值对象，会过滤掉不显示或是不启用的项目的值，
-         */
-        getValidValues?: Function;
-        /**
-         * 重置表单
-         */
-        reset?: Function;
-        /**
-         * 清空表单数据
-         * 允许清空单个
-         */
-        clear?: (name?: string | string[]) => void;
-    }>;
+    form?: React.MutableRefObject<FormRefObject>;
     /**
      * from 表单的默认属性
      */
@@ -76,19 +79,19 @@ export interface FormProps {
     /**
      * 获取表单的校验方法，会传出表单的校验方法
      */
-    getCheckForm?: (checkFrom: Function) => {};
+    getCheckForm?: (checkFrom: Function) => void;
     /**
      * 输入框内容改变传出
      * @param {string} name 表单项的name
      * @param {any} value 当前表单输入项修改的值
      */
-    onChange?: (name: string, value: any) => void;
+    onChange?: (name: string, value: unknown) => void;
     /**
      * 强制刷新配置
      * @param {Function} configHook 传出内部设置表单项，和回填参数的 hook方法
      */
     getForcedRefresh?: (setConfigHook: (configList: configListProps, bData?: {
-        [name: string]: any;
+        [name: string]: unknown;
     }) => void) => void;
     /**
      * 表单项的配置
@@ -98,7 +101,7 @@ export interface FormProps {
      * 回填数据
      */
     backData?: {
-        [name: string]: any;
+        [name: string]: unknown;
     };
     /**
      * 是否禁用
@@ -136,7 +139,7 @@ export interface FormProps {
 /**
  * form 存储各种参数的集合类型
  */
-interface RefDataProps {
+export interface RefDataProps {
     /**
      * 存储所有表单item最后的配置，方便提交时做总的校验
      */
@@ -159,7 +162,7 @@ interface RefDataProps {
      * 表单保存的值集合
      */
     allValues: {
-        [name: string]: any;
+        [name: string]: unknown;
     };
     /**
      * 最新配置信息

package/lib/Form/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const V=require("../_virtual/jsx-runtime.js"),D=require("@paraview/lib"),n=require("react"),T=require("../FormItem/index.js"),W=require("../FormItem/validateFunction.js"),w=require("../GlobalContext/constant.js"),B=require("../GlobalContext/useFormatMessage.js"),z=require("../FormItem/lang/index.js"),A=v=>{const P=B.default("FormItem",z.default),{className:C="",FormProps:N,requiredElement:p,disRequiredElement:M,configList:i,type:x,getCheckForm:f,backData:c,disabled:b,onChange:m,getForcedRefresh:g,labelProps:E,helperTextProps:F,form:d,labelWidth:R=60,disOnlySpace:q=!0}=v,h=n.useRef(c&&D.DeepClone(c)||{}),S=n.useRef(i),[u,k]=n.useState(i),[j,I]=n.useState(Math.random()),t=n.useRef({allItems:{},itemsCheckStatus:{},itemsCheckMessage:{},configList:i||[],allValues:c&&D.DeepClone(c)||{}}),L=(e,s)=>{if(s)for(const r in s)t.current.allValues[r]=s[r];k(e||u&&[...u])},a=(e,s,r)=>{switch(s){case"status":t.current.itemsCheckStatus[e]=r;break;case"message":t.current.itemsCheckMessage[e]=r;break;case"item":t.current.allItems[e]=r;break;case"initValue":t.current.allValues[e]=r;break;default:t.current.allValues[e]=r,m&&m(e,r);break}},y=()=>{let e=0;for(let s=0;s<t.current.configList.length;s++){const r=t.current.configList[s].name,l=t.current.allItems[r];if(l.disabled||l.hide||t.current.itemsCheckStatus[r]===!0)continue;if(t.current.itemsCheckStatus[r]===!1){e++;continue}const o=W.default(l,t.current.allValues[r],P);o&&(e++,typeof o=="string"&&(t.current.itemsCheckMessage[r]=o),l.setErrorMsg&&l.setErrorMsg(o))}return!e&&t.current.allValues},O=()=>{const e={};for(let s=0;s<t.current.configList.length;s++){const r=t.current.configList[s];!r.hide&&t.current.allValues[r.name]&&(e[r.name]=t.current.allValues[r.name])}return e},$=(e=!1,s)=>{if(!e||!s){if(t.current={allItems:{},itemsCheckStatus:{},itemsCheckMessage:{},configList:S.current||[],allValues:{}},h.current&&!e)for(const r in h.current)t.current.allValues[r]=h.current[r]}else typeof s=="string"?(a(s,"status",void 0),a(s,"message",""),a(s,"initValue",void 0)):s.forEach(r=>{a(r,"status",void 0),a(r,"message",""),a(r,"initValue",void 0)});k(S.current),I(Math.random())};n.useEffect(()=>{f&&f(y),g&&g(L)},[f,g]),n.useEffect(()=>{if(c)for(const e in c)t.current.allValues[e]=c[e];I(Math.random())},[c]),n.useEffect(()=>{k(i)},[i]),n.useEffect(()=>{t.current.configList=u||[]},[u]),n.useEffect(()=>{d&&(d.current={get refreshForm(){return L},get check(){return y},get items(){return t.current.allItems},get values(){return t.current.allValues},get refData(){return t.current},get getValidValues(){return O},get reset(){return $},get clear(){return e=>{$(!0,e)}}})},[d]);const _=n.useMemo(()=>V.jsxRuntimeExports.jsx("div",{className:`form-content ${C}`,children:u&&u.length>0&&u.map((e,s)=>(e.hide&&a(e.name,"item",e),!e.hide&&V.jsxRuntimeExports.jsx(T.default,{type:x,disabled:b,disOnlySpace:q,errorMessage:t.current.itemsCheckMessage[e.name],requiredElement:p,disRequiredElement:M,labelProps:E,helperTextProps:F,llabelWidth:R,...e,backData:t.current.allValues,setValue:a},`form-item-${s}-${j}`)))}),[C,u,m,j,R,x,b,q,p,M,E,F]);return V.jsxRuntimeExports.jsx("form",{...N,className:`${w.$prefixCls}-form`,children:_})};exports.default=A;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const V=require("../_virtual/jsx-runtime.js"),$=require("@snack-kit/lib"),n=require("react"),T=require("../FormItem/index.js"),W=require("../FormItem/validateFunction.js"),w=require("../GlobalContext/constant.js"),B=require("../GlobalContext/useFormatMessage.js"),z=require("../FormItem/lang/index.js"),A=v=>{const P=B.default("FormItem",z.default),{className:C="",FormProps:N,requiredElement:p,disRequiredElement:M,configList:i,type:b,getCheckForm:f,backData:c,disabled:x,onChange:m,getForcedRefresh:g,labelProps:E,helperTextProps:F,form:d,labelWidth:R=60,disOnlySpace:q=!0}=v,h=n.useRef(c&&$.DeepClone(c)||{}),S=n.useRef(i),[u,k]=n.useState(i),[j,I]=n.useState(Math.random()),t=n.useRef({allItems:{},itemsCheckStatus:{},itemsCheckMessage:{},configList:i||[],allValues:c&&$.DeepClone(c)||{}}),L=(e,s)=>{if(s)for(const r in s)t.current.allValues[r]=s[r];k(e||u&&[...u])},a=(e,s,r)=>{switch(s){case"status":t.current.itemsCheckStatus[e]=r;break;case"message":t.current.itemsCheckMessage[e]=r;break;case"item":t.current.allItems[e]=r;break;case"initValue":t.current.allValues[e]=r;break;default:t.current.allValues[e]=r,m&&m(e,r);break}},y=()=>{let e=0;for(let s=0;s<t.current.configList.length;s++){const r=t.current.configList[s].name,l=t.current.allItems[r];if(l.disabled||l.hide||t.current.itemsCheckStatus[r]===!0)continue;if(t.current.itemsCheckStatus[r]===!1){e++;continue}const o=W.default(l,t.current.allValues[r],P);o&&(e++,typeof o=="string"&&(t.current.itemsCheckMessage[r]=o),l.setErrorMsg&&l.setErrorMsg(o))}return!e&&t.current.allValues},O=()=>{const e={};for(let s=0;s<t.current.configList.length;s++){const r=t.current.configList[s];!r.hide&&t.current.allValues[r.name]&&(e[r.name]=t.current.allValues[r.name])}return e},D=(e=!1,s)=>{if(!e||!s){if(t.current={allItems:{},itemsCheckStatus:{},itemsCheckMessage:{},configList:S.current||[],allValues:{}},h.current&&!e)for(const r in h.current)t.current.allValues[r]=h.current[r]}else typeof s=="string"?(a(s,"status",void 0),a(s,"message",""),a(s,"initValue",void 0)):s.forEach(r=>{a(r,"status",void 0),a(r,"message",""),a(r,"initValue",void 0)});k(S.current),I(Math.random())};n.useEffect(()=>{f&&f(y),g&&g(L)},[f,g]),n.useEffect(()=>{if(c)for(const e in c)t.current.allValues[e]=c[e];I(Math.random())},[c]),n.useEffect(()=>{k(i)},[i]),n.useEffect(()=>{t.current.configList=u||[]},[u]),n.useEffect(()=>{d&&(d.current={get refreshForm(){return L},get check(){return y},get items(){return t.current.allItems},get values(){return t.current.allValues},get refData(){return t.current},get getValidValues(){return O},get reset(){return D},get clear(){return e=>{D(!0,e)}}})},[d]);const _=n.useMemo(()=>V.jsxRuntimeExports.jsx("div",{className:`form-content ${C}`,children:u&&u.length>0&&u.map((e,s)=>(e.hide&&a(e.name,"item",e),!e.hide&&V.jsxRuntimeExports.jsx(T.default,{type:b,disabled:x,disOnlySpace:q,errorMessage:t.current.itemsCheckMessage[e.name],requiredElement:p,disRequiredElement:M,labelProps:E,helperTextProps:F,llabelWidth:R,...e,backData:t.current.allValues,setValue:a},`form-item-${s}-${j}`)))}),[C,u,m,j,R,b,x,q,p,M,E,F]);return V.jsxRuntimeExports.jsx("form",{...N,className:`${w.$prefixCls}-form`,children:_})};exports.default=A;
 //# sourceMappingURL=index.js.map

package/lib/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/lib/FormItem/compoments/defaultCompoments/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const o=require("react"),g=a=>{const{error:r,placeholder:n,defaultValue:e,disabled:s,onChange:d,inputProps:c,moudle:i}=a,[f,t]=o.useState(e);return o.useEffect(()=>{t(e)},[e]),i({error:r,placeholder:n,value:f,disabled:s,hideErrorDom:null,...c,onChange:u=>{const l=u?.target?.value||u;t(l),d(l)}})};exports.default=g;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const o=require("../../../_virtual/jsx-runtime.js"),s=require("react"),f=l=>{const{error:n,placeholder:a,defaultValue:e,disabled:i,onChange:c,inputProps:d,moudle:m}=l,[p,t]=s.useState(e);return s.useEffect(()=>{t(e)},[e]),o.jsxRuntimeExports.jsx(o.jsxRuntimeExports.Fragment,{children:m({error:n,placeholder:a,value:p,disabled:i,hideErrorDom:null,...d,onChange:u=>{const r=u?.target?.value??u;t(r),c(r)}})})};exports.default=f;
 //# sourceMappingURL=index.js.map

package/lib/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/lib/FormItem/compoments/formFile/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../../../_virtual/jsx-runtime.js"),u=require("react"),E=require("../../../node_modules/@para-ui/icons/Delete/index.js"),h=require("../../../node_modules/@para-ui/icons/LinkGroup/index.js"),q=require("../../../AutoTips/index.js"),F=require("../../../Button/index.js"),g=require("../../../node_modules/@para-ui/icons/UploadFile/index.js"),b=require("../../../GlobalContext/useFormatMessage.js"),v=require("../../lang/index.js");;/* empty css            */const y=a=>{const{fileType:n="",defaultValue:t,onChange:c,disabled:r,buttonLabel:p,inputProps:f,buttonProps:j}=a,m=b.default("FormItem",v.default),i=u.useRef(null),R=()=>{i.current?.click()},x=o=>{const d=o!==void 0?o:i.current.files;l(d),c&&c(d),o===null&&(i.current.value=null)},[s,l]=u.useState();return u.useEffect(()=>{t&&l(t)},[t]),e.jsxRuntimeExports.jsxs("div",{className:"form-file",children:[!r&&e.jsxRuntimeExports.jsx(F.Button,{variant:"outlined",...j,startIcon:e.jsxRuntimeExports.jsx(g.UploadFile,{}),onClick:R,children:p||m({id:"chooseFile"})}),e.jsxRuntimeExports.jsx("input",{...f,ref:i,type:"file",onInput:()=>x(),hidden:!0,accept:typeof n=="string"?n:n.join(",")}),s&&s[0]&&e.jsxRuntimeExports.jsx("div",{className:`file-tips ${r&&"file-tips-disabled"||""}`,children:e.jsxRuntimeExports.jsxs("div",{className:"file-tips-item",children:[e.jsxRuntimeExports.jsx(h.LinkGroup,{}),e.jsxRuntimeExports.jsx("span",{className:"file-tips-context",children:e.jsxRuntimeExports.jsx(q.default,{children:typeof s=="string"?s:s[0].name})}),!r&&e.jsxRuntimeExports.jsx(E.Delete,{onClick:()=>x(null)})]})})]})};exports.default=y;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../../../_virtual/jsx-runtime.js"),u=require("react"),E=require("../../../para-ui-core/node_modules/@para-ui/icons/Delete/index.js"),h=require("../../../para-ui-core/node_modules/@para-ui/icons/LinkGroup/index.js"),q=require("../../../AutoTips/index.js"),F=require("../../../Button/index.js"),g=require("../../../para-ui-core/node_modules/@para-ui/icons/UploadFile/index.js"),b=require("../../../GlobalContext/useFormatMessage.js"),v=require("../../lang/index.js");;/* empty css            */const y=a=>{const{fileType:n="",defaultValue:t,onChange:c,disabled:r,buttonLabel:p,inputProps:f,buttonProps:j}=a,m=b.default("FormItem",v.default),s=u.useRef(null),R=()=>{s.current?.click()},x=o=>{const d=o!==void 0?o:s.current?.files??null;l(d),c&&c(d),o===null&&s.current&&(s.current.value="")},[i,l]=u.useState();return u.useEffect(()=>{t&&l(t)},[t]),e.jsxRuntimeExports.jsxs("div",{className:"form-file",children:[!r&&e.jsxRuntimeExports.jsx(F.Button,{variant:"outlined",...j,startIcon:e.jsxRuntimeExports.jsx(g.UploadFile,{}),onClick:R,children:p||m({id:"chooseFile"})}),e.jsxRuntimeExports.jsx("input",{...f,ref:s,type:"file",onInput:()=>x(),hidden:!0,accept:typeof n=="string"?n:n.join(",")}),i&&i[0]&&e.jsxRuntimeExports.jsx("div",{className:`file-tips ${r&&"file-tips-disabled"||""}`,children:e.jsxRuntimeExports.jsxs("div",{className:"file-tips-item",children:[e.jsxRuntimeExports.jsx(h.LinkGroup,{}),e.jsxRuntimeExports.jsx("span",{className:"file-tips-context",children:e.jsxRuntimeExports.jsx(q.default,{children:typeof i=="string"?i:i[0].name})}),!r&&e.jsxRuntimeExports.jsx(E.Delete,{onClick:()=>x(null)})]})})]})};exports.default=y;
 //# sourceMappingURL=index.js.map

package/lib/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/lib/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/lib/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/lib/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/lib/FormItem/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),f=require("react"),w=require("./itemType.js"),I=require("./errorTips.js"),p=require("clsx"),L=require("../Label/index.js"),u=require("../GlobalContext/constant.js");;/* empty css            */const S={checkGroup:!0,select:!0,radioGroup:!0,textarea:!0,default:!0,switch:!0,number:!0,file:!0,comboSelect:!0},k=s=>{const{type:o="horizontal",labelWidth:c,tips:m,label:i,itemType:h,InputType:l=h,setValue:j,errorMessage:d,hideLabel:b,backData:a={},defaultValue:$,name:t,hideError:v=!1,className:x="",labelProps:E,helperTextProps:y,requiredElement:R,disRequiredElement:q=!1}=s;a[t]===void 0&&(a[t]=$);const n=f.useRef(),T=e=>{n.current&&n.current(e)},N=e=>o==="vertical"?r.jsxRuntimeExports.jsx("div",{className:`form-content-vertical form-content-vertical-${t}`,style:{width:`calc(100% - ${c}px)`},children:e.children}):e.children,g=f.useCallback(()=>i?typeof i=="string"?i:i(s):"",[i]),C=()=>{let e=`${u.$prefixCls}-form-item ${u.$prefixCls}-form-item-${t}`;return x&&(e+=` ${x}`),typeof l=="string"&&S[l]&&(e+=` ${u.$prefixCls}-form-item-${l}`),e};return r.jsxRuntimeExports.jsxs("div",{className:C(),children:[!b&&r.jsxRuntimeExports.jsx("div",{className:p(`form-label form-label-${t}`,o==="vertical"&&"form-label-vertical"),style:{width:o==="vertical"?`${c}px`:""},children:r.jsxRuntimeExports.jsx(L.default,{className:p("form-labe-text",m&&"form-labe-text-hastips"),label:g(),required:!!s?.rules?.validate?.required,tooltip:m,tooltipIcon:q?"":R,...E})}),r.jsxRuntimeExports.jsxs(N,{children:[r.jsxRuntimeExports.jsx("div",{className:`form-edit form-edit-${t}`,children:s.children?s.children:r.jsxRuntimeExports.jsx(w.default,{setError:T,error:!!d,itemType:l,backData:a,...s,setValue:j})}),!v&&r.jsxRuntimeExports.jsx("div",{className:`form-error form-error-${t}`,children:r.jsxRuntimeExports.jsx(I.default,{getSetError:e=>n.current=e,helperTextProps:y,errorMessage:d})})]})]})};exports.default=k;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),f=require("react"),w=require("./itemType.js"),I=require("./errorTips.js"),p=require("clsx"),L=require("../Label/index.js"),u=require("../GlobalContext/constant.js");;/* empty css            */const S={checkGroup:!0,select:!0,radioGroup:!0,textarea:!0,default:!0,switch:!0,number:!0,file:!0,comboSelect:!0},k=s=>{const{type:o="horizontal",labelWidth:c,tips:m,label:i,itemType:h,InputType:l=h,setValue:j,errorMessage:x,hideLabel:b,backData:n={},defaultValue:E,name:t,hideError:$=!1,className:d="",labelProps:v,helperTextProps:R,requiredElement:y,disRequiredElement:q=!1}=s;n[t]===void 0&&(n[t]=E);const a=f.useRef(),T=r=>{a.current&&a.current(r)},g=r=>o==="vertical"?e.jsxRuntimeExports.jsx("div",{className:`form-content-vertical form-content-vertical-${t}`,style:{width:`calc(100% - ${c}px)`},children:r.children}):e.jsxRuntimeExports.jsx(e.jsxRuntimeExports.Fragment,{children:r.children}),N=f.useCallback(()=>i?typeof i=="string"?i:i(s):"",[i]),C=()=>{let r=`${u.$prefixCls}-form-item ${u.$prefixCls}-form-item-${t}`;return d&&(r+=` ${d}`),typeof l=="string"&&S[l]&&(r+=` ${u.$prefixCls}-form-item-${l}`),r};return e.jsxRuntimeExports.jsxs("div",{className:C(),children:[!b&&e.jsxRuntimeExports.jsx("div",{className:p(`form-label form-label-${t}`,o==="vertical"&&"form-label-vertical"),style:{width:o==="vertical"?`${c}px`:""},children:e.jsxRuntimeExports.jsx(L.default,{className:p("form-labe-text",m&&"form-labe-text-hastips"),label:N(),required:!!s?.rules?.validate?.required,tooltip:m,tooltipIcon:q?"":y,...v})}),e.jsxRuntimeExports.jsxs(g,{children:[e.jsxRuntimeExports.jsx("div",{className:`form-edit form-edit-${t}`,children:s.children?s.children:e.jsxRuntimeExports.jsx(w.default,{setError:T,error:!!x,itemType:l,backData:n,...s,setValue:j})}),!$&&e.jsxRuntimeExports.jsx("div",{className:`form-error form-error-${t}`,children:e.jsxRuntimeExports.jsx(I.default,{getSetError:r=>a.current=r,helperTextProps:R,errorMessage:x})})]})]})};exports.default=k;
 //# sourceMappingURL=index.js.map

package/lib/FormItem/itemType.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const a=require("../_virtual/jsx-runtime.js"),h=require("react"),g=require("../TextField/index.js"),y=require("./compoments/formRadioGroup/index.js"),F=require("./compoments/formSelect/index.js"),$=require("./compoments/formCheckboxGroup/index.js"),v=require("./validateFunction.js"),_=require("../Switch/index.js"),w=require("./compoments/formFile/index.js"),I=require("../InputNumber/index.js"),M=require("../ComboSelect/index.js"),k=require("./compoments/defaultCompoments/index.js"),D=require("../GlobalContext/useFormatMessage.js"),G=require("./lang/index.js"),N=o=>{const{itemType:l,error:p,placeholder:E,label:q,inputProps:i,name:t,rules:V,setValue:u,setError:m,backData:r,disabled:s,change:j,isComponent:b}=o,C=D.default("FormItem",G.default),d=E||`${q}`,[c,R]=h.useState(!!p),n=e=>{if(u&&u(t,"value",e),j&&j(e),!V)return;const S={...o,setErrorMsg:x,setAndValidateValue:f},T=v.default(S,e,C)||"";x(T)},f=n,x=h.useCallback(e=>{m&&m(e),R(!!e),u&&u(t,"message",e)},[t,m,u]);return h.useEffect(()=>{const e={...o,setErrorMsg:x,setAndValidateValue:f};u&&u(t,"item",e)},[t,o,x,u]),(()=>{if(!b&&l&&typeof l!="string"&&(!l.name||l.name==="InputType")){const e={...o,setErrorMsg:x,setAndValidateValue:f};return l(e)}switch(l){case"file":return a.jsxRuntimeExports.jsx(w.default,{...o,defaultValue:r[t],disabled:s,onChange:e=>{n(e)}});case"switch":return r[t]===void 0&&u&&u(t,"initValue",!!r[t]),a.jsxRuntimeExports.jsx(_.Switch,{defaultChecked:!!r[t],onChange:e=>{n(e)},...i,disabled:s});case"checkGroup":return a.jsxRuntimeExports.jsx($.default,{error:c,defaultValue:r[t],change:e=>{n(e)},list:o.list,...i,disabled:s});case"select":return a.jsxRuntimeExports.jsx(F.default,{placeholder:d,defaultValue:r[t],error:c,change:e=>{n(e)},list:o.list,disabled:s,...i});case"radioGroup":return a.jsxRuntimeExports.jsx(y.default,{error:c,defaultValue:r[t],change:e=>{n(e)},list:o.list,disabled:s,...i});case"textarea":return a.jsxRuntimeExports.jsx(g.TextField,{error:c,placeholder:d,defaultValue:r[t]||"",disabled:s,multiline:!0,rows:3,name:t,hideErrorDom:null,onChange:e=>{n(e.target.value)},...i});case"number":return a.jsxRuntimeExports.jsx(I.InputNumber,{error:c,placeholder:d,defaultValue:r[t],disabled:s,name:t,hideErrorDom:null,onChange:e=>{n(e)},...i});case"comboSelect":return a.jsxRuntimeExports.jsx(M.ComboSelect,{error:c,placeholder:d,defaultValue:r[t],disabled:s,onChange:e=>{n(e)},...i});default:return l&&typeof l!="string"?a.jsxRuntimeExports.jsx(k.default,{moudle:l,error:c,placeholder:d,defaultValue:r[t],disabled:s,onChange:e=>{n(e)},inputProps:i}):a.jsxRuntimeExports.jsx(g.TextField,{defaultValue:r[t]||"",autocomplete:"off",error:c,placeholder:d,onChange:e=>{n(e.target.value)},name:t,hideErrorDom:null,disabled:s,...i})}})()};exports.default=N;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const a=require("../_virtual/jsx-runtime.js"),h=require("react"),g=require("../TextField/index.js"),y=require("./compoments/formRadioGroup/index.js"),F=require("./compoments/formSelect/index.js"),$=require("./compoments/formCheckboxGroup/index.js"),v=require("./validateFunction.js"),_=require("../Switch/index.js"),w=require("./compoments/formFile/index.js"),I=require("../InputNumber/index.js"),M=require("../ComboSelect/index.js"),k=require("./compoments/defaultCompoments/index.js"),D=require("../GlobalContext/useFormatMessage.js"),G=require("./lang/index.js"),N=o=>{const{itemType:l,error:p,placeholder:E,label:q,inputProps:i,name:t,rules:C,setValue:u,setError:m,backData:r,disabled:s,change:j,isComponent:V}=o,b=D.default("FormItem",G.default),d=E||`${q}`,[c,R]=h.useState(!!p),n=e=>{if(u&&u(t,"value",e),j&&j(e),!C)return;const S={...o,setErrorMsg:x,setAndValidateValue:f},T=v.default(S,e,b)||"";x(T)},f=n,x=h.useCallback(e=>{m&&m(e),R(!!e),u&&u(t,"message",e)},[t,m,u]);return h.useEffect(()=>{const e={...o,setErrorMsg:x,setAndValidateValue:f};u&&u(t,"item",e)},[t,o,x,u]),(()=>{if(!V&&l&&typeof l!="string"&&(!l.name||l.name==="InputType")){const e={...o,setErrorMsg:x,setAndValidateValue:f};return l(e)}switch(l){case"file":return a.jsxRuntimeExports.jsx(w.default,{...o,defaultValue:r[t],disabled:s,onChange:e=>{n(e)}});case"switch":return r[t]===void 0&&u&&u(t,"initValue",!!r[t]),a.jsxRuntimeExports.jsx(_.Switch,{defaultChecked:!!r[t],onChange:e=>{n(e)},...i,disabled:s});case"checkGroup":return a.jsxRuntimeExports.jsx($.default,{error:c,defaultValue:r[t],change:e=>{n(e)},list:o.list,...i,disabled:s});case"select":return a.jsxRuntimeExports.jsx(F.default,{placeholder:d,defaultValue:r[t],error:c,change:e=>{n(e)},list:o.list,disabled:s,...i});case"radioGroup":return a.jsxRuntimeExports.jsx(y.default,{error:c,defaultValue:r[t],change:e=>{n(e)},list:o.list,disabled:s,...i});case"textarea":return a.jsxRuntimeExports.jsx(g.TextField,{error:c,placeholder:d,defaultValue:r[t]||"",disabled:s,multiline:!0,rows:3,name:t,hideErrorDom:null,onChange:e=>{n(e.target.value)},...i});case"number":return a.jsxRuntimeExports.jsx(I.InputNumber,{error:c,placeholder:d,defaultValue:r[t],disabled:s,name:t,hideErrorDom:null,onChange:e=>{n(e)},...i});case"comboSelect":return a.jsxRuntimeExports.jsx(M.ComboSelect,{error:c,placeholder:d,defaultValue:r[t],disabled:s,onChange:e=>{n(e)},...i});default:return l&&typeof l!="string"?a.jsxRuntimeExports.jsx(k.default,{moudle:l,error:c,placeholder:d,defaultValue:r[t],disabled:s,onChange:e=>{n(e)},inputProps:i}):a.jsxRuntimeExports.jsx(g.TextField,{defaultValue:r[t]||"",autoComplete:"off",error:c,placeholder:d,onChange:e=>{n(e.target.value)},name:t,hideErrorDom:null,disabled:s,...i})}})()};exports.default=N;
 //# sourceMappingURL=itemType.js.map