@king-design/intact 2.0.0-beta.0

package/components/form/demos/basic.md

@@ -0,0 +1,193 @@
+---
+title: 基本用法
+order: 0
+---
+
+表单需要`Form`嵌套`FormItem`进行使用，`FormItem`中可以包含任意组件或原生元素。
+同时我们可以指定`FormItem`的表单验证规则：
+
+1. 给`FormItem`添加`value`属性，指定需要验证的数据。如果不指定，则不会进行任何验证
+2. 给`FormItem`添加`rules`属性，指定需要验证的规则。如果不指定，则不会进行任何验证。内置的验证规则如下：
+    1. `required {Boolean}`：必须填写
+    2. `digits {Boolean}`： 请输入数字
+    3. `email {Boolean}`: 请输入正确的邮箱地址
+    4. `url {Boolean}`: 请输入正确的网址
+        > 该规则可以验证IP地址，但是会排除`192.168.X.X | 192.254.X.X | 172.16.0.0 - 172.31.255.255 | 10.X.X.X | 172.X.X.X`这类保留IP地址
+    5. `date {Boolean}`：请输入正确的日期
+    6. `dateISO {Boolean}`：请输入正确的日期（YYYY-MM-DD）
+    7. `number {Boolean}`：请输入正确的数
+    8. `maxLength {Number}`：如果检验的值是数组：最多选择n项；如果检验的值是字符串：最多输入n个字符
+    9. `minLength {Number}`：同上（检验最少长度）
+    10. `rangeLength {Array<Number>}`：同上，检验长度的范围
+    11. `max {Number}`：请输入不大于n的数
+    12. `min {Number}`：请输入不小于n的数
+    13. `range {Array<Number>}`：请输入min到max之间的数
+    14. `step {Number}`：请输入步长为n的数
+    15. `equalTo {String}`：两次输入不一致
+3. 给`FormItem`添加`messages`属性，指定验证失败时展示的错误提示。默认内容如上所示
+4. 给`FormItem`添加`classNames`属性，指定验证失败时错误元素需要额外添加的`className`，默认不添加
+
+表单验证通过会触发`submit`事件（不通过不会触发），我们可以绑定该事件来提交数据。或者我们也可以
+手动调用`Form`的`validate()`方法来验证，该函数为异步函数，返回`true`或`false`来标示验证是否通过。
+另外，验证失败时，可以通过`Form`的`getFirstInvalidFormItem()`方法来获取第一条出错的`FormItem`
+
+```vdt
+import {
+    Form, FormItem,
+    Input,
+    Select, Option,
+    Checkbox,
+    Radio,
+    ButtonGroup, Button,
+    Switch,
+    Slider,
+    Datepicker,
+} from 'kpc';
+
+<Form ev-submit={this.submit} ref="form" labelWidth="200">
+    <FormItem label="Input" value={this.get('model.input')} rules={{required: true}}>
+        <Input v-model="model.input" />
+    </FormItem>
+    <FormItem label="Select" value={this.get('model.select')}
+        rules={{required: true}} 
+        messages={{required: '必须选择'}}
+    >
+        <Select v-model="model.select">
+            <Option value="Javascript">Javascript</Option>
+            <Option value="PHP">PHP</Option>
+            <Option value="C++">C++</Option>
+        </Select>
+    </FormItem>
+    <FormItem label="Checkbox" value={this.get('model.checkbox')}
+        rules={{required: true, maxLength: 2}}
+        messages={{required: '必须选择'}}
+    >
+        <Checkbox trueValue="Javascript" v-model="model.checkbox">Javascript</Checkbox>
+        <Checkbox trueValue="PHP" v-model="model.checkbox">PHP</Checkbox>
+        <Checkbox trueValue="C++" v-model="model.checkbox">C++</Checkbox>
+    </FormItem>
+    <FormItem label="Radio" value={this.get('model.radio')}
+        rules={{required: true}} 
+        messages={{required: '必须选择'}}
+    >
+        <Radio trueValue="Javascript" v-model="model.radio">Javascript</Radio>
+        <Radio trueValue="PHP" v-model="model.radio">PHP</Radio>
+        <Radio trueValue="C++" v-model="model.radio">C++</Radio>
+    </FormItem>
+    <FormItem label="Radio ButtonGroup" value={this.get("model.buttonGroup")}
+        rules={{required: true}} 
+        messages={{required: '必须选择'}}
+    >
+        <ButtonGroup checkType="radio" v-model="model.buttonGroup">
+            <Button value="Javascript">Javascript</Button>
+            <Button value="PHP">PHP</Button>
+            <Button value="C++">C++</Button>
+        </ButtonGroup>
+    </FormItem>
+    <FormItem label="Switch" value={this.get("model.switch")}>
+        <Switch v-model="model.switch" />
+    </FormItem>
+    <FormItem value={this.get("model.slider")} rules={{required: true, min: 1}} label="Slider">
+        <Slider v-model="model.slider" showInput={false} />
+    </FormItem>
+    <FormItem value={this.get("model.date")} rules={{required: true}} label="Datepicker">
+        <Datepicker v-model="model.date" />  
+    </FormItem>
+    <FormItem label="Textarea" value={this.get("model.textarea")}
+        rules={{required: true}}
+    >
+        <Input type="textarea" v-model="model.textarea" />
+    </FormItem>
+    <FormItem label="Password" value={this.get("model.password")}
+        rules={{required: true}}
+    >
+        <Input type="password" v-model="model.password" />
+    </FormItem>
+    <FormItem label="Confirm Password" value={this.get("model.confirmPassword")}
+        rules={{required: true, equal: this.get('model.password')}}
+    >
+        <Input type="password" v-model="model.confirmPassword" />
+    </FormItem>
+    <FormItem>
+        <Button type="primary" htmlType="submit" ev-click={this.handleSubmit}>提交</Button>
+        <Button style="margin-left: 20px" ev-click={this.reset}>重置</Button>
+    </FormItem>
+</Form>
+```
+
+```styl
+.k-slider
+.k-select
+    width 300px
+.k-radio
+.k-checkbox
+    margin-right 10px
+
+@media (max-width: 768px) 
+    .k-form-item
+        width 100%
+        .k-input
+        .k-select
+        .k-datepicker
+        .k-slider
+            width 100%
+        .k-label
+            width 100px !important
+```
+
+```ts
+import {Message, bind} from 'kpc';
+
+interface Props {
+    model: Model
+}
+
+type Model = {
+    input?: string
+    select?: string
+    checkbox: string[] 
+    radio?: string
+    buttonGroup?: string
+    switch?: boolean
+    slider?: number
+    date?: string
+    textarea?: string
+    password?: string
+    confirmPassword?: string
+}
+
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            model: {
+                checkbox: []
+            }
+        } as Props;
+    }
+
+    @bind
+    submit() {
+        Message.success('验证通过，开始提交');
+        console.log(this.get('model'));
+    }
+
+    @bind
+    async handleSubmit() {
+        if (await this.refs.form.validate()) {
+            console.log('验证通过，开始提交');
+        } else {
+            // 验证失败，我们可以获取第一条出错的FormItem
+            console.log(this.refs.form.getFirstInvalidFormItem());
+        }
+    }
+
+    @bind
+    reset() {
+        this.set('model', {checkbox: []});
+        this.refs.form.reset();
+        console.log(this.get('model'));
+    }
+}
+```

package/components/form/demos/custom.md

@@ -0,0 +1,242 @@
+---
+title: 自定义验证规则
+order: 1
+---
+
+当内置的验证规则不能满足需求时，我们还可以自定义验证规则。有如下两种方式添加规则：
+
+1. 通过`Form.addMethod()`静态方法添加全局验证规则，由于是全局的，我们可以在任意地方的
+`FormItem`中使用该规则。使用方法见API说明
+2. 通过`FormItem`的`rules`属性，定义局部规则，该规则只对该`FormItem`有效
+
+本例中，我们添加一条全局规则`letter`用来验证只能输入字母，同时添加一条局部规则
+`unique`来验证所有输入必须不同
+
+> 验证方法中`param`，即为使用该规则时传入的参数，例如本例中的`letter: true`，`true`会作为`param`
+> 参数传给验证方法。当然我们还可以指定任意值，只要不是`false`就行，因为`false`代表不验证
+
+```vdt
+import {Form, FormItem, Input, Button} from 'kpc';
+
+<Form>
+    <FormItem label="描述">
+        <FormItem v-for={this.get('descriptions')}
+            value={$value}
+            hideLabel
+            rules={{
+                required: true, 
+                // 自定义全局规则
+                letter: true,
+                // 自定义局部规则: 所有描述必须不重复
+                unique: this.unique 
+            }}
+        >
+            <Input v-model={`descriptions[${$key}]`} />    
+            <b:append>
+                <Button ev-click={this.remove.bind(self, $key)}>删除</Button>
+            </b:append>
+        </FormItem>
+        <Button ev-click={this.add}>添加</Button>
+    </FormItem>
+</Form>
+```
+
+```styl
+.k-form-item
+    .k-form-item
+        margin-bottom 20px
+
+@media (max-width: 768px)
+    .k-form-item
+        width 100%
+        .k-input
+            width 100%
+        .k-label
+            width auto
+```
+
+```ts
+import {Form, bind} from 'kpc';
+
+interface Props {
+    descriptions: string[]
+}
+
+// 添加全局规则
+Form.addMethod('letter', (value, param) => {
+    return /^[a-z|A-Z]+$/.test(value);
+}, '只能输入字母');
+
+export default class extends Component<Props> {
+    static template = template;
+    static defaults() {
+        return {
+            descriptions: ['', '']
+        }
+    };
+
+    @bind
+    add() {
+        this.set('descriptions', this.get('descriptions').concat(''));
+    }
+
+    @bind
+    remove(index: number) {
+        const descriptions = this.get('descriptions').slice(0);
+        descriptions.splice(index, 1);
+        this.set('descriptions', descriptions);
+    }
+
+    @bind
+    unique(value: string) {
+        let count = 0;
+        this.get('descriptions').find(item => {
+            if (item === value) count++;
+            return count > 1;
+        });
+
+        // 直接返回错误文案，或者也可以单独定义messages为{unique: '不能相同'}
+        return count === 1 || '不能相同';
+    }
+}
+```
+
+```vue-template
+<Form>
+    <FormItem label="描述">
+        <FormItem v-for="($value, $key) in descriptions"
+            :model="`descriptions[${$key}]`"
+            hideLabel
+            :rules="{
+                required: true, 
+                // 自定义全局规则
+                letter: true,
+                // 自定义局部规则，所有描述必须不重复
+                unique: unique 
+            }"
+        >
+            <Input v-model="descriptions[$key]" />    
+            <template slot="append">
+                <Button @click="remove($key)">删除</Button>
+            </template>
+        </FormItem>
+        <Button @click="add">添加</Button>
+    </FormItem>
+</Form>
+```
+
+```vue-methods
+add() {
+    this.descriptions.push('');
+}
+remove(index: number) {
+    this.descriptions.splice(index, 1);
+}
+```
+
+```react-methods
+add() {
+    this.setState({descriptions: this.state.descriptions.concat('')});
+}
+
+onInput(index: number, v?: string) {
+    const descriptions = this.state.descriptions.slice(0);
+    descriptions[index] = v!;
+    this.setState({descriptions});
+}
+
+render() {
+    return (
+        <Form>
+            <FormItem label="描述">
+                {this.state.descriptions.map(($value, $key) => {
+                    return (
+                        <FormItem
+                            slotAppend={<Button onClick={this.remove.bind(self, $key)}>删除</Button>}
+                            value={$value}
+                            hideLabel
+                            rules={{
+                                required: true, 
+                                // 自定义全局规则
+                                letter: true,
+                                // 自定义局部规则，所有描述必须不重复
+                                unique: this.unique 
+                            }}
+                        >
+                            <Input value={this.state.descriptions[$key]} 
+                                onChangeValue={this.onInput.bind(this, $key)}
+                            />    
+                        </FormItem>
+                    )
+                })}
+                <Button onClick={this.add}>添加</Button>
+            </FormItem>
+        </Form>
+    )
+}
+```
+
+```angular
+// import {Component} from '@angular/core';
+// import {Form} from 'kpc';
+// 
+// // 添加全局规则
+// Form.addMethod('letter', (value, item, param) => {
+//     return /^[a-z|A-Z]+$/.test(value);
+// }, '只能输入字母');
+// 
+// @Component({
+//     selector: 'app-demo',
+//     template: `
+//         <k-form>
+//             <k-form-item label="标签">
+//                 <k-form-item
+//                     *ngFor="let value of descriptions; let i = index; trackBy: trackArray"
+//                     [value]="value"
+//                     [hideLabel]="true"
+//                     [rules]="{
+//                         required: true, 
+//                         letter: true,
+//                         unique: unique
+//                     }"
+//                     [force]="true"
+//                 >
+//                     <k-input [(value)]="descriptions[i]"></k-input>    
+//                     <ng-template #append>
+//                         <k-button (click)="remove(i)">删除</k-button>
+//                     </ng-template>
+//                 </k-form-item>
+//                 <k-button (click)="add()">添加</k-button>
+//             </k-form-item>
+//         </k-form>
+//     `,
+//     styleUrls: ['./index.styl'],
+// })
+// export class AppDemoComponent {
+//     private descriptions = ["", ""];
+// 
+//     add() {
+//         this.descriptions = this.descriptions.concat('');
+//     }
+//     
+//     remove(index) {
+//         this.descriptions.splice(index, 1);
+//     }
+// 
+//     trackArray(index) {
+//         return index;
+//     }
+// 
+//     // 局部验证规则
+//     unique = (value) => {
+//         let count = 0;
+//         this.descriptions.find(item => {
+//             if (item === value) count++;
+//             return count > 1;
+//         });
+// 
+//         // 直接返回错误文案，或者也可以单独定义messages为{unique: '不能相同'}
+//         return count === 1 || '不能相同';
+//     }
+// }
+```

package/components/form/demos/label.md

@@ -0,0 +1,29 @@
+---
+title: 自定义label
+order: 3
+---
+
+通过`label`扩展点，我们可以定义更复杂的`label`，而不仅仅只是文本，当`Form`添加了`starOnRequired`属性时，
+必填的`FormItem`标签前面将自动添加`*`
+
+```vdt
+import {Form, FormItem, Input} from 'kpc';
+
+<Form starOnRequired>
+    <FormItem rules={{required: true}} label="姓名">
+        <Input />
+    </FormItem>
+    <FormItem>
+        <b:label><i class="ion-person"></i> 姓名</b:label>
+        <Input />
+    </FormItem>
+</Form>
+```
+
+```styl
+@media (max-width: 768px) 
+    .k-form-item
+        width 100%
+        .k-input
+            width 100%
+```

package/components/form/demos/layout.md

@@ -0,0 +1,69 @@
+---
+title: 表单布局
+order: 5
+---
+
+通过`layout`指定表单布局：`horizontal`, `vertical`, `inline`，还可以通过`size`控制`FormItem`的间距
+
+```vdt
+import {Form, FormItem, Input, Select, Option, ButtonGroup, Button} from 'kpc';
+
+<Form layout={this.get('layout')} size={this.get('size')}>
+    <FormItem label="Layout">
+        <ButtonGroup checkType="radio" v-model="layout">
+            <Button value="horizontal">horizontal</Button>
+            <Button value="vertical">vertical</Button>
+            <Button value="inline">inline</Button>
+        </ButtonGroup>
+    </FormItem>
+    <FormItem label="Size">
+        <ButtonGroup checkType="radio" v-model="size">
+            <Button value="default">default</Button>
+            <Button value="small">small</Button>
+            <Button value="mini">mini</Button>
+        </ButtonGroup>
+    </FormItem>
+    <FormItem label="Input" value={this.get('model.input')} rules={{required: true}}>
+        <Input v-model="model.input" />
+    </FormItem>
+    <FormItem label="Select" value={this.get("model.select")}
+        rules={{required: true}} 
+    >
+        <Select v-model="model.select">
+            <Option value="Javascript">Javascript</Option>
+            <Option value="PHP">PHP</Option>
+            <Option value="C++">C++</Option>
+        </Select>
+    </FormItem>
+    <FormItem>
+        <Button type="primary" htmlType="submit">Submit</Button>
+    </FormItem>
+</Form>
+```
+
+```ts
+import type {FormProps} from 'kpc';
+
+interface Props {
+    model: Model
+    layout: FormProps['layout']
+    size: FormProps['size']
+}
+
+type Model = {
+    input?: string
+    select?: string
+}
+
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            model: {},
+            layout: 'horizontal',
+            size: 'default'
+        } as Props;
+    }
+}
+```

package/components/form/demos/remote.md

@@ -0,0 +1,52 @@
+---
+title: 异步验证 
+order: 4
+---
+
+要完成异步验证（例如：通过后端接口判断用户名是否重复），只需要在验证规则函数中返回`Promise`即可
+
+```vdt
+import {Form, FormItem, Input} from 'kpc';
+
+<Form ref="form">
+    <FormItem label="用户名" value={this.get('userName')}
+        rules={{required: true, userName: this.validateUserName}}
+    >
+        <Input v-model="userName" />
+    </FormItem>
+</Form>
+```
+
+```styl
+@media (max-width: 768px)
+    .k-form-item
+        width 100%
+        .k-input
+            width 100%
+        .k-label
+            width auto
+```
+
+```ts
+export default class extends Component<{userName?: string}> {
+    static template = template;
+    static defaults() {
+        return {
+            userName: ''
+        }
+    }
+
+    validateUserName(value: string) {
+        // mock api
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                if (Math.random() > 0.5) {
+                    reject({message: `用户名 ${value} 已被占用`});
+                } else {
+                    resolve(true);
+                }
+            });
+        });
+    }
+}
+```

package/components/form/demos/variable.md

@@ -0,0 +1,60 @@
+---
+title: 可变规则
+order: 3
+---
+
+规则`rules`的值是响应式的，这意味着我们可以实时改变验证规则。
+
+例如本例中，用户可以不输入姓名，但如果输入了“姓”，就必须输入“名”，反之亦然。
+
+```vdt
+import {Form, FormItem, Input, Row, Col} from 'kpc';
+
+<Form ref="form">
+    <FormItem label="姓名">
+        <Row gutter="16">
+            <Col span="12">
+                <FormItem hideLabel value={this.get('firstName')} rules={{
+                    // 该规则取值，随着lastName的存在与否而改变
+                    required: this.get('lastName')
+                }}> 
+                    <Input v-model="firstName" />
+                </FormItem>
+            </Col>
+            <Col span="12">
+                <FormItem hideLabel value={this.get("lastName")} rules={{
+                    // 该规则取值，随着firstName的存在与否而改变
+                    required: this.get('firstName')
+                }}> 
+                    <Input v-model="lastName" />
+                </FormItem>
+            </Col>
+        </Row>
+    </FormItem>
+</Form>
+```
+
+```styl
+@media (max-width: 768px)
+    .k-form-item
+        width 100%
+        .k-input
+            width 100%
+```
+
+```ts
+interface Props {
+    firstName?: string
+    lastName?: string
+}
+
+export default class extends Component<Props> {
+    static template = template;
+    static defaults() {
+        return {
+            firstName: '',
+            lastName: '',
+        }
+    }
+}
+```