表单输入绑定

在前端处理表单时，我们通常需要将表单输入元素的状态与 JavaScript 中的对应状态同步。手动连接值绑定和更改事件监听器可能会很麻烦

模板

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

v-model 指令帮助我们简化上述操作

模板

<input v-model="text">

此外，v-model 可以用于不同类型的输入，如 <textarea> 和 <select> 元素。它将自动扩展到不同的 DOM 属性和事件对，根据所使用的元素而变化

具有文本类型的 <input> 和 <textarea> 元素使用 value 属性和 input 事件；
<input type="checkbox"> 和 <input type="radio"> 使用 checked 属性和 change 事件；
<select> 使用 value 作为属性，并使用 change 作为事件。

注意

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

基本用法

文本

模板

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

消息是

在游乐场中尝试

注意

对于需要输入法 (IME) 的语言（中文、日语、韩语等），您会注意到在 IME 组合期间 v-model 不会更新。如果您还想对这些更新做出响应，请使用您自己的 input 事件监听器和 value 绑定，而不是使用 v-model。

多行文本

模板

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

多行消息是

在游乐场中尝试

请注意，在 <textarea> 中的插值不起作用。请使用 v-model。

模板

<!-- bad -->
<textarea>{{ text }}</textarea>

<!-- good -->
<textarea v-model="text"></textarea>

复选框

单个复选框，布尔值

模板

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

false

在游乐场中尝试

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

const checkedNames = ref([])

export default {
  data() {
    return {
      checkedNames: []
    }
  }
}

模板

<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>

已选名字：[]

JackJohnMike

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

在游乐场中尝试

单选按钮

模板

<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>

选择

一个二

在游乐场中尝试

选择

单个选择

模板

<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>

已选择

在游乐场中尝试

注意

如果您的 v-model 表达式的初始值与任何选项都不匹配，则 <select> 元素将以“未选择”状态渲染。在 iOS 上，这会导致用户无法选择第一个选项，因为 iOS 在这种情况下不会触发更改事件。因此，建议提供一个带有空值的禁用选项，如上例所示。

多选（绑定到数组）

模板

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

<select v-model="selected" multiple>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>

已选择：[]

在游乐场中尝试

选择选项可以使用 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' }
      ]
    }
  }
}

模板

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

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

在游乐场中尝试

值绑定

对于单选框、复选框和选择选项，v-model 绑定值通常是静态字符串（对于复选框是布尔值）

模板

<!-- `picked` is a string "a" when checked -->
<input type="radio" v-model="picked" value="a" />

<!-- `toggle` is either true or false -->
<input type="checkbox" v-model="toggle" />

<!-- `selected` is a string "abc" when the first option is selected -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>

但有时我们可能想要将值绑定到当前活动实例的动态属性上。我们可以使用 v-bind 来实现这一点。此外，使用 v-bind 还允许我们将输入值绑定到非字符串值。

复选框

模板

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

true-value 和 false-value 是 Vue 特定的属性，只能与 v-model 一起使用。在此，当复选框被选中时，toggle 属性的值将设置为 'yes'，当未选中时设置为 'no'。您还可以使用 v-bind 将它们绑定到动态值。

模板

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

提示

由于浏览器在表单提交时不包括未选中的复选框，因此 true-value 和 false-value 属性不会影响输入的 value 属性。为了保证在表单中提交两个值之一（例如“是”或“否”），请使用单选按钮。

单选按钮

模板

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

当第一个单选按钮被选中时，pick 将设置为 first 的值，当第二个被选中时设置为 second 的值。

选择选项

模板

<select v-model="selected">
  <!-- inline object literal -->
  <option :value="{ number: 123 }">123</option>
</select>

v-model 还支持非字符串值的值绑定！在上面的示例中，当选项被选中时，selected 将设置为对象字面量的值 { number: 123 }。

修饰符

`.lazy`

默认情况下，v-model 在每次 input 事件后（如上所述，除 IME 组合外）同步输入与数据。您可以将 lazy 修饰符添加到同步后 change 事件。

模板

<!-- synced after "change" instead of "input" -->
<input v-model.lazy="msg" />

`.number`

如果您希望用户输入自动转换为数字，您可以将 number 修饰符添加到您的 v-model 输入。

模板

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

如果无法使用 parseFloat() 解析值，则使用原始（字符串）值。特别是，如果输入为空（例如用户清除输入字段后），则返回空字符串。此行为与 DOM 属性 valueAsNumber 不同。

如果输入具有 type="number"，则自动应用 number 修饰符。

`.trim`

如果您希望自动从用户输入中删除空白，您可以将 trim 修饰符添加到您的 v-model 输入。

模板

<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` 与组件