QInput 组件用于捕获用户的文本输入。它使用 v-model，类似于常规输入框。它支持错误提示和表单验证，并提供多种样式、颜色和类型供选择。

设计

颜色

Standard（标准样式）

Filled（填充样式）

Outlined（轮廓样式）

Standout（凸显样式）

Standout 设计最典型的使用场景之一是在 QToolbar 中：

Borderless（无边框样式）

borderless 设计可以让 QInput 无缝融入其他组件，不会绘制边框或改变背景色：

圆角设计

rounded 属性仅在 Filled、Outlined 和 Standout 设计下生效，如下方示例所示：

直角边框

square 属性仅在 Filled、Outlined 和 Standout 设计下有意义，如下方示例所示：

强制深色模式

基础功能

原生属性

所有设置在 QInput 上但不在 API 中 props 列表里的属性，都会被透传到原生元素（input 或 textarea）上。例如：autocomplete、placeholder 等。

请参考以下资源了解更多原生属性（对于 input 还需注意每种 type 的特有属性）：

• input
• textarea

可清除

使用 clearable 属性可以让用户通过一个附加图标将 model 数据重置为 null。下方示例中第二个 QInput 的效果等价于使用 clearable。

输入类型

以下 QInput 使用 type 属性来渲染对应的原生 <input type="..."> 元素。

数字类型输入

使用 v-model.number（注意 number 修饰符）配合 type="number" 属性：

文件类型输入

文本域

当您需要 QInput 随内容自动增高时，可以使用 autogrow 属性：

前缀和后缀

自定义标签

通过 label 插槽，您可以自定义标签的外观或添加特殊功能，如 QTooltip。

阴影文字

在插槽中使用 type=“submit” 的 QBtn

model 防抖

防抖的作用在于：当您监听 model 数据并执行开销较大的操作时，可以让用户先输入完毕再触发 model 更新，而不是每次按键都更新。

加载状态

输入掩码

您可以通过 mask 属性来强制或引导用户按照特定格式输入。

以下是默认的掩码标记。如需自定义标记，请参阅下一节。

QInput 的 mask 属性有一些内置辅助格式：完整列表。您可以直接使用它们（例如：“phone”、“card”），也可以编写自定义的掩码字符串。

unmasked-value 在以下场景非常有用：比如您希望强制用户按照特定格式输入，但 model 数据中保存的是原始值（不含掩码字符）：

reverse-fill-mask 在以下场景非常有用：您希望用户从末尾开始填充掩码，并允许输入长度不固定：

自定义掩码标记

v2.18.4+

您还可以在默认标记的基础上定义自定义掩码标记，甚至覆盖部分或全部默认标记。

自定义掩码标记的语法必须与默认标记一致。请注意，transform 属性是可选的。

使用第三方掩码处理器

您可以通过少量调整轻松将任何第三方掩码处理器与 QInput 配合使用。

假设您有这样一个 QInput：

<q-input
  filled
  v-model="price"
  label="Price with 2 decimals"
  mask="#.##"
  fill-mask="#"
  reverse-fill-mask
  hint="Mask: #.00"
  input-class="text-right"
/>

可以使用 v-money 指令：

<q-field filled v-model="price" label="Price with v-money directive" hint="Mask: $ #,###.00 #">
  <template v-slot:control="{ id, floatingLabel, modelValue, emitValue }">
    <input
      :id="id"
      class="q-field__input text-right"
      :value="modelValue"
      @change="e => emitValue(e.target.value)"
      v-money="moneyFormatForDirective"
      v-show="floatingLabel"
    />
  </template>
</q-field>

moneyFormatForDirective: {
  decimal: '.',
  thousands: ',',
  prefix: '$ ',
  suffix: ' #',
  precision: 2,
  masked: false /* doesn't work with directive */
}

或者使用 money 组件：

<q-field filled v-model="price" label="Price with v-money component" hint="Mask: $ #,###.00 #">
  <template v-slot:control="{ id, floatingLabel, modelValue, emitValue }">
    <money
      :id="id"
      class="q-field__input text-right"
      :model-value="modelValue"
      @update:model-value="emitValue"
      v-bind="moneyFormatForComponent"
      v-show="floatingLabel"
    />
  </template>
</q-field>

moneyFormatForComponent: {
  decimal: '.',
  thousands: ',',
  prefix: '$ ',
  suffix: ' #',
  precision: 2,
  masked: true
}

验证

内部验证

您可以通过 :rules 属性来验证 QInput 组件。可以指定内置规则数组或自定义验证函数。自定义验证函数需要在验证通过时返回 true，验证失败时返回包含错误信息的 String。

这样您就可以使用如下简洁的规则写法：

(value) => condition || errorMessage;

例如：

(value) => value.includes("Hello") || "Field must contain word Hello";

您可以通过调用 QInput 上的 resetValidation() 方法来重置验证状态。

QInput 的 rules 属性有一些内置辅助规则：完整列表。您可以直接使用它们（例如：“date”、“time”、“hexColor”、“rgbOrRgbaColor”、“anyColor”），也可以编写自定义规则。

如果设置了 lazy-rules，验证将在首次失焦后才开始。如果将 lazy-rules 设置为 ondemand 字符串，则仅在手动调用组件的 validate() 方法或外层 QForm 提交时才会触发验证。

异步规则

规则也支持异步，可以使用 async/await 或直接返回 Promise。

外部验证

您也可以使用外部验证，只需传入 error 和 error-message 属性即可（需启用 bottom-slots 来显示错误信息）。

您还可以自定义错误信息的插槽：

原生表单提交

当处理带有 action 和 method 的原生表单时（例如将 Quasar 与 ASP.NET 控制器一起使用），您需要在 QInput 上指定 name 属性，否则 formData 将不会包含该字段的数据：