介紹

用戶可以在文本框內(nèi)輸入或編輯文字。

引入

通過以下方式來全局注冊(cè)組件，更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。

import { createApp } from 'vue';
import { Field, CellGroup } from 'vant';

const app = createApp();
app.use(Field);
app.use(CellGroup);

代碼演示

基礎(chǔ)用法

可以通過 ?v-model? 雙向綁定輸入框的值，通過 ?placeholder? 設(shè)置占位提示文字。

<!-- 可以使用 CellGroup 作為容器 -->
<van-cell-group inset>
  <van-field v-model="value" label="文本" placeholder="請(qǐng)輸入用戶名" />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref('');
    return { value };
  },
};

自定義類型

根據(jù) ?type? 屬性定義不同類型的輸入框，默認(rèn)值為 ?text?。

<van-cell-group inset>
  <!-- 輸入任意文本 -->
  <van-field v-model="text" label="文本" />
  <!-- 輸入手機(jī)號(hào)，調(diào)起手機(jī)號(hào)鍵盤 -->
  <van-field v-model="tel" type="tel" label="手機(jī)號(hào)" />
  <!-- 允許輸入正整數(shù)，調(diào)起純數(shù)字鍵盤 -->
  <van-field v-model="digit" type="digit" label="整數(shù)" />
  <!-- 允許輸入數(shù)字，調(diào)起帶符號(hào)的純數(shù)字鍵盤 -->
  <van-field v-model="number" type="number" label="數(shù)字" />
  <!-- 輸入密碼 -->
  <van-field v-model="password" type="password" label="密碼" />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const tel = ref('');
    const text = ref('');
    const digit = ref('');
    const number = ref('');
    const password = ref('');

    return { tel, text, digit, number, password };
  },
};

禁用輸入框

通過 ?readonly? 將輸入框設(shè)置為只讀狀態(tài)，通過 ?disabled? 將輸入框設(shè)置為禁用狀態(tài)。

<van-cell-group inset>
  <van-field label="文本" model-value="輸入框只讀" readonly />
  <van-field label="文本" model-value="輸入框已禁用" disabled />
</van-cell-group>

顯示圖標(biāo)

通過 ?left-icon? 和 ?right-icon? 配置輸入框兩側(cè)的圖標(biāo)，通過設(shè)置 ?clearable? 在輸入過程中展示清除圖標(biāo)。

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="文本"
    left-icon="smile-o"
    right-icon="warning-o"
    placeholder="顯示圖標(biāo)"
  />
  <van-field
    v-model="value2"
    clearable
    label="文本"
    left-icon="music-o"
    placeholder="顯示清除圖標(biāo)"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('123');
    return {
      value1,
      value2,
    };
  },
};

錯(cuò)誤提示

設(shè)置 ?required? 屬性表示這是一個(gè)必填項(xiàng)，可以配合 ?error? 或 ?error-message? 屬性顯示對(duì)應(yīng)的錯(cuò)誤提示。

<van-cell-group inset>
  <van-field
    v-model="username"
    error
    required
    label="用戶名"
    placeholder="請(qǐng)輸入用戶名"
  />
  <van-field
    v-model="phone"
    required
    label="手機(jī)號(hào)"
    placeholder="請(qǐng)輸入手機(jī)號(hào)"
    error-message="手機(jī)號(hào)格式錯(cuò)誤"
  />
</van-cell-group>

插入按鈕

通過 button 插槽可以在輸入框尾部插入按鈕。

<van-cell-group inset>
  <van-field
    v-model="sms"
    center
    clearable
    label="短信驗(yàn)證碼"
    placeholder="請(qǐng)輸入短信驗(yàn)證碼"
  >
    <template #button>
      <van-button size="small" type="primary">發(fā)送驗(yàn)證碼</van-button>
    </template>
  </van-field>
</van-cell-group>

格式化輸入內(nèi)容

通過 ?formatter? 屬性可以對(duì)輸入的內(nèi)容進(jìn)行格式化，通過 ?format-trigger? 屬性可以指定執(zhí)行格式化的時(shí)機(jī)，默認(rèn)在輸入時(shí)進(jìn)行格式化。

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="文本"
    :formatter="formatter"
    placeholder="在輸入時(shí)執(zhí)行格式化"
  />
  <van-field
    v-model="value2"
    label="文本"
    :formatter="formatter"
    format-trigger="onBlur"
    placeholder="在失焦時(shí)執(zhí)行格式化"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('');
    // 過濾輸入的數(shù)字
    const formatter = (value) => value.replace(/\d/g, '');

    return {
      value1,
      value2,
      formatter,
    };
  },
};

高度自適應(yīng)

對(duì)于 textarea，可以通過 ?autosize? 屬性設(shè)置高度自適應(yīng)。

<van-cell-group inset>
  <van-field
    v-model="message"
    rows="1"
    autosize
    label="留言"
    type="textarea"
    placeholder="請(qǐng)輸入留言"
  />
</van-cell-group>

顯示字?jǐn)?shù)統(tǒng)計(jì)

設(shè)置 ?maxlength? 和 ?show-word-limit? 屬性后會(huì)在底部顯示字?jǐn)?shù)統(tǒng)計(jì)。

<van-cell-group inset>
  <van-field
    v-model="message"
    rows="2"
    autosize
    label="留言"
    type="textarea"
    maxlength="50"
    placeholder="請(qǐng)輸入留言"
    show-word-limit
  />
</van-cell-group>

輸入框內(nèi)容對(duì)齊

通過 ?input-align? 屬性可以設(shè)置輸入框內(nèi)容的對(duì)齊方式，可選值為 ?center?、?right?。

<van-cell-group inset>
  <van-field
    v-model="value"
    label="文本"
    placeholder="輸入框內(nèi)容右對(duì)齊"
    input-align="right"
  />
</van-cell-group>

輸入框文本位置

通過 ?label-align? 屬性可以設(shè)置輸入框文本的位置，可選值為 ?center?、?right?、?top?。

<van-cell-group inset>
  <van-field
    v-model="value"
    label="手機(jī)號(hào)"
    placeholder="請(qǐng)輸入手機(jī)號(hào)"
    label-align="top"
  />
</van-cell-group>

API

Props

Events

方法

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

類型定義

組件導(dǎo)出以下類型定義：

import type {
  FieldType,
  FieldRule,
  FieldProps,
  FieldInstance,
  FieldTextAlign,
  FieldRuleMessage,
  FieldClearTrigger,
  FieldFormatTrigger,
  FieldRuleValidator,
  FiledRuleFormatter,
  FieldValidateError,
  FieldAutosizeConfig,
  FieldValidateTrigger,
  FieldValidationStatus,
} from 'vant';

?FieldInstance? 是組件實(shí)例的類型，用法如下：

import { ref } from 'vue';
import type { FieldInstance } from 'vant';

const fieldRef = ref<FieldInstance>();

fieldRef.value?.focus();

Slots

主題定制

樣式變量

組件提供了下列 CSS 變量，可用于自定義樣式，使用方法請(qǐng)參考 ConfigProvider 組件。

常見問題

設(shè)置 type 為 number 后，為什么 input 標(biāo)簽的類型仍為 text?

HTML 原生的 ?type="number"? 屬性在 iOS 和 Android 系統(tǒng)上都存在一定問題，比如 maxlength 屬性不生效、無法獲取到完整的輸入內(nèi)容等。因此設(shè)置 type 為 ?number? 時(shí)，F(xiàn)ield 不會(huì)使用原生的 ?type="number"? 屬性，而是用現(xiàn)代瀏覽器支持的 inputmode 屬性來控制輸入鍵盤的類型。

為什么 v-model 綁定的值被更新為 string 類型？

Field 組件內(nèi)部會(huì)將傳入的 v-model 格式化為 string 類型，便于組件內(nèi)部進(jìn)行處理。

如果你希望在 v-model 上綁定 number 類型，可以使用 Vue 提供的 .number 修飾符。

<van-field v-model.number="value" type="tel" />

在桌面端點(diǎn)擊清除按鈕無效？

清除按鈕監(jiān)聽是的移動(dòng)端 Touch 事件，參見桌面端適配。