Vue.js

外觀

本頁目錄

表單輸入綁定 ​

在前端處理表單時，我們常常需要將表單輸入框的內容同步給 JavaScript 中相應的變量。手動連接值綁定和更改事件監聽器可能會很麻煩：

template
<input
  :value="text"
  @input="event => text = event.target.value">

v-model 指令幫我們簡化了這一步驟：

template
<input v-model="text">

另外，v-model 還可以用於各種不同類型的輸入，<textarea>、<select> 元素。它會根據所使用的元素自動使用對應的 DOM 屬性和事件組合：

  • 文本類型的 <input> 和 <textarea> 元素會綁定 value property 並偵聽 input 事件；
  • <input type="checkbox"> 和 <input type="radio"> 會綁定 checked property 並偵聽 change 事件；
  • <select> 會綁定 value property 並偵聽 change 事件。

注意

v-model 會忽略任何表單元素上初始的 value、checked 或 selected attribute。它將始終將當前綁定的 JavaScript 狀態視為數據的正確來源。你應該在 JavaScript 中使用data 選項響應式系統的 API來聲明該初始值。

基本用法 ​

文本 ​

template
<p>Message is: {{ message }}</p>
<input v-model="message" placeholder="edit me" />

Message is:

在演練場中嘗試一下

在演練場中嘗試一下

注意

對於需要使用 IME 的語言 (中文，日文和韓文等)，你會發現 v-model 不會在 IME 輸入還在拼字階段時觸發更新。如果你的確想在拼字階段也觸發更新，請直接使用自己的 input 事件監聽器和 value 綁定而不要使用 v-model。

多行文本 ​

template
<span>Multiline message is:</span>
<p style="white-space: pre-line;">{{ message }}</p>
<textarea v-model="message" placeholder="add multiple lines"></textarea>
Multiline message is:

在演練場中嘗試一下

在演練場中嘗試一下

注意在 <textarea> 中是不支持插值表達式的。請使用 v-model 來替代：

template
<!-- 錯誤 -->
<textarea>{{ text }}</textarea>

<!-- 正確 -->
<textarea v-model="text"></textarea>

複選框 ​

單一的複選框，綁定布爾類型值：

template
<input type="checkbox" id="checkbox" v-model="checked" />
<label for="checkbox">{{ checked }}</label>

在演練場中嘗試一下

在演練場中嘗試一下

我們也可以將多個複選框綁定到同一個數組或集合的值：

js
const checkedNames = ref([])
js
export default {
  data() {
    return {
      checkedNames: []
    }
  }
}
template
<div>Checked names: {{ checkedNames }}</div>

<input type="checkbox" id="jack" value="Jack" v-model="checkedNames">
<label for="jack">Jack</label>

<input type="checkbox" id="john" value="John" v-model="checkedNames">
<label for="john">John</label>

<input type="checkbox" id="mike" value="Mike" v-model="checkedNames">
<label for="mike">Mike</label>
Checked names: []

在這個例子中，checkedNames 數組將始終包含所有當前被選中的框的值。

在演練場中嘗試一下

在演練場中嘗試一下

單選按鈕 ​

template
<div>Picked: {{ picked }}</div>

<input type="radio" id="one" value="One" v-model="picked" />
<label for="one">One</label>

<input type="radio" id="two" value="Two" v-model="picked" />
<label for="two">Two</label>
Picked:

在演練場中嘗試一下

在演練場中嘗試一下

選擇器 ​

單個選擇器的示例如下：

template
<div>Selected: {{ selected }}</div>

<select v-model="selected">
  <option disabled value="">Please select one</option>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
Selected:

在演練場中嘗試一下

在演練場中嘗試一下

注意

如果 v-model 表達式的初始值不匹配任何一個選擇項，<select> 元素會渲染成一個“未選擇”的狀態。在 iOS 上，這將導致用戶無法選擇第一項，因為 iOS 在這種情況下不會觸發一個 change 事件。因此，我們建議提供一個空值的禁用選項，如上面的例子所示。

多選 (值綁定到一個數組)：

template
<div>Selected: {{ selected }}</div>

<select v-model="selected" multiple>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
Selected: []

在演練場中嘗試一下

在演練場中嘗試一下

選擇器的選項可以使用 v-for 動態渲染：

js
const selected = ref('A')

const options = ref([
  { text: 'One', value: 'A' },
  { text: 'Two', value: 'B' },
  { text: 'Three', value: 'C' }
])
js
export default {
  data() {
    return {
      selected: 'A',
      options: [
        { text: 'One', value: 'A' },
        { text: 'Two', value: 'B' },
        { text: 'Three', value: 'C' }
      ]
    }
  }
}
template
<select v-model="selected">
  <option v-for="option in options" :value="option.value">
    {{ option.text }}
  </option>
</select>

<div>Selected: {{ selected }}</div>

在演練場中嘗試一下

在演練場中嘗試一下

值綁定 ​

對於單選按鈕，複選框和選擇器選項，v-model 綁定的值通常是靜態的字符串 (或者對複選框是布爾值)：

template
<!-- `picked` 在被選擇時是字符串 "a" -->
<input type="radio" v-model="picked" value="a" />

<!-- `toggle` 只會為 true 或 false -->
<input type="checkbox" v-model="toggle" />

<!-- `selected` 在第一項被選中時為字符串 "abc" -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>

但有時我們可能希望將該值綁定到當前組件實例上的動態數據。這可以通過使用 v-bind 來實現。此外，使用 v-bind 還使我們可以將選項值綁定為非字符串的數據類型。

複選框 ​

template
<input
  type="checkbox"
  v-model="toggle"
  true-value="yes"
  false-value="no" />

true-value 和 false-value 是 Vue 特有的 attributes，僅支持和 v-model 配套使用。這裡 toggle 屬性的值會在選中時被設為 'yes'，取消選擇時設為 'no'。你同樣可以通過 v-bind 將其綁定為其他動態值：

template
<input
  type="checkbox"
  v-model="toggle"
  :true-value="dynamicTrueValue"
  :false-value="dynamicFalseValue" />

提示

true-value 和 false-value attributes 不會影響 value attribute，因為瀏覽器在表單提交時，並不會包含未選擇的複選框。為了保證這兩個值 (例如：“yes”和“no”) 的其中之一被表單提交，請使用單選按鈕作為替代。

單選按鈕 ​

template
<input type="radio" v-model="pick" :value="first" />
<input type="radio" v-model="pick" :value="second" />

pick 會在第一個按鈕選中時被設為 first，在第二個按鈕選中時被設為 second。

選擇器選項 ​

template
<select v-model="selected">
  <!-- 內聯對象字面量 -->
  <option :value="{ number: 123 }">123</option>
</select>

v-model 同樣也支持非字符串類型的值綁定！在上面這個例子中，當某個選項被選中，selected 會被設為該對象字面量值 { number: 123 }。

修飾符 ​

.lazy ​

默認情況下，v-model 會在每次 input 事件後更新數據 (IME 拼字階段的狀態例外)。你可以添加 lazy 修飾符來改為在每次 change 事件後更新數據：

template
<!-- 在 "change" 事件後同步更新而不是 "input" -->
<input v-model.lazy="msg" />

.number ​

如果你想讓用戶輸入自動轉換為數字，你可以在 v-model 後添加 .number 修飾符來管理輸入：

template
<input v-model.number="age" />

如果該值無法被 parseFloat() 處理，那麼將返回原始值。

number 修飾符會在輸入框有 type="number" 時自動啟用。

.trim ​

如果你想要默認自動去除用戶輸入內容中兩端的空格，你可以在 v-model 後添加 .trim 修飾符：

template
<input v-model.trim="msg" />

組件上的 v-model ​

如果你還不熟悉 Vue 的組件，那麼現在可以跳過這個部分。

HTML 的內置表單輸入類型並不一定足以滿足所有需求。幸運的是，我們可以使用 Vue 構建具有自定義行為的可複用輸入組件，並且這些輸入組件也支持 v-model！要了解更多關於此的內容，請在組件指引中閱讀配合 v-model 使用。

在 GitHub 上編輯此頁