PIUI 高质量开源组件库

# Form 表单

用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型。

# 平台差异说明

App H5 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
√ √ √ √ √ √ √

# 示例

# 基础用法

包含多种表单控件，如输入框，选择器，复选框，文本域等。

required 属性可设置表单项必填标志。 border 属性为表单项添加底部边框。

<pi-form
  ref="form"
  label-width="200"
  input-align="right"
  :model="form"
  title="典型表单"
  border
  error-type="toast"
>
  <pi-form-item required label-width="300" prop="name" label="姓名">
    <pi-input v-model="form.name" />
  </pi-form-item>
  <pi-form-item required label-width="300" prop="age" label="年龄">
    <pi-input v-model="form.age" type="number" />
  </pi-form-item>
  <pi-form-item required label-width="300" prop="sex" label="性别">
    <pi-radio-group v-model="form.sex" shape="dot">
      <pi-radio name="male">男</pi-radio>
      <pi-radio name="female">女</pi-radio>
    </pi-radio-group>
  </pi-form-item>
  <pi-form-item required label-width="300" prop="notice" label="自动通知">
    <pi-switch v-model="form.notice" />
  </pi-form-item>
  <pi-form-item label="参与活动" prop="" activity>
    <pi-checkbox-group v-model="form.activity" shape="text" active-mode="fill">
      <pi-checkbox name="1">活动1</pi-checkbox>
      <pi-checkbox name="2">活动2</pi-checkbox>
      <pi-checkbox name="3">活动3</pi-checkbox>
    </pi-checkbox-group>
  </pi-form-item>
  <pi-form-item prop="intro" label="自我介绍" wrap>
    <pi-input v-model="form.intro" type="textarea" placeholder="请输入" />
  </pi-form-item>
  <pi-form-item>
    <pi-button type="primary" @click="handleSubmitForm">提交</pi-button>
    <pi-button class="pi-mg-left-24" type="secondary" @click="handleResetForm">
      重置
    </pi-button>
  </pi-form-item>
</pi-form>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 标题和描述

通过 title, desc 属性可以设置表单的标题和描述。

<pi-form slot="body" :model="form" title="表单标题：禁用" desc="表单描述" border disabled>
  <pi-form-item label="名称">
    <pi-input />
    <view slot="right">秒</view>
  </pi-form-item>
</pi-form>
1
2
3
4
5
6

# 对齐方式和宽度

根据不同需求选择不同的标签对齐方式，labelAlign 属性提供了三种选择：

  1. left : 左对齐
  2. center : 居中对齐
  3. right : 右对齐

还可以配合labelWidth使用，整体表现会更好。

<view class="pi-justify-between">
  <pi-radio-group
    v-model="labelAlign"
    shape="dot"
    class="pi-justify-center"
    direction="vertical"
  >
    <pi-radio name="left">左对齐</pi-radio>
    <pi-radio name="center">居中对齐</pi-radio>
    <pi-radio name="right">右对齐</pi-radio>
  </pi-radio-group>
  <pi-radio-group
    v-model="labelWidth"
    shape="dot"
    class="pi-justify-center"
    direction="vertical"
  >
    <pi-radio :name="120">宽度120</pi-radio>
    <pi-radio :name="200">宽度200</pi-radio>
    <pi-radio :name="300">宽度300</pi-radio>
  </pi-radio-group>
</view>
<pi-form :model="form" :label-align="labelAlign" :label-width="labelWidth">
  <pi-form-item required prop="name" label="姓名">
    <pi-input v-model="form.name" />
  </pi-form-item>
  <pi-form-item required prop="age" label="手机号">
    <pi-input v-model="form.age" type="number" />
  </pi-form-item>
  <pi-form-item required prop="age" label="是否预约">
    <pi-switch v-model="form.notice" />
  </pi-form-item>
</pi-form>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
export default {
  name: 'Input',
  data() {
    return {
      form: {
        name: '张三',
        phone: 12,
        sex: 'male'
      },
      labelAlign: 'left',
    }
  },
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 标签换行

有时设置对齐和宽度也不符合设计目标，此时使用 wrap 标签换行或许会更好。

<pi-form :model="form" wrap>
  <pi-form-item required prop="name" label="姓名">
    <pi-input v-model="form.name" />
  </pi-form-item>
  <pi-form-item required prop="age" label="手机号">
    <pi-input v-model="form.age" type="number" />
  </pi-form-item>
  <pi-form-item required prop="age" label="是否预约">
    <pi-switch v-model="form.notice" />
  </pi-form-item>
</pi-form>
1
2
3
4
5
6
7
8
9
10
11

但是我们可能不希望全部标签换行，此时只需要在某个 pi-form-item 上单独设置即可。

# 表单校验

在提交数据前让用户发现并且及时解决错误。

在 Form 上用 model 绑定表单数据对象，ref设置表单标识，然后在 Form-Item 上把 prop 属性设置为对应字段即可。

设置 border 属性在每一个 Form-Item 里加上底边框。

<pi-form ref="form" :model="form" border error-type="toast">
  <pi-form-item prop="name" label="姓名"><pi-input v-model="form.name" /></pi-form-item>
  <pi-form-item prop="intro" label="简介">
    <pi-input v-model="form.intro" type="textarea" placeholder="请输入简介" />
  </pi-form-item>
  <pi-form-item>
    <pi-button type="primary" @click="handleSubmitForm">提交</pi-button>
    <pi-button type="secondary" @click="handleResetForm">重置</pi-button>
  </pi-form-item>
</pi-form>
1
2
3
4
5
6
7
8
9
10
<script>
export default {
  name: 'Input',
  data() {
    return {
      form: {
        name: '张三',
        intro: '三个字'
      },
      checkboxGroupMax: ['male'],
      stepper: 1
    }
  },
  onReady() {
    const rules = {
      name: [
        {
          required: true,
          message: '请输入姓名',
          // 可以单个或者同时写两个触发验证方式
          trigger: ['change', 'blur']
        }
      ],
      intro: [
        {
          required: true,
          message: '请输入简介',
          // 可以单个或者同时写两个触发验证方式
          trigger: ['change', 'blur']
        },
        {
          min: 5,
          message: '简介不能少于5个字',
          trigger: 'change'
        }
      ]
    }
    this.$refs.form.setRules(rules)
  },
  methods: {
    handleSubmitForm() {
      this.$refs.form.validation()
    },
    handleResetForm() {
      this.$refs.form.resetValidation()
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

更多校验规则及高级用法参考 async-validator (opens new window)。

# API

# Form Props

名称 描述 类型 必选 默认值
model 表单项值 注意：绑定是:model不是v-model false -
customStyle 自定义样式 Object false -
customClass 自定义样式类 String false -
title 列表面板标题 String false -
desc 列表面板描述 String false -
titleStyle 标题自定义样式 Object false -
height 高度 String | Number false -
labelWidth 表单项 label 宽度，默认单位为rpx String | Number false 120
labelAlign 表单label区域 label 对齐方式 'left' 'center' 'right' false -
labelStyle 表单项 label样式 Object false -
inputAlign 表单输入区域 label 对齐方式 'left' 'center' 'right' false -
wrap 是否以换行样式显示表单 Boolean false -
labelWrapBorder wrap样式label是否显示边框 Boolean false -
colon 是否在 label 后面添加冒号 Boolean false false
disabled 是否禁用 Boolean false false
border 是否显示边框 Boolean false false
errorType 表单校验两种提示 'message'-输入框下方提示 'toast'-提示(只提示第一个错误) false 'message'
showRightIcon 表单项是否显示右边icon。默认是箭头（可以自定义设置成其他图标） Boolean false false
rightIcon 右侧icon样式, 对象形式 Object false rightIcon配置项

# Form Slots

名称 描述 插槽内容
default - -

# FormItem Props

注意

Form与FormItem同名的属性，相当于整体设置，会覆盖FormItem的属性

名称 描述 类型 必选 默认值
customStyle 自定义样式 Object false -
customClass 自定义样式类 String false -
prop 绑定字段 String false ''
required 是否必填 Boolean false -
requiredStyle 必填标志自定义样式 Object false -
height 高度 String | Number false -
padding 列表项内边距 String false -
label - String false -
labelWidth 表单项 label 宽度，默认单位为rpx String | Number false -
labelStyle 表单项 label样式 Object false -
labelAlign 表单label区域 label 对齐方式 'left' 'center' 'right' false 'left'
inputAlign 表单输入区域 label 对齐方式 'left' 'center' 'right' false 'right'
wrap 是否以换行样式显示表单 Boolean false false
labelWrapBorder wrap样式label是否显示边框 Boolean false true
colon 是否在 label 后面添加冒号 Boolean false false
disabled 是否禁用 Boolean false false
border 是否显示边框 Boolean false false
showRightIcon 表单项是否显示右边icon。默认是箭头（可以自定义设置成其他图标） Boolean false false
rightIcon 右侧icon样式, 对象形式 Object false rightIcon配置项

# Right Icon

参数 说明 类型 可选值 默认值
name 图标名称或图片链接 Object - 'right'
dot 是否显示图标右上角小红点 Boolean true false
badge 图标右上角徽标的内容 String - ''
color 图标颜色 String - '#cccccc'
size 图标字体大小，单位rpx Number/String - 默认使用字体大小
classPrefix 类名前缀，用于使用自定义图标 String - 'pi-icon-'

# FormItem Events

事件名 描述 参数
click - -

# FormItem Slots

名称 描述 插槽内容
label 表单项label -
default 表单项内容 -
right 右侧区域内容 -
Last updated: 2021/11/23 下午4:13:36

← Mask 蒙层 →

10:44