uView Pro X

简体中文

English

简体中文

English

主题

Form 表单 ​

17:06

说明 ​

表单校验容器，配合任意输入类组件使用。ux-form 负责收集表单内的 ux-form-item，向下提供 model / rules / error-type / label-* / size 等配置，并对外暴露 validate()、resetFields()、setRules()；ux-form-item 是单个表单项，用 prop 关联 model 中的字段（支持 a.b 嵌套路径），负责渲染 label、必填星号、左右图标与错误提示，并在字段 blur / change 时按规则里的 trigger 触发校验。两者通过 provide/inject 协作，表单项内可放 ux-input、ux-textarea、ux-radio-group、ux-checkbox-group、ux-picker 等任意输入组件。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持

示例 ​

基础用法 ​

通过 rules 配置校验规则，validate() 校验全部字段，resetFields() 重置表单。

查看源码
vue
<template>
    <ux-form ref="formRef" :model="model" :rules="rules" :error-type="['message']" label-position="left">
        <ux-form-item label="姓名" prop="name" required left-icon="account">
            <ux-input v-model="model.name" placeholder="请输入姓名" border />
        </ux-form-item>
        <ux-form-item label="密码" prop="password">
            <ux-input v-model="model.password" type="password" :password-icon="true" placeholder="请输入密码" border />
        </ux-form-item>
        <ux-form-item label="手机号" prop="phone">
            <ux-input v-model="model.phone" type="number" placeholder="请输入手机号" border />
        </ux-form-item>
        <ux-form-item label="性别" prop="sex">
            <ux-input v-model="model.sex" type="select" :select-open="pickerShow" placeholder="请选择性别" border @click="pickerShow = true" />
        </ux-form-item>
    </ux-form>
    <ux-button type="primary" @click="onSubmit">提交</ux-button>
    <ux-button type="default" @click="onReset">重置</ux-button>
    <ux-picker v-model="pickerShow" mode="selector" :columns="columns" @confirm="onConfirm" />
</template>

<script setup lang="uts">
import type { FormRule } from '@/uni_modules/uview-pro-x';
import type { PickerOption } from '@/uni_modules/uview-pro-x';

const formRef = ref<any | null>(null);
const pickerShow = ref<boolean>(false);

const model = ref<UTSJSONObject>(new UTSJSONObject());
model.value['name'] = '';
model.value['password'] = '';
model.value['phone'] = '';
model.value['sex'] = '';

const rules = ref<Map<string, FormRule[]>>(new Map([
    ['name', [
        { required: true, message: '请输入姓名', trigger: 'blur' },
        { min: 2, max: 5, message: '姓名长度在 2 到 5 个字符', trigger: 'change' }
    ]],
    ['password', [
        { required: true, message: '请输入密码', trigger: 'blur' }
    ]],
    ['phone', [
        { required: true, message: '请输入手机号', trigger: 'blur' },
        {
            validator: (value: any | null): boolean | string => {
                if (value == null || value === '') return true;
                if (String(value).length !== 11) return '手机号码不正确';
                return true;
            },
            trigger: 'change'
        }
    ]],
    ['sex', [{ required: true, message: '请选择性别', trigger: 'change' }]]
]));

const columns: PickerOption[][] = [
    [
        { text: '男', value: 'male' },
        { text: '女', value: 'female' }
    ]
];

const onSubmit = () => {
    formRef.value?.validate().then((valid: boolean) => {
        if (valid) {
            uni.showToast({ title: '提交成功', icon: 'success' });
        } else {
            uni.showToast({ title: '校验失败', icon: 'none' });
        }
    });
};

const onReset = () => {
    formRef.value?.resetFields();
};

const onConfirm = (event: UTSJSONObject): void => {
    const options = event['selectedOptions'] as PickerOption[];
    if (options != null && options.length > 0) {
        model.value['sex'] = options[0].text;
    }
};
</script>

参数配置 ​

查看源码
vue
<template>
    <ux-form :model="model" :error-type="errorType" :label-position="labelPosition">
        <ux-form-item label="错误提示方式" prop="name">
            <ux-input v-model="model.name" placeholder="触发校验查看错误提示" border />
        </ux-form-item>
    </ux-form>
    <view class="btn-wrap">
        <ux-button size="small" :type="errorType[0] === 'message' ? 'primary' : 'default'" @click="setErrorType('message')">message</ux-button>
        <ux-button size="small" :type="errorType[0] === 'toast' ? 'primary' : 'default'" @click="setErrorType('toast')">toast</ux-button>
        <ux-button size="small" :type="labelPosition === 'top' ? 'primary' : 'default'" @click="labelPosition = 'top'">标签在上</ux-button>
        <ux-button size="small" :type="labelPosition === 'left' ? 'primary' : 'default'" @click="labelPosition = 'left'">标签在左</ux-button>
    </view>
</template>

<script setup lang="uts">
import type { FormErrorType } from '@/uni_modules/uview-pro-x';

const model = ref<UTSJSONObject>(new UTSJSONObject());
model.value['name'] = '';

const errorType = ref<FormErrorType[]>(['message']);
const labelPosition = ref<'left' | 'top'>('left');

const setErrorType = (value: string) => {
    errorType.value = [value as FormErrorType];
};
</script>

<style scoped>
.btn-wrap {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

API ​

Props ​

ux-form ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
model表单数据对象UTSJSONObject--
rules表单验证规则FormRules--
errorType错误提示方式FormErrorType[]--
borderBottom是否显示下划线边框booleantrue-
labelPositionlabel 位置FormLabelPosition'left'-
labelWidthlabel 宽度string | number45-
labelAlignlabel 对齐方式string'left'-
labelStylelabel 样式UTSJSONObject--
size组件大小string'default'-

ux-form-item ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
labelinput 的 label 提示语string''-
prop绑定的值string''-
borderBottom是否显示表单域的下划线边框string | boolean''-
labelPositionlabel 的位置string''-
labelWidthlabel 的宽度string | number''-
labelStylelabel 的样式UTSJSONObject--
labelAlignlabel 字体的对齐方式string''-
rightIcon右侧图标string''-
leftIcon左侧图标string''-
leftIconPrefix左侧图标的自定义前缀string'uicon'-
rightIconPrefix右侧图标的自定义前缀string'uicon'-
leftIconStyle左侧图标的样式UTSJSONObject--
rightIconStyle右侧图标的样式UTSJSONObject--
required是否显示左边的必填星号booleanfalse-
size表单内组件的大小string''-

Events ​

本页组件均无事件。

Slots ​

ux-form ​

插槽名说明版本
default表单内容，放置 ux-form-item-

ux-form-item ​

插槽名说明版本
leftIcon自定义左侧图标-
label自定义 label 内容-
default表单项内容，放置输入类组件（如 ux-input）-
rightIcon自定义右侧图标-
right自定义右侧内容-

方法 ​

通过 ref 获取 ux-form 实例后调用：

方法名说明参数返回值
validate校验全部已注册表单项，执行各字段的全部规则callback?: (valid: boolean, errorArr: ErrorItem[]) => voidPromise<boolean>，true 表示全部通过
resetFields重置全部表单项为初始值，并清除错误提示--
setRules动态替换校验规则rules: FormRules-

注意事项 ​

  1. prop 是校验与重置的前提：未设置 prop 的 ux-form-item 不会注册进表单，validate() 与 resetFields() 都会跳过它；prop 支持 a.b 嵌套路径。
  2. required 只负责显示左侧红色星号，真正的必填校验必须在 rules 里配置 required: true，两者互不替代。
  3. 校验触发时机由规则的 trigger 决定（blur / change）：trigger: 'change' 的规则不会在失焦时触发，反之亦然；整体调用 validate() 时会忽略 trigger，执行该字段的全部规则。
  4. error-type 为数组，可同时开启多种提示（默认 ['message', 'toast']）；数组里一旦包含 none，所有提示（含 message / border）都会关闭。toast 只弹出第一个出错字段的第一条错误。
  5. resetFields() 把字段还原为组件挂载时记录的初始值（支持嵌套路径），而不是清空为 ''。
  6. ux-form-item 的 size / label-position / label-width / label-align / border-bottom 未单独设置时，继承 ux-form 上的同名配置；border-bottom 在 ux-form 上默认 true。
  7. label 传空字符串时，label 区域宽度自动为 auto（此时 label-width 不生效）。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5