Field

QField 组件提供了表单组件的通用方法,它可以使用 :model-value (或者 v-model,如果您要使用 clearable 的话)来绑定组件内的数据。还支持设置标签,提示信息,错误验证以及一系列的样式和颜色。

QField 允许您在其中展示任意的表单控件(实际上任何内容都可以),只需要将其放在 control 插槽中即可。

WARNING

不要再使用 QField 封装 QInput, QFile 或 QSelect,因为它们已经继承了 QField。

QField API

Loading QField API...

Design

TIP

下面的示例使用简单的文本内容只是为了向您展示 QField 可以使用的外观设计。要查看封装真实组件的示例,请参见“基本功能”部分。

WARNING

QField 不会(也不应该)管理您的 control 插槽内容,所以如果您在使用 label 属性,那么最好也声明一下stack-label 属性,否则,当 QField 未聚焦时,它可能会与您的控件重叠。

预览

您只能给 QField 使用一种主要的外观设计款式(filled, outlined, standout, borderless),不能使用多个,因为它们是互相排斥的。




着色




Standard-标准




Filled-填充




Outlined-轮廓




Standout-突出




其中一个很合适的的用例就是将 Standout 模式的 QField 用在 QToolbar 中:




Borderless-无边框

无边框(borderless)设计允许您无缝地将 QField 集成到其他组件中,而无需 QField 在其周围绘制边框或更改其背景颜色:




圆形边框

圆形(rounded)属性只能与填充,轮廓和突出的设计(Filled, Outlined 和 Standout )一起工作,如下面的例子所示:




方形边框

方形(square )属性只能与填充,轮廓和突出的设计(Filled, Outlined 和 Standout )一起工作,如下面的例子所示:




黑色背景




基础特性

可清除的

作为辅助,您可以使用 clearable 属性,这样用户可以通过附加的图标将数据重置为 null。下面第二个示例等价于使用 clearable

WARNING

如果使用 clearable 那么您必须使用 v-model 或者监听 @update:model-value 事件并更新其值。




控件类型

任何您放置在 control 插槽中的内容,都会作为 QFiled 组件的内容展示。我们提供了一些示例:




TIP

大部分的表单控件都是可见的,所以如果您在使用 label 属性,那么最好也声明一下stack-label 属性,否则,当 QField 未聚焦时,它可能会与您的控件重叠。

前缀和后缀




自定义标签

使用 label 插槽可以自定义标签或使用 QTooltip 添加特殊功能。

TIP

不要忘记设置 label-slot 属性。

如果要与标签(QTooltip)的内容交互,请在插槽中的元素上添加all-pointer-events CSS 类。




插槽中使用 “submit” 类型的 QBtn

WARNING

当将类型为 “submit” 的 QBtn 放置在 QField、QInput 或 QSelect 的 “before”、“after” 、“prepend” 或 “append” 插槽中时,您还应该在有问题的 QBtn 上添加 @click 事件。该事件应调用提交表单的方法。此类插槽中的所有点击事件均不会传播到其父元素。

加载状态




验证

内部验证

您可以使用 :rules 属性来对 QField 进行验证。声明一个规则数组或自定义的验证器。自定义的验证器应该是一个函数,当验证成功时返回 true,验证失败时返回 String 类型的错误信息。

TIP

默认情况下,规则的改变不会触发一次新的验证,直到绑定的数据发生变化。为了在规则改变时触发一次验证,您可以使用 reactive-rules 布尔属性,缺点是会降低性能(所以当您真的需要时在使用它),通过使用计算属性作为规则的值(而不是在 vue 模板中内联指定它们),可以稍微减轻这种情况。

一个规则的格式如下:

value => condition || errorMessage

示例:

value => value < 10 || 'Value should be lower'

您可以通过调用 QField 的 resetValidation() 方法来重置验证。







如果您设置了 lazy-rules,验证会在第一次失去焦点后才会开始。如果将 lazy-rules 设置为 ondemand 字符串,那么验证只有在手动调用了 QField 组件的 validate() 方法之后才会触发,或者是包裹它的 QForm 触发了提交事件。




异步规则

通过使用 async/await 或直接返回一个 Promise,规则也可以是异步的。

TIP

考虑将异步规则与 debounce 属性相结合,以避免在每次按键时立即调用异步规则,这可能会影响性能。




外部验证

您还可以使用外部验证,并且只传递 errorerror-message(启用 bottom-slots 插槽以显示此错误消息)。

TIP

根据您的需求,您可能需要 Vuelidate(我们推荐的方法)或者别的验证库连接到 QField。




您还可以为错误消息自定义插槽:




类型定义

export type EmbeddedValidationRule =
  | "date"
  | "time"
  | "fulltime"
  | "timeOrFulltime"
  | "email"
  | "hexColor"
  | "hexaColor"
  | "hexOrHexaColor"
  | "rgbColor"
  | "rgbaColor"
  | "rgbOrRgbaColor"
  | "hexOrRgbColor"
  | "hexaOrRgbaColor"
  | "anyColor";

type EmbeddedValidationRuleFn = (value: any) => boolean;
export type ValidationRule<T = any> =
  | EmbeddedValidationRule
  | ((
      value: T,
      rules: Record<EmbeddedValidationRule, EmbeddedValidationRuleFn>,
    ) => boolean | string | Promise<boolean | string>);