0.0.4

Form 表单 ​

表单由输入框、单选框、选择器、复选框等控件组成，用于收集、校验与提交数据。

TIP

组件已升级为 Flex 布局，替代旧的浮动布局。

典型表单 ​

包含输入框、选择器、单选框、复选框等。

每个表单项需使用 form-item 作为容器包裹控件。

Activity name
Activity zone
please select your zone
Activity time
-
Instant delivery
Activity type
Resources
Activity form

TIP

W3C 规定：

当表单中仅有一个单行文本输入框时，用户在该字段按下 Enter 应被视为提交表单。

若需禁止该行为，可在 <u-form> 上添加 @submit.prevent。

行内表单 ​

垂直空间有限且表单较简单时，可在一行内排布。

将 inline 设为 true。

Approved by
Activity zone
Activity zone
Activity time

对齐方式 ​

标签可按设计选择不同对齐。

可为单个 u-form-item 设置 label-position；为空时继承 u-form 的 label-position。

label-position 为 top 时标签在控件上方；为 left 时标签在左侧（通常需配合 label-width）。

Form Align
Form Item Align
Name
Activity zone
Activity form

校验 ​

通过规则校验数据，便于发现与修正错误。

在 Form 上设置 rules，并在需要校验的 FormItem 上设置对应的 prop。更多规则写法见 async-validator。

Activity name
Activity zone
Activity zone
Activity count
Activity count
Activity time
-
Instant delivery
Activity location
Activity type
Resources
Activity form

自定义校验规则 ​

演示如何实现二次密码确认等自定义规则。

使用 status-icon 以图标展示校验结果。

TIP

自定义校验函数必须被调用。进阶用法见 async-validator。

动态增删表单项 ​

除在表单上一次性传入全部规则外，也可在单个表单项上动态增删规则。

Email
Domain0

数字校验 ​

数字校验建议在 v-model 上使用 .number 修饰符，将字符串转为数值。

age

TIP

当 u-form-item 嵌套在另一个 u-form-item 内时，内层标签宽度为 0；若需要可单独设置内层 label-width。

尺寸 ​

表单内组件默认继承表单的 size；FormItem 也支持 size。

若不希望某个控件继承尺寸，可单独为其设置 size。


Activity name
Activity zone
please select your zone
Activity time
-
Activity type
Resources

无障碍 ​

当 u-form-item 内仅有一个输入类控件（或选择框、复选框等相关控件）时，标签会自动关联该控件。若同一 u-form-item 内有多个控件，表单项会被赋予 WAI-ARIA 的 group 角色，此时需自行保证每个控件具备可读的辅助标签。

Full Name
Your Information

表单 API ​

Form 属性 ​

名称说明类型默认值
model表单数据模型object—
rules校验规则object—
inline是否行内表单booleanfalse
label-position标签位置；为 left/right 时通常需设置 label-widthenumright
label-width标签宽度，如 '50px'；子级表单项会继承；支持 autostring / number''
label-suffix标签后缀string''
hide-required-asterisk是否隐藏必填星号booleanfalse
require-asterisk-position星号位置enumleft
show-message是否显示错误信息booleantrue
inline-message错误信息是否与表单项行内展示booleanfalse
status-icon是否显示校验状态图标booleanfalse
validate-on-rule-changerules 变更时是否重新校验booleantrue
size表单内控件尺寸enum—
disabled是否禁用表单内控件；以子组件自身配置为准booleanfalse
scroll-to-error校验失败时是否滚动到第一项错误booleanfalse
scroll-into-view-options校验失败滚动行为，参见 scrollIntoViewobject / booleantrue

Form 事件 ​

名称说明类型
validate任一表单项校验后触发Function

Form 插槽 ​

名称说明子标签
default自定义默认内容FormItem

Form 暴露 ​

名称说明类型
validate校验整个表单；可传入回调或返回 PromiseFunction
validateField校验指定字段Function
resetFields重置字段并清除校验结果Function
scrollToField滚动到指定字段Function
clearValidate清除全部或指定字段的校验信息Function
fields获取全部表单项上下文array
getField获取单个表单项上下文Function
setInitialValues设置字段初始值；调用 resetFields 时将恢复到这些值Function

表单项 API ​

FormItem 属性 ​

名称说明类型默认值
prop对应 model 的键名，可为路径（如 a.b.0 或 ['a','b','0']）；使用 validate、resetFields 时必填string / string[]—
label标签文本string—
label-position标签位置；为 left/right 时需设置 label-width；默认继承表单enum''
label-width标签宽度；支持 autostring / number—
required是否必填；未设置时由规则推断boolean—
rules校验规则，见下表；进阶见 async-validatorobject—
error手动设置错误文案；设置后立即显示为错误态string—
show-message是否显示错误信息booleantrue
inline-message行内展示错误信息booleanfalse
size表单项内控件尺寸enum—
for同原生 label 的 forstring—
validate-status校验状态enum—

FormItemRule ​

名称说明类型默认值
trigger校验触发时机enum—

TIP

若不希望根据输入事件触发校验，可在对应输入类组件（<u-input>、<u-radio>、<u-select> 等）上将 validate-event 设为 false。

FormItem 插槽 ​

名称说明类型
default表单项内容—
label自定义标签区域object
error自定义错误信息展示object

FormItem 暴露 ​

名称说明类型
size表单项尺寸object
validateMessage校验提示文案object
validateState校验状态object
validate校验当前表单项Function
resetField重置当前字段并清除校验结果Function
clearValidate清除当前字段校验状态Function
setInitialValue设置当前字段初始值；调用 resetField 时将恢复到该值Function

类型声明 ​

展开类型声明
ts
type Arrayable<T> = T | T[]

type FormValidationResult = Promise<boolean>

// ValidateFieldsError: 见 [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
type FormValidateCallback = (
  isValid: boolean,
  invalidFields?: ValidateFieldsError
) => Promise<void> | void

// RuleItem: 见 [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
interface FormItemRule extends RuleItem {
  trigger?: Arrayable<string>
}

type Primitive = null | undefined | string | number | boolean | symbol | bigint
type BrowserNativeObject = Date | FileList | File | Blob | RegExp
type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
  ? false
  : true
type ArrayMethodKey = keyof any[]
type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, ArrayMethodKey>
type ArrayKey = number
type PathImpl<K extends string | number, V> = V extends
  | Primitive
  | BrowserNativeObject
  ? `${K}`
  : `${K}` | `${K}.${Path<V>}`
type Path<T> =
  T extends ReadonlyArray<infer V>
    ? IsTuple<T> extends true
      ? {
          [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K]>
        }[TupleKey<T>]
      : PathImpl<ArrayKey, V>
    : {
        [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K]>
      }[keyof T]
type FieldPath<T> = T extends object ? Path<T> : never
// MaybeRef: 见 [@vueuse/core](https://github.com/vueuse/vueuse/blob/main/packages/shared/utils/types.ts)
// UnwrapRef: 见 [vue](https://github.com/vuejs/core/blob/main/packages/reactivity/src/ref.ts)
type FormRules<T extends MaybeRef<Record<string, any> | string> = string> =
  Partial<
    Record<
      UnwrapRef<T> extends string ? UnwrapRef<T> : FieldPath<UnwrapRef<T>>,
      Arrayable<FormItemRule>
    >
  >

type FormItemValidateState = (typeof formItemValidateStates)[number]
type FormItemProps = ExtractPropTypes<typeof formItemProps>

type FormItemContext = FormItemProps & {
  $el: HTMLDivElement | undefined
  size: ComponentSize
  validateMessage: string
  validateState: FormItemValidateState
  isGroup: boolean
  labelId: string
  inputIds: string[]
  hasLabel: boolean
  fieldValue: any
  propString: string
  addInputId: (id: string) => void
  removeInputId: (id: string) => void
  validate: (
    trigger: string,
    callback?: FormValidateCallback
  ) => FormValidationResult
  resetField(): void
  clearValidate(): void
  setInitialValue: (value: any) => void
}