表单输入绑定

在处理前端表单时，我们经常需要将表单输入元素的状态与 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 属性和 input 事件；
<input type="checkbox"> 和 <input type="radio"> 使用 checked 属性和 change 事件；
<select> 使用 value 作为 prop，并使用 change 作为事件。

注意

v-model 会忽略在任何表单元素上找到的初始 value、checked 或 selected 属性。它始终会将当前绑定的 JavaScript 状态视为唯一可信来源。你应该在 JavaScript 端声明初始值，使用 data 选项响应式 API。

基础用法

文本

template

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

Message is:

在 Playground 中试试

注意

对于需要 IME 的语言（中文、日文、韩文等），你会注意到在 IME 组合输入期间 v-model 不会更新。如果你也想响应这些更新，请使用你自己的 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:

在 Playground 中试试

注意，<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>

false

在 Playground 中试试

我们也可以将多个复选框绑定到同一个数组或 Set 值：

const checkedNames = ref([])

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: []

JackJohnMike

在这种情况下，checkedNames 数组将始终包含当前选中的复选框的值。

在 Playground 中试试

单选按钮

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:

OneTwo

在 Playground 中试试

下拉选择

单项选择：

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:

在 Playground 中试试

注意

如果你的 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: []

在 Playground 中试试

可以使用 v-for 动态渲染选择选项：

const selected = ref('A')

const options = ref([
  { text: 'One', value: 'A' },
  { text: 'Two', value: 'B' },
  { text: 'Three', value: 'C' }
])

export default {
  data() {
    return {
      selected: 'A',
      options: [
        { text: 'One', value: 'A' },
        { text: 'Two', value: 'B' },
        { text: 'Three', value: 'C' }
      ]
    }
  }
}

template

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

<select v-model="selected">
  <option v-for="option in options" :value="option.value">
    {{ option.text }}
  </option>
</select>

Selected: A

在 Playground 中试试

值绑定

对于单选框、复选框和选择框选项，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 特有的属性，只能与 v-model 一起使用。这里，当复选框被勾选时，toggle 属性的值会被设置为 'yes'，未勾选时则设置为 'no'。你也可以使用 v-bind 将它们绑定到动态值：

template

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

提示

true-value 和 false-value 属性不会影响输入框的 value 属性，因为浏览器不会在表单提交中包含未勾选的复选框。为了保证表单中会提交两个值中的一个（例如 "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() 解析，则会改用原始的（字符串）值。特别地，如果输入框为空（例如用户清空输入字段后），则会返回空字符串。此行为与 DOM 属性 valueAsNumber 不同。

如果输入框的 type="number"，则会自动应用 number 修饰符。

`.trim`

如果你希望自动去除用户输入中的空白字符，可以在由 v-model 管理的输入框上添加 trim 修饰符：

template

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

组件上的 `v-model`

如果你还不熟悉 Vue 的组件，可以先跳过这一部分。

HTML 内置的输入类型并不总能满足你的需求。幸运的是，Vue 组件允许你构建可复用的输入组件，并拥有完全自定义的行为。这些输入组件甚至可以与 v-model 一起工作！要了解更多，请阅读组件指南中的与 v-model 一起使用。

在 GitHub 上编辑此页

表单输入绑定 ​

基础用法 ​

文本 ​

多行文本 ​

复选框 ​

单选按钮 ​

下拉选择 ​

值绑定 ​

复选框 ​

单选框 ​

选择框选项 ​

修饰符 ​

.lazy ​

.number ​

.trim ​

组件上的 v-model ​

表单输入绑定

基础用法

文本

多行文本

复选框

单选按钮

下拉选择

值绑定

复选框

单选框

选择框选项

修饰符

`.lazy`

`.number`

`.trim`

组件上的 `v-model`