Form 表单

表单目前包含输入框, 下拉选择, 开关等用户输入的组件。使用表单，您可以收集、验证和提交数据。

TIP

ps: 表单控件目前不全，待完善

基本用法

最基础的表单包括各种输入表单项，比如input、select、switch等。(目前只开发了这三个 🤣) 在每个 from 组件中，需要使用 from-item 组件来包裹每个表单项,用于获取值与校验。

<script lang="ts" setup>
import { reactive, ref } from "vue";
import { EcMessage } from "easy-collective-ui";

const form = reactive({
    name: "",
    region: "",
    delivery: false,
    desc: "",
});

const options = ref([
    { value: "beijing", label: "Zone One" },
    { value: "shanghai", label: "Zone Two" },
]);

const onSubmit = () => {
    EcMessage.success("submit!");
};
</script>

<template>
    <ec-form :model="form">
        <ec-form-item label="Activity name">
            <ec-input v-model="form.name" />
        </ec-form-item>
        <ec-form-item label="Activity zone">
            <ec-select v-model="form.region" placeholder="please select your zone" :options="options" />
        </ec-form-item>
        <ec-form-item label="Instant delivery">
            <ec-switch v-model="form.delivery" />
        </ec-form-item>
        <ec-form-item label="Activity form">
            <ec-input v-model="form.desc" type="textarea" />
        </ec-form-item>
        <ec-form-item>
            <ec-button type="primary" @click="onSubmit">Create</ec-button>
            <ec-button>Cancel</ec-button>
        </ec-form-item>
    </ec-form>
</template>

对齐方式

通过 label-position 属性可以控制表单项的左右对齐方式。

<script lang="ts" setup>
import { reactive, ref } from "vue";
import { EcMessage, type FormProps } from "easy-collective-ui";

const form = reactive({
    name: "",
    region: "",
    delivery: false,
    desc: "",
});
const options = ref([
    { value: "beijing", label: "Zone One" },
    { value: "shanghai", label: "Zone Two" },
]);
const labelPosition = ref<FormProps["labelPosition"]>("right");

const onSubmit = () => {
    EcMessage.success("submit");
};
</script>

<template>
    <ec-button-group size="small">
        <ec-button @click="labelPosition = 'left'"
            :type="labelPosition === 'left' ? 'primary' : 'info'">Left</ec-button>
        <ec-button @click="labelPosition = 'right'"
            :type="labelPosition === 'right' ? 'primary' : 'info'">Right</ec-button>
        <ec-button @click="labelPosition = 'top'" :type="labelPosition === 'top' ? 'primary' : 'info'">Top</ec-button>
    </ec-button-group>
    <div style="margin: 20px"></div>
    <ec-form :model="form" :label-position="labelPosition">
        <ec-form-item label="Activity name">
            <ec-input v-model="form.name" />
        </ec-form-item>
        <ec-form-item label="Activity zone">
            <ec-select v-model="form.region" placeholder="please select your zone" :options="options" />
        </ec-form-item>
        <ec-form-item label="Instant delivery">
            <ec-switch v-model="form.delivery" />
        </ec-form-item>
        <ec-form-item label="Activity form">
            <ec-input v-model="form.desc" type="textarea" />
        </ec-form-item>
        <ec-form-item>
            <ec-button type="primary" @click="onSubmit">Create</ec-button>
            <ec-button>Cancel</ec-button>
        </ec-form-item>
    </ec-form>
</template>

表单校验

通过 rules 属性可以设置表单项的校验规则。书写规则参考 async-validator。

<script lang="ts" setup>
import { reactive, ref } from "vue";
import { EcMessage, type FormInstance } from "easy-collective-ui";

const formRef = ref<FormInstance>();
const form = reactive({
    name: "",
    region: "",
    delivery: false,
    desc: "",
});

const options = ref([
    { value: "beijing", label: "Zone One" },
    { value: "shanghai", label: "Zone Two" },
]);

const rules = reactive({
    name: [
        { required: true, message: "请输入活动名称", trigger: "blur" },
        { min: 3, max: 5, message: "长度在 3 到 5 个字符", trigger: "blur" },
    ],
    region: [{ required: true, message: "请选择活动区域", trigger: "change" }],
    desc: [{ required: true, message: "请填写活动形式", trigger: "blur" }],
});

const onSubmit = () => {
    formRef.value?.validate().then((valid) => {
        if (valid) {
            EcMessage.success("submit!");
        }
    });
};

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

<template>
    <ec-form ref="formRef" :model="form" :rules="rules">
        <ec-form-item label="Activity name" prop="name">
            <ec-input v-model="form.name" />
        </ec-form-item>
        <ec-form-item label="Activity zone" prop="region">
            <ec-select v-model="form.region" placeholder="please select your zone" :options="options" />
        </ec-form-item>
        <ec-form-item label="Instant delivery" prop="delivery">
            <ec-switch v-model="form.delivery" />
        </ec-form-item>
        <ec-form-item label="Activity form" prop="desc">
            <ec-input v-model="form.desc" type="textarea" />
        </ec-form-item>
        <ec-form-item>
            <ec-button type="primary" @click="onSubmit">Create</ec-button>
            <ec-button @click="onReset">Reset</ec-button>
        </ec-form-item>
    </ec-form>
</template>

自定义校验规则

通过校验规则中的 validator 属性可以自定义校验规则。

<script lang="ts" setup>
import { reactive, ref } from "vue";
import { EcMessage, type FormInstance } from "easy-collective-ui";

const formRef = ref<FormInstance>();
const form = reactive({
    name: "",
    password: "",
    passwordConfirm: "",
});

const rules: any = reactive({
    name: [
        { required: true, message: "请输入活动名称", trigger: "blur" },
        { min: 3, max: 5, message: "长度在 3 到 5 个字符", trigger: "blur" },
    ],
    password: [{ required: true, trigger: "blur", message: "请输入密码" }],
    passwordConfirm: [
        {
            required: true,
            trigger: "blur",
            message: "请再次输入密码",
        },
        {
            validator: (_: typeof rules, value: string) => value === form.password,
            trigger: "blur",
            message: "两个密码必须相同",
        },
    ],
});

const onSubmit = async (instance?: FormInstance) => {
    const valid = await instance?.validate();
    if (!valid) return;
    EcMessage.success("submit!");
};

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

<template>
    <ec-form ref="formRef" :model="form" :rules="rules" label-position="top" @submit.prevent="onSubmit(formRef)">
        <ec-form-item label="Activity name" prop="name">
            <ec-input v-model="form.name" />
        </ec-form-item>
        <ec-form-item label="Password" prop="password">
            <ec-input v-model="form.password" type="password" />
        </ec-form-item>
        <ec-form-item label="Password Confirm" prop="passwordConfirm">
            <ec-input v-model="form.passwordConfirm" type="password" />
        </ec-form-item>
        <ec-form-item>
            <ec-button type="primary" native-type="submit">Create</ec-button>
            <ec-button @click="onReset">Reset</ec-button>
        </ec-form-item>
    </ec-form>
</template>

Form API

Props

Name	Description	Type	Default
model	表单数据	`Record<string, any>`	-
rules	校验规则	`FormRules`	-
disabled	是否禁用表单	`boolean`	`false`
label-position	标签位置	`enum`- `'left' \| 'top'\| right'`	right
label-width	标签宽度	`number`	-
label-suffix	标签后缀	`string`	-
show-message	是否显示提示	`boolean`	true
hide-required-asterisk	是否隐藏必填符号	`boolean`	false
required-asterisk-position	必填符号位置	`enum`-`'left' \| 'right'`	`right`

Events

Name	Description	Type
validate	验证表单项校验后触发	`(prop: FormItemProps, isValid: boolean, message: string ) => void`

Slots

Name	Description	Sub Component
default	默认插槽	FormItem

Expose

Name	Description	Type
validate	校验表单项	`() => Promise<boolean>`
validateField	校验指定表单项	`(props?: string[],callback?:(isValid:boolean,invalidFields?: ValidateFieldsError)) => Promise<boolean>`
resetFields	重置表单项	`(props?: string[]) => void`
clearValidate	清除校验状态	`(props?: string[]) => void`

FormItem API

Props

Name	Description	Type	Default
prop	表单域 model 字段	`string`	-
label	标签文本	`string`	-
label-width	标签宽度，例如 '50px'	`string\|number`	-
disabled	是否禁用表单域	`boolean`	`false`
required	是否必填，如不设置，则会根据校验规则自动生成	`boolean`	`false`
show-message	是否显示校验错误信息	`boolean`	`true`
error	错误提示文案，如不设置，则会从校验规则的 message 属性中获取	`string`	-
rules	校验规则	`FormItemRule[]`	-

Slots

Name	Description	Type
default	默认插槽	-
label	label 插槽	`{label:string}`
error	错误提示文案插槽	`{error:string}`

Expose

Name	Description	Type
validateStatus	校验状态	`Ref<ValidateStatus>` - `'success' \| 'error' \| 'validating' \| 'init'`
validateMessage	校验信息	`Ref<string>`
validate	校验表单项	`(trigger: string,callback?: (valid: boolean,invalidFields?: ValidateFieldsError) => void) => Promise<boolean>`
resetField	重置表单项	`() => void`
clearValidate	清除校验结果	`() => void`

Form 表单 ​

基本用法 ​

对齐方式 ​

表单校验 ​

自定义校验规则 ​

Form API ​

Props ​

Events ​

Slots ​

Expose ​

FormItem API ​

Props ​

Slots ​

Expose ​

Form 表单

基本用法

对齐方式

表单校验

自定义校验规则

Form API

Props

Events

Slots

Expose

FormItem API

Props

Slots

Expose