Skip to content

Commit

Permalink
feat: update the api docs using typescript (#149)
Browse files Browse the repository at this point in the history
  • Loading branch information
@stkevintan @janryWang
stkevintan authored and janryWang committed Jul 9, 2019
1 parent b04d413 commit 5a9ea5a
Show file tree
Hide file tree
Showing 21 changed files with 372 additions and 299 deletions.
90 changes: 46 additions & 44 deletions docs/API/Field_React.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,21 @@ import {Field} from '@uform/react'

| 属性名称 | 属性描述 | 属性类型 | 默认值 | |
| ---- | ---- | ---- | --- | --- |
| default | 默认值 | any | | |
| enum | 枚举值，配置该值在默认情况下会显示Select形态，指定x-component会显示对应的组件形态 | `Array< String | {label:String,value:any}>` | \[] | |
| maxItems | 最大条目数，只有在type="array"时可以使用 | Number | | |
| minItems | 最小条目数，只有在type="array"时可以使用 | Number | | |
| name | 字段名称 | Object | {} | |
| required | 字段是否必填 | Boolean | false | |
| description | 字段描述，如果字符串字数超过30字或内容是ReactNode，会自动以pop形式展示 | String/React Node | '' | |
| type | 字段类型，具体类型枚举参考 [fields](https://github.com/alibaba/uform/tree/master/packages/antd/src/fields) | String | "" | |
| x-component | 字段UI组件，用于指定该字段应该用什么组件做渲染，具体类型枚举参考 [fields](https://github.com/alibaba/uform/tree/master/packages/antd/src/fields) | String | "" | |
| x-effect | 副作用事件绑定对象 | `Function(dispatch : Function) : { [eventName](...arguemtns)}` | | |
| x-index | 字段索引顺序 | Number | | |
| x-props | 字段UI组件属性，API请参考对应fusion next/ant design组件API | Object | {} | |
| x-props.editable | 字段是否可编辑 | Boolean | true | |
| x-render | 字段渲染函数 | `Function(fieldProps : FieldRenderProps){}` | | |
| x-rules | 字段校验规则 | `Object | Array<String | Object | Function> | String | Function` | | |
| default | 默认值 | `any` | | |
| enum | 枚举值，配置该值在默认情况下会显示Select形态，指定x-component会显示对应的组件形态 | `(string | { label: string, value:any })[]` | \[] | |
| maxItems | 最大条目数，只有在type="array"时可以使用 | `number` | | |
| minItems | 最小条目数，只有在type="array"时可以使用 | `number` | | |
| name | 字段名称 | `string` | '' | |
| required | 字段是否必填 | `boolean` | false | |
| description | 字段描述，如果字符串字数超过30字或内容是`JSX.Element`，会自动以pop形式展示 | `JSX.Element | string | null` | '' | |
| type | 字段类型，具体类型枚举参考 [fields](https://github.com/alibaba/uform/tree/master/packages/antd/src/fields) | `string` | | |
| x-component | 字段UI组件，用于指定该字段应该用什么组件做渲染，具体类型枚举参考 [fields](https://github.com/alibaba/uform/tree/master/packages/antd/src/fields) | `string` | | |
| x-effect | 副作用事件绑定对象 | `(dispatch: (eventName: string, ...params: any[]) => void) => void` | | |
| x-index | 字段索引顺序 | `number` | | |
| x-props | 字段UI组件属性，API请参考对应fusion next/ant design组件API | `{[key: string]: any}` | {} | |
| x-props.editable | 字段是否可编辑 | `boolean` | true | |
| x-render | 字段渲染函数 | `(fieldProps : IFieldProps) => string | JSX.Element | null` | | |
| x-rules | 字段校验规则 | `Rule | Rule[]` | | |

## x-rules详解

Expand Down Expand Up @@ -72,18 +72,19 @@ import {Field} from '@uform/react'

```typescript
interface IRuleDescription {
required?: boolean
message?: string,
pattern?: RegExp | string,
required? : boolean
message? : string,
pattern? : RegExp | string,
validator?: Validator,
format?: DefaultPatternRule
format? : DefaultPatternRule
}


type Validator = (value: any, rule: IRuleDescription, values: any, name: string) => string | Promise<string>

type DefaultPatternRule = 'url' | 'email' | 'ipv6' | 'ipv4' | 'number' | 'integer' | 'qq' | 'phone' | 'idcard' | 'taodomain' | 'money' | 'zh' | 'date' | 'zip'

type Rule = Validator | Array<Validator | IRuleDescription | DefaultPatternRule> | DefaultPatternRule | IRuleDescription
type Rule = Validator | DefaultPatternRule | IRuleDescription

//该回调函数直接return错误文案字符串代表响应错误，如果返回Promise对象，
//代表是异步校验，resolve错误文案的时候代表错误响应，resolve为空的时候代表正确响应
Expand All @@ -92,42 +93,43 @@ type Rule = Validator | Array<Validator | IRuleDescription | DefaultPatternRule>

## x-render详解

上面API List中可以看到x-render函数会接收FieldRenderProps类型的参数，下面是它的具体描述
上面API List中可以看到x-render函数会接收IFieldProps类型的参数，下面是它的具体描述

```typescript
type FieldRenderProps {
name : String,//字段数据路径
path : Array<String>,//字段数组数据路径
value : any,//字段值
errors : Array<String>,//字段错误消息集合
editable : Boolean | Function,//字段是否可编辑
locale : Object,//国际化文案对象
loading : Boolean,//是否处于加载态
schemaPath : Array<String>,//schema path,考虑到有些schema其实是不占数据路径的，所以这个路径是真实路径
getSchema(path) : Object, //根据路径获取schema
renderField(childKey : String,reactKey : String | Number) : ReactElement,//根据childKey渲染当前字段的子字段
renderComponent(props : Object) : ReactElement,//渲染当前字段的组件，对于x-render来说，可以借助它快速实现渲染包装功能
getOrderProperties() : Array<Object>,//根据properties里字段的x-index值求出排序后的properties
interface IFieldProps<V = any> {
name : string //字段数据路径
path : Array<string> //字段数组数据路径
value : V //字段值
errors : Array<string> //字段错误消息集合
editable : boolean | ((name:string) => boolean) //字段是否可编辑
locale : Locale //国际化文案对象
loading : boolean //是否处于加载态
schemaPath : Array<string> //schema path,考虑到有些schema其实是不占数据路径的，所以这个路径是真实路径
getSchema : (path: string) => ISchema //根据路径获取schema
renderField : (childKey: string, reactKey: string | number) => JSX.Element | string | null //根据childKey渲染当前字段的子字段
renderComponent : React.FunctionComponent<Partial<IFieldProps>> | undefined>,//渲染当前字段的组件，对于x-render来说，可以借助它快速实现渲染包装功能
getOrderProperties : () => Array<{schema: ISchema, key: number, path: string, name: string }>,//根据properties里字段的x-index值求出排序后的properties
mutators : Mutators,//数据操作对象
schema : Object
schema : ISchema
}

type Mutators {
change(value : any),//改变当前字段值
dispatch(name : String,payload : any),//触发effect事件
errors(errors : String | Array<String>,[...formatValue : String | Number]),//设置当前字段的错误消息
push(value : any),//对当前字段的值做push操作
interface Mutators<V = any> {
change: (value: V)=> void,//改变当前字段值
dispatch: (name: string, payload : any) => void,//触发effect事件
errors: (errors: string | Array<string>, ...formatValues: Array<string | number>) => void,//设置当前字段的错误消息
push(value: V),//对当前字段的值做push操作
pop(),//对当前字段的值做pop操作
insert(index : Number,value : any),//对当前字段的值做insert操作
remove(name : any),//对当前字段的值做remove操作
unshift(value : any),//对当前字段值做unshift操作
insert(index: number,value: V),//对当前字段的值做insert操作
remove(name : string),//对当前字段的值做remove操作
unshift(value : V),//对当前字段值做unshift操作
shift(),//对当前字段值做shift操作
move(fromIndex : Number, toIndex : Number)//对当前字段值做move操作
move(fromIndex: number, toIndex: number)//对当前字段值做move操作
}
```

## x-effect详解


x-effect属于一个非常高级的API，它是为了解决在某些场景，我们的数据联动不是基于字段的onChange事件来做的联动或者依赖onChange事件的其他参数来做的联动，它的解决方案是将dispatch函数给x-effect函数，然后让x-effect函数返回对应的事件处理器，然后再传递给具体的组件，比如：

```javascript
Expand Down
12 changes: 6 additions & 6 deletions docs/API/FormButtonGroup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ import { FormButtonGroup } from '@uform/next(antd)'

| 属性名称 | 属性描述 | 属性类型 | 默认值 |
| ---- | ---- | ---- | --- |
| align | 按钮内容的定位 | string | |
| itemStyle | 按钮组容器样式 | object | {} |
| offset | 按钮组容器左偏移距离 | number | |
| span | 按钮组容器宽度 | number | |
| sticky | 是否洗底 | boolean | false |
| style | 大容器样式 | object | {} |
| align | 按钮内容的定位 | `'left'|'right'|'start'|'end'|'top'|'bottom'|'center'` | |
| itemStyle | 按钮组容器样式 | `React.CSSProperties` | {} |
| offset | 按钮组容器左偏移距离 | `number` | |
| span | 按钮组容器宽度 | `number` | |
| sticky | 是否洗底 | `boolean` | false |
| style | 大容器样式 | `React.CSSProperties` | {} |

## 用例

Expand Down
18 changes: 8 additions & 10 deletions docs/API/FormConsumer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,14 @@ import {FormConsumer} from '@uform/react'
## API

```typescript
<FormConsumer>
{({
status : String<"changed" | "resetd" | "initialize" | "submitting" | "submitted">, //表单活动状态
state : FormState,//表单状态模型
schema : Object,//表单schema
submit(),//表单提交
reset(),//表单重置
dispatch(name : String,payload : any)//触发effect自定义事件
})=>ReactElement)
</FormConsumer>
type FormConsumer = React.Consumer<{
status : "changed" | "reseted" | "initialize" | "submitting" | "submitted", //表单活动状态
state : IFormState,//表单状态模型
schema : ISchema,//表单schema
submit : () => void,//表单提交
reset : () => void,//表单重置
dispatch: (name: string, payload: any) => void//触发effect自定义事件
}>
```
## 用例
Expand Down
8 changes: 4 additions & 4 deletions docs/API/FormItemGrid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@ import { FormItemGrid } from '@uform/next(antd)'

| 属性名称 | 属性描述 | 属性类型 | 默认值 |
| ---- | ---- | ---- | --- |
| cols | 内部网格宽度占比 | `array<string | object>` | 不传值默认等比分割，可传入类似[4, 8]进行不等比分割，如果数组元素传对象，则是`[{span:3,offset:0}]`这样的形式 |
| description | 描述文案 | string/JSX | |
| gutter | 列间距 | number | 0 |
| title | 标题 | string/JSX | |
| cols | 内部网格宽度占比 | `Array<number | { span: number, offset: number }>` | 不传值默认等比分割，可传入类似[4, 8]进行不等比分割，如果数组元素传对象，则是`[{ span:3,offset:0 }]`这样的形式 |
| description | 描述文案 | `string | JSX.Element | null` | |
| gutter | 列间距 | `number` | 0 |
| title | 标题 | `string | JSX.Element | null` | |

## 用例

Expand Down
16 changes: 8 additions & 8 deletions docs/API/FormLayout.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ import { FormLayout } from '@uform/next(antd)'

| 属性名称 | 属性描述 | 属性类型 | 默认值 | 可选值 |
| ---- | ---- | ---- | --- | --- |
| className | 容器自定义类名 | string | "" | |
| inline | 内部是否采用行内排列 | boolean | false | |
| labelAlign | 按钮组容器样式 | object | "left" | "left"/"top" |
| labelCol | 标签宽度占比 | number | | |
| labelTextAlign | 按钮组容器左偏移距离 | number | "right" | "left"/"right" |
| size | 容器大小 | string | medium | "small"/"medium"/"large" |
| style | 容器样式 | object | {} | |
| wrapperCol | 容器宽度占比 | number | | |
| className | 容器自定义类名 | `string` | "" | |
| inline | 内部是否采用行内排列 | `boolean` | false | |
| labelAlign | 按钮组容器样式 | `'left'|'top'|'inset'` | | "left" | "left"/"top"/"inset" |
| labelCol | 标签宽度占比 | `number` | | |
| labelTextAlign | 按钮组容器左偏移距离 | `'left'|'right'` | "right" | "left"/"right" |
| size | 容器大小 | `'small'|'medium'|'large'` | medium | "small"/"medium"/"large" |
| style | 容器样式 | `React.CSSProperties` | {} | |
| wrapperCol | 容器宽度占比 | `number` | | |

## 用例

Expand Down
22 changes: 11 additions & 11 deletions docs/API/FormPath.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,19 @@
## 类型描述

```typescript
type FormPath {
match : (
pattern : String, //匹配模式字符串
matchRealPath : Boolean, //是否匹配真实路径，该属性是用于处理path为FormField时，是否匹配完整路径
filter : Function //过滤器，相当于是基于pattern所匹配的结果再进行一次过滤操作
interface FormPath {
match: (
pattern : string, //匹配模式字符串
matchRealPath: boolean, //是否匹配真实路径，该属性是用于处理path为FormField时，是否匹配完整路径
filter : (pattern: string) => boolean //过滤器，相当于是基于pattern所匹配的结果再进行一次过滤操作
)=>(
path : String | Array<String> | FormField
)=>Boolean,
path: string | Array<string> | FormField
)=>boolean,
transform:(
path : String | Array<String>,//要改变的路径
regexp : RegExp, //提取正则，该正则会在路径遍历过程中将某个路径节点按照该正则提取出来，然后以参数形式放到callback中
operator : Function //路径处理器，根据正则提取出来的路径节点，做一些转换处理，并返回最终路径
) : Any
path : string | Array<string>, //要改变的路径
regexp : RegExp, //提取正则，该正则会在路径遍历过程中将某个路径节点按照该正则提取出来，然后以参数形式放到callback中
operator: (...paths: string[]) => string; //路径处理器，根据正则提取出来的路径节点，做一些转换处理，并返回最终路径
)=> string
}
```

Expand Down
8 changes: 4 additions & 4 deletions docs/API/FormTextBox.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ import { FormTextBox } from '@uform/next(antd)'

| 属性名称 | 属性描述 | 属性类型 | 默认值 |
| ---- | ---- | ---- | --- |
| text | 字符串文本，以%s来代表字段的位置，同时这种方式对国际化也比较友好 | string | '' |
| description | 描述文案 | string/JSX | |
| gutter | 间距 | number | 10 |
| title | 标题 | string/JSX | |
| text | 字符串文本，以%s来代表字段的位置，同时这种方式对国际化也比较友好 | `string` | '' |
| description | 描述文案 | `string|JSX.Element|null` | |
| gutter | 间距 | `number` | 10 |
| title | 标题 | `string|JSX.Element|null` | |

## 用例

Expand Down
50 changes: 26 additions & 24 deletions docs/API/SchemaForm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,19 @@ import SchemaForm from '@uform/next(antd)'

| 属性名称 | 属性描述 | 属性类型 | 默认值 |
| ---- | ---- | ---- | --- |
| actions | 需要握手的表单actions，只接收通过[createFormActions](#/97UlUl/XEFAF7HoHV)/[createAsyncFormActions](#/97UlUl/leFLFGHMHK)创建出来的actions | Object | |
| defaultValue | 表单默认值 | Object | |
| editable | 控制表单字段是否可编辑状态 | `Boolean | Function(name : String) : Boolean` | |
| effects | 副作用处理函数 | Function | |
| initialValues | 表单值，受控态使用 | Object | {} |
| locale | 表单国际化文案 | Object | {} |
| schema | 表单json schema，具体参考 [扩展规范](#/MpI2Ij/DVSLSafN) | Object | {type:"object",properties:{}} |
| onChange | 表单变化事件回调 | `Function(values : Object){}` | |
| onReset | 表单重置事件回调 | `Function(values : Object){}` | |
| onSubmit | 表单提交事件回调 | `Function(values : Object){}` | |
| onValidateFailed | 表单校验失败事件回调 | Function | |
| actions | 需要握手的表单actions，只接收通过[createFormActions](#/97UlUl/XEFAF7HoHV)/[createAsyncFormActions](#/97UlUl/leFLFGHMHK)创建出来的actions | `FormActions|AsyncFormActions` | |
| defaultValue | 表单默认值 | `any` | |
| value | 表单值 | `any` | |
| editable | 控制表单字段是否可编辑状态 | `boolean|(name: string) => boolean` | |
| effects | 副作用处理函数 | `Effects`| |
| initialValues | 表单值，受控态使用 | `any` | {} |
| locale | 表单国际化文案 | `Locale` | {} |
| schema | 表单json schema，具体参考 [扩展规范](#/MpI2Ij/DVSLSafN) | `ISchema` | {type:"object",properties:{}} |
| onChange | 表单变化事件回调 | `(values: any) => void` | |
| onReset | 表单重置事件回调 | `(values : any) => void` | |
| onSubmit | 表单提交事件回调 | `(values : any) => void` | |
| onValidateFailed | 表单校验失败事件回调 | `(fieldErrors: IFieldError[]) => void` | |


## 副作用处理

Expand Down Expand Up @@ -83,7 +85,7 @@ ReactDOM.render(
$("onFormMount").subscribe((formState)=>{})
$("onFormReset").subscribe((formState)=>{})
$("onFormSubmit").subscribe((formState)=>{})
$("onXXX").subscribe((xxx)=>{}) //自定义事件，主要通过dispatch函数来触发，后面都会提到哪里可以使用dispatch，比如Field组件的x-effect属性，FormConsumer里，FieldRenderProps里
$("onXXX").subscribe((xxx)=>{}) //自定义事件，主要通过dispatch函数来触发，后面都会提到哪里可以使用dispatch，比如Field组件的x-effect属性，FormConsumer里，IFieldProps里
}}
/>
```
Expand All @@ -92,18 +94,18 @@ ReactDOM.render(

| 属性名称 | 属性描述 | 属性类型 | 默认值 | |
| ---- | ---- | ---- | --- | --- |
| autoAddColon | 是否自动添加冒号 | Boolean | | |
| className | className | String | | |
| inline | 是否是单行布局 | Boolean | false | |
| layout | 表单布局(horizontal/vertical/inline)，只有@uform/antd支持 | String | horizontal|
| maxTipsNum | 针对Field description的最大提示字符数，如果超出该字符数，则会以PopTips的形式展示 | Number | 30 |
| labelAlign | 标签的位置<br /><br />可选值:<br />'top'(上)<br />'left'(左)<br />'inset'(内) | String | 'left' | |
| labelCol | 控制所有子节点的labelCol | Number | Object | |
| labelTextAlign | 标签的左右对齐方式<br /><br />可选值:<br />'left'(左)<br />'right'(右) | String | | |
| prefix | className前缀 | String | 'next-' | 'antd-' |
| size | 表单尺寸 <br /><br />可选值:<br />'large'(大)<br />'medium'(中)<br />'small'(小) | String | 'medium' | |
| style | 样式对象 | Object | | |
| wrapperCol | 控制所有子节点wrapperCol | Number | Object | |
| autoAddColon | 是否自动添加冒号 | `boolean` | | |
| className | className | `string` | | |
| inline | 是否是单行布局 | `boolean` | false | |
| layout | 表单布局(horizontal/vertical/inline)，只有@uform/antd支持 | `'horizontal'|'vertical'|'inline'` | horizontal|
| maxTipsNum | 针对Field description的最大提示字符数，如果超出该字符数，则会以PopTips的形式展示 | `number` | 30 |
| labelAlign | 标签的位置<br /><br />可选值:<br />'top'(上)<br />'left'(左)<br />'inset'(内) | `'top'|'left'|'inset'` | 'left' | |
| labelCol | 控制所有子节点的labelCol | `number|{span: number, offset: number}` | | |
| labelTextAlign | 标签的左右对齐方式<br /><br />可选值:<br />'left'(左)<br />'right'(右) | `'left'|'right'` | | |
| prefix | className前缀 | string | 'next-' | 'antd-' |
| size | 表单尺寸 <br /><br />可选值:<br />'large'(大)<br />'medium'(中)<br />'small'(小) | `'large'|'medium'|'small'` | 'medium' | |
| style | 样式对象 | `React.CSSProperties` | | |
| wrapperCol | 控制所有子节点wrapperCol | `number|{span: number, offset: number}` | | |

## 用例

Expand Down
Loading

0 comments on commit 5a9ea5a

Please sign in to comment.