v1.0

Author: bplok20010

README.md

@@ -2,42 +2,298 @@
 
 `npm install --save react-widget-form`
 
+```ts
+import {
+    Form,
+    FormItem,
+    NativeInput,
+    FormContext,
+    FormItemContext,
+    useForm,
+    useFormItem
+}  from 'react-widget-form'
+
+```
+
 ## Props
 
+### Types
+
+```ts
+type ValidateTriggerType = "change" | "blur";
+
+type Validator = (
+    value: any,
+    formValue: {}
+) => boolean | string | Error | Promise;
+
+type InvalidError = {
+    name: string;
+    message: any;
+};
+
+```
+
 ### Form
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| prefixCls | 组件CSS样式前缀 | string | rw-form |
-| className | 组件className属性 | string | - |
-| style | 组件style属性 | React.CSSProperties | - |
-| path2obj | 是否启用lodash.get、是否启用lodash.set来获取、设置formValue的值 | boolean | true |
-| defaultFormValue | 表单默认数据 | object | {} |
-| formValue | 表单数据`受控` | object |  |
-| validateDelay |- | number |  |
-| validateTrigger |- | string |  |
-| validateFieldsAndScroll |- | string |  |
-| showMessage |- | string |  |
-| component | 表单默认元素 | React.Element | form  |
-| rules | 验证规则 | object\|array\|function | null  |
-| labelWidth | 表单标签域宽度 | number\|string | - |
-| labelPosition | 表单标签域位置 | `top` `left` `right` | left |
-| alignItems | 表单控制表单项的alignItems的属性 | string | center |
-| inline | 行内表单模式 | function(value,e) | |
-| onSubmit | 只有当原生表单的onSubmit事件 | function(e) |  |
-| onChange | 按下回车的回调 | function(formValue, e) |  |
-| getFormItemInputProps | 自定义表单输入框控件的属性 | function(e) |  |
 
+```ts
+children: ((form: Form) => React.ReactNode) | React.ReactNode;
+prefixCls?: string;
+className?: string;
+style?: React.CSSProperties;
+path2obj?: boolean;
+defaultFormValue?: {};
+formValue?: {};
+getDefaultFieldValue?: (name: string) => any;
+renderFieldExtra?: (
+    component: FormItem,
+    name: string
+) => React.ReactNode;
+validators?: {
+    [name: string]: Validator | Validator[];
+};
+validateDelay?: number;
+validateTrigger?: ValidateTriggerType | ValidateTriggerType[];
+asyncTestDelay?: number;
+component?: React.ElementType;
+labelWidth?: string | number;
+labelClassName?: string;
+labelStyle?: React.CSSProperties;
+labelPosition?: "top" | "left";
+controlStyle?: React.CSSProperties;
+controlClassName?: string;
+clearErrorOnFocus?: boolean;
+inline?: boolean;
+onSubmit?: (e: React.SyntheticEvent) => void;
+onChange?: (formValue: {}) => void;
+getInputProps?: (component: FormItem, name: string) => {};
+```
 
 ### FormItem
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| - | - | - | - |
-| - | - | - |
 
-### NativeField
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| component | 接收`value` `onChange(e)`的控件 | React.Element | input |
+```ts
+children:
+    | ((props: FormItemChildProps, item: FormItem) => React.ReactNode)
+    | React.ReactNode;
+prefixCls?: string;
+name?: string;
+className?: string;
+style?: React.CSSProperties;
+validator?: Validator | Validator[];
+label?: React.ReactNode;
+labelFor?: string;
+labelWidth?: string | number;
+labelClassName?: string;
+labelStyle?: React.CSSProperties;
+labelPosition?: "top" | "left";
+controlStyle?: React.CSSProperties;
+controlClassName?: string;
+required?: boolean;
+requiredMessage?: string;
+clearErrorOnFocus?: boolean;
+normalize?: (value: any) => any;
+renderExtra?: (component: FormItem) => React.ReactNode;
+validateDelay?: number;
+validateTrigger?: ValidateTriggerType | ValidateTriggerType[];
+inline?: boolean;
+onChange?: (value: any) => void;
+onFocus?: (e: React.SyntheticEvent) => void;
+onBlur?: (e: React.SyntheticEvent) => void;
+```
+
+FormItem的会覆盖child的部分属性，覆盖属性如下:
+
+如果child的值发生改变必须要调用`onChange`来更新`Form`的状态，同样child发生`focus` `blur`最好也要调用`onFocus` `onBlur`
+
+- 【重要】 `onChange` 会触发 `validateTrigger` 及 Form的`onChange`
+- `onFocus` 会触发`clearErrorOnFocus`行为
+- `onBlur` 会触发`validateTrigger`行为
+
+```ts
+{
+    value: any;
+    onChange: (value: any) => void;
+    onFocus: (e: React.SyntheticEvent) => void;
+    onBlur: (e: React.SyntheticEvent) => void;
+    [propName: string]: any;
+}
+```
+
+由于FormItem的`onChange`接收的是一个值，所以不能直接使用原生表单组件或其他并非直接提供值的组件，例如：
+```jsx
+//这是错误的，onChange会将Event当作值赋值给formValue，可能导致预期不一致
+//ERROR
+<FormItem name="email">
+    <input type="text" />
+</FormItem>
+
+//正确写法一：
+<FormItem name="email">
+    {
+        (props) => {
+            
+            return <input {...props} type="text" onChange={e => props.onChange(e.target.value)} />
+        } 
+    }
+</FormItem>
+
+//正确写法二：
+function Input(props){
+    return <input {...props} type="text" onChange={e => props.onChange(e.target.value)} /> 
+}
+<FormItem name="email">
+    <Input />
+</FormItem>
+
+//正确写法三，使用NativeInput：
+<FormItem name="email">
+    <NativeInput component="input" />
+</FormItem>
+```
+
+
+### NativeInput
+
+```ts
+component: React.ElementType;
+onChange?: (value: any) => void;
+inputRef?: (dom: any) => void;
+[others: string]: any;
+```
+
+> others 会传递给component组件
+
+`NativeInput`是为了解决`onChange`返回事件的情况下做了简单的处理，封装代码如下:
+```js
+export default function NativeInput(props) {
+    const {
+        component: Component = "input",
+        value,
+        inputRef,
+        onChange,
+        ...others
+    } = props;
+
+    const onInputChange = e => {
+        const value = e.target.value;
+        onChange && onChange(value, e);
+    };
+
+    return (
+        <Component
+            ref={inputRef}
+            onChange={onInputChange}
+            value={value}
+            {...others}
+        />
+    );
+}
+
+```
+
+## Methods
+
+### Form
+```ts
+{
+    getValue(name: string): any;
+    setValue(
+       name: string,
+       value: any,
+       callback: (formValue: {}) => void
+    ): void;
+    setValues(formValue: {}, callback: (formValue: {}) => void): void;
+    hasError(name: string): boolean;
+    getError(name: string): any;
+    cleanError(name: string): void;
+    setError(name: string): void;
+    cleanErrors(): void;
+    setErrors(errors: {}): void;
+    isFieldValidating(name: string): boolean;
+    isValidating(): boolean;
+    validateField(
+        name: string,
+        callback: (errors: null | InvalidError[], formValue: {}) => void
+    ): boolean;
+    validate(
+        callback: (errors: null | InvalidError[], formValue: {}) => void
+    ): boolean;
+    validateAndScroll(
+        callback: (errors: null | InvalidError[], formValue: {}) => void
+    ): boolean;
+}
+```
+
+### FormItem 
+```ts
+{
+    getDOM(): any;
+    getForm(): Form;
+    getValue(): any;
+    setValue(value: any, callback: (formValue: {}) => void): void;
+    hasError(): boolean;
+    getError(): any;
+    cleanError(): void;
+    setError(message: any): void;
+    isValidating(): boolean;
+    validate(
+        callback: (errors: null | InvalidError[], formValue: {}) => void
+    ): boolean;
+}
+```
+
+## hooks
+
+- useForm
+- useFormItem
+
+
+## 基础样式
+
+```scss
+$form-item-cls: nex-form-item;
+
+.#{$form-item-cls} {
+    display: flex;
+
+    &-inline {
+        display: inline-flex;
+    }
+
+    &-label {
+        text-align: right;
+        flex: none;
+    }
+
+    &-top {
+        display: block;
+    }
+
+    &-top.#{$form-item-cls}-inline {
+        display: inline-block;
+        vertical-align: top;
+    }
+
+    &-top &-label {
+        text-align: left;
+        display: block;
+    }
+
+    &-control {
+        position: relative;
+        flex: 1;
+    }
+
+    &.is-required &-label:before {
+        content: "*";
+        display: inline-block;
+        margin-right: 4px;
+        font-family: SimSun;
+        color: red;
+    }
+}
+
+```
+
 
-其余属性传递给component。