介紹

用于數(shù)據(jù)錄入、校驗(yàn)，支持輸入框、單選框、復(fù)選框、文件上傳等類型，需要與 Field 輸入框 組件搭配使用。2.5 版本開(kāi)始支持此組件。

引入

import Vue from 'vue';
import { Form } from 'vant';
import { Field } from 'vant';

Vue.use(Form);
Vue.use(Field);

代碼演示

基礎(chǔ)用法

在表單中，每個(gè) Field 組件 代表一個(gè)表單項(xiàng)，使用 Field 的 rules 屬性定義校驗(yàn)規(guī)則。

<van-form @submit="onSubmit">
  <van-field
    v-model="username"
    name="用戶名"
    label="用戶名"
    placeholder="用戶名"
    :rules="[{ required: true, message: '請(qǐng)?zhí)顚?xiě)用戶名' }]"
  />
  <van-field
    v-model="password"
    type="password"
    name="密碼"
    label="密碼"
    placeholder="密碼"
    :rules="[{ required: true, message: '請(qǐng)?zhí)顚?xiě)密碼' }]"
  />
  <div style="margin: 16px;">
    <van-button round block type="info" native-type="submit">提交</van-button>
  </div>
</van-form>

export default {
  data() {
    return {
      username: '',
      password: '',
    };
  },
  methods: {
    onSubmit(values) {
      console.log('submit', values);
    },
  },
};

校驗(yàn)規(guī)則

通過(guò) rules 定義表單校驗(yàn)規(guī)則，可用字段見(jiàn)下方表格。

<van-form validate-first @failed="onFailed">
  <!-- 通過(guò) pattern 進(jìn)行正則校驗(yàn) -->
  <van-field
    v-model="value1"
    name="pattern"
    placeholder="正則校驗(yàn)"
    :rules="[{ pattern, message: '請(qǐng)輸入正確內(nèi)容' }]"
  />
  <!-- 通過(guò) validator 進(jìn)行函數(shù)校驗(yàn) -->
  <van-field
    v-model="value2"
    name="validator"
    placeholder="函數(shù)校驗(yàn)"
    :rules="[{ validator, message: '請(qǐng)輸入正確內(nèi)容' }]"
  />
  <!-- 通過(guò) validator 進(jìn)行異步函數(shù)校驗(yàn) -->
  <van-field
    v-model="value3"
    name="asyncValidator"
    placeholder="異步函數(shù)校驗(yàn)"
    :rules="[{ validator: asyncValidator, message: '請(qǐng)輸入正確內(nèi)容' }]"
  />
  <div style="margin: 16px;">
    <van-button round block type="info" native-type="submit">提交</van-button>
  </div>
</van-form>

import { Toast } from 'vant';

export default {
  data() {
    return {
      value1: '',
      value2: '',
      value3: '',
      pattern: /\d{6}/,
    };
  },
  methods: {
    // 校驗(yàn)函數(shù)返回 true 表示校驗(yàn)通過(guò)，false 表示不通過(guò)
    validator(val) {
      return /1\d{10}/.test(val);
    },
    // 異步校驗(yàn)函數(shù)返回 Promise
    asyncValidator(val) {
      return new Promise((resolve) => {
        Toast.loading('驗(yàn)證中...');

        setTimeout(() => {
          Toast.clear();
          resolve(/\d{6}/.test(val));
        }, 1000);
      });
    },
    onFailed(errorInfo) {
      console.log('failed', errorInfo);
    },
  },
};

表單項(xiàng)類型 - 開(kāi)關(guān)

在表單中使用 Switch 組件。

<van-field name="switch" label="開(kāi)關(guān)">
  <template #input>
    <van-switch v-model="switchChecked" size="20" />
  </template>
</van-field>

export default {
  data() {
    return {
      switchChecked: false,
    };
  },
};

表單項(xiàng)類型 - 復(fù)選框

在表單中使用 Checkbox 組件。

<van-field name="checkbox" label="復(fù)選框">
  <template #input>
    <van-checkbox v-model="checkbox" shape="square" />
  </template>
</van-field>
<van-field name="checkboxGroup" label="復(fù)選框組">
  <template #input>
    <van-checkbox-group v-model="checkboxGroup" direction="horizontal">
      <van-checkbox name="1" shape="square">復(fù)選框 1</van-checkbox>
      <van-checkbox name="2" shape="square">復(fù)選框 2</van-checkbox>
    </van-checkbox-group>
  </template>
</van-field>

export default {
  data() {
    return {
      checkbox: false,
      checkboxGroup: [],
    };
  },
};

表單項(xiàng)類型 - 單選框

在表單中使用 Radio 組件。

<van-field name="radio" label="單選框">
  <template #input>
    <van-radio-group v-model="radio" direction="horizontal">
      <van-radio name="1">單選框 1</van-radio>
      <van-radio name="2">單選框 2</van-radio>
    </van-radio-group>
  </template>
</van-field>

export default {
  data() {
    return {
      radio: '1',
    };
  },
};

表單項(xiàng)類型 - 步進(jìn)器

在表單中使用 Stepper 組件。

<van-field name="stepper" label="步進(jìn)器">
  <template #input>
    <van-stepper v-model="stepper" />
  </template>
</van-field>

export default {
  data() {
    return {
      stepper: 1,
    };
  },
};

表單項(xiàng)類型 - 評(píng)分

在表單中使用 Rate 組件。

<van-field name="rate" label="評(píng)分">
  <template #input>
    <van-rate v-model="rate" />
  </template>
</van-field>

export default {
  data() {
    return {
      rate: 3,
    };
  },
};

表單項(xiàng)類型 - 滑塊

在表單中使用 Slider 組件。

<van-field name="slider" label="滑塊">
  <template #input>
    <van-slider v-model="slider" />
  </template>
</van-field>

export default {
  data() {
    return {
      slider: 50,
    };
  },
};

表單項(xiàng)類型 - 文件上傳

在表單中使用 Uploader 組件。

<van-field name="uploader" label="文件上傳">
  <template #input>
    <van-uploader v-model="uploader" />
  </template>
</van-field>

export default {
  data() {
    return {
      uploader: [{ url: 'https://img01.yzcdn.cn/vant/leaf.jpg' }],
    };
  },
};

表單項(xiàng)類型 - 選擇器

在表單中使用 Picker 組件。

<van-field
  readonly
  clickable
  name="picker"
  :value="value"
  label="選擇器"
  placeholder="點(diǎn)擊選擇城市"
  @click="showPicker = true"
/>
<van-popup v-model="showPicker" position="bottom">
  <van-picker
    show-toolbar
    :columns="columns"
    @confirm="onConfirm"
    @cancel="showPicker = false"
  />
</van-popup>

export default {
  data() {
    return {
      value: '',
      columns: ['杭州', '寧波', '溫州', '嘉興', '湖州'],
      showPicker: false,
    };
  },
  methods: {
    onConfirm(value) {
      this.value = value;
      this.showPicker = false;
    },
  },
};

表單項(xiàng)類型 - 時(shí)間選擇器

在表單中使用 DatetimePicker 組件。

<van-field
  readonly
  clickable
  name="datetimePicker"
  :value="value"
  label="時(shí)間選擇"
  placeholder="點(diǎn)擊選擇時(shí)間"
  @click="showPicker = true"
/>
<van-popup v-model="showPicker" position="bottom">
  <van-datetime-picker
    type="time"
    @confirm="onConfirm"
    @cancel="showPicker = false"
  />
</van-popup>

export default {
  data() {
    return {
      value: '',
      showPicker: false,
    };
  },
  methods: {
    onConfirm(time) {
      this.value = time;
      this.showPicker = false;
    },
  },
};

表單項(xiàng)類型 - 省市區(qū)選擇器

在表單中使用 Area 組件。

<van-field
  readonly
  clickable
  name="area"
  :value="value"
  label="地區(qū)選擇"
  placeholder="點(diǎn)擊選擇省市區(qū)"
  @click="showArea = true"
/>
<van-popup v-model="showArea" position="bottom">
  <van-area
    :area-list="areaList"
    @confirm="onConfirm"
    @cancel="showArea = false"
  />
</van-popup>

export default {
  data() {
    return {
      value: '',
      showArea: false,
      areaList: {}, // 數(shù)據(jù)格式見(jiàn) Area 組件文檔
    };
  },
  methods: {
    onConfirm(values) {
      this.value = values
        .filter((item) => !!item)
        .map((item) => item.name)
        .join('/');
      this.showArea = false;
    },
  },
};

表單項(xiàng)類型 - 日歷

在表單中使用 Calendar 組件。

<van-field
  readonly
  clickable
  name="calendar"
  :value="value"
  label="日歷"
  placeholder="點(diǎn)擊選擇日期"
  @click="showCalendar = true"
/>
<van-calendar v-model="showCalendar" @confirm="onConfirm" />

export default {
  data() {
    return {
      value: '',
      showCalendar: false,
    };
  },
  methods: {
    onConfirm(date) {
      this.value = `${date.getMonth() + 1}/${date.getDate()}`;
      this.showCalendar = false;
    },
  },
};

API

Props

表單項(xiàng)的 API 參見(jiàn)：Field 組件

Rule 數(shù)據(jù)結(jié)構(gòu)

使用 Field 的 rules 屬性可以定義校驗(yàn)規(guī)則，可選屬性如下:

validate-trigger 可選值

通過(guò) validate-trigger 屬性可以自定義表單校驗(yàn)的觸發(fā)時(shí)機(jī)。

Events

方法

通過(guò) ref 可以獲取到 Form 實(shí)例并調(diào)用實(shí)例方法，詳見(jiàn)組件實(shí)例方法。

Slots

常見(jiàn)問(wèn)題

點(diǎn)擊表單中的普通按鈕為什么會(huì)觸發(fā)表單提交？

在表單中，除了提交按鈕外，可能還有一些其他的功能性按鈕，如發(fā)送驗(yàn)證碼按鈕。在使用這些按鈕時(shí)，要注意將native-type設(shè)置為button，否則會(huì)觸發(fā)表單提交。

<van-button native-type="button">發(fā)送驗(yàn)證碼</van-button>

這個(gè)問(wèn)題的原因是瀏覽器中 button 標(biāo)簽 type 屬性的默認(rèn)值為submit，導(dǎo)致觸發(fā)表單提交。我們會(huì)在下個(gè)大版本中將 type 的默認(rèn)值調(diào)整為button來(lái)避免這個(gè)問(wèn)題。