Form 表单

简介

在原来的 ElForm 的基础上增加了一些语法糖和更多的布局设置，帮助我们快速地开发一个表单，同时添加了一些默认行为，让我们的表单默认好用。

分步表单、Modal 表单、Drawer 表单、查询表单、轻量筛选等多种 layout 可以覆盖大部分的使用场景，让我们脱离复杂而且繁琐的表单布局工作，用更少的代码完成更多的功能。

Form 没有黑科技，只是 ElForm 的封装，如果要使用自定义的组件可以用 ElFormItem 包裹后使用，支持混用。

何时使用 Form？

当你想快速实现一个表单但不想花太多时间去布局时 Form 是最好的选择。

Form 是基于 ElForm 的可降级封装，与 element-plus 功能完全对齐，但是在其之上还增加一些预设行为和多种布局。这些布局之间可以无缝切换，并且拥有公共的 API。

代码演示

FormItem 表单项

一个表单除了 Form 之外还是需要一系列的表单项，FormItem 自带了数量可观的表单项，这些组件本质上是 ElFormItem 和表单组件的结合，我们可以把他们当成一个 ElFormItem 来使用，并且支持各种 props。每个表单项都支持 field-type 来指定组件类型，同时支持 field-props 属性来支持设置输入组件的 props。 我们支持 v-model 和 placeholder 等属性的透传。

下文把所有的输入组件统称为 field。

ElFormItem + ElInput 可以通过以下代码实现：

<template>
  <co-form-item
    v-model="username"
    label="用户名"
    placeholder="请输入"
    field-type="input"
    width="md"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const username = ref('');
</script>

field 的插槽内容可以直接放在 FormItem 里面，根据设置的 field-type 值会自动推断出插槽的接口类型。

<template>
  <co-form-item v-model="username" placeholder="请输入用户名" field-type="input" width="sm">
    <template #prefix>
      <co-icon name="bi bi-person" />
    </template>
  </co-form-item>
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const username = ref('');
</script>

field-props

field 的 props 和事件都可以通过 field-props 定义，事件名需要转换为以 on 开头紧跟大写字母的形式。 同插槽的使用，只要设置了 field-type ，便可以享受 props 的类型推断。

<template>
  <co-form-item
    v-model="username"
    label="用户名"
    field-type="input"
    :field-props="{
      maxlength: 10,
      showWordLimit: true,
      onInput(value) {
        console.log('input', value);
      },
    }"
    width="sm"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const username = ref('');
</script>

提示信息

使用 tooltip 属性或插槽可以在标签右边显示icon，鼠标移上去会显示提示信息。

<template>
  <co-form-item
    v-model="state"
    label="field"
    placeholder="请输入"
    field-type="input"
    width="md"
    tooltip="提示信息"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const state = ref('');
</script>

额外信息

使用 extra 属性或插槽可以在 field 下面显示额外信息。

<template>
  <co-form-item v-model="state" label="用户名" placeholder="请输入" width="md">
    <template #extra>
      <div>规范：</div>
      <div>1. 不能包括空格</div>
      <div>2. 长度为8-16个字符</div>
      <div>3. 只能包含字母、数字和下划线</div>
    </template>
  </co-form-item>
</template>

<script lang="ts" setup>
import { ref } from 'vue';

const state = ref('');
</script>

FormGroup 表单组

FormGroup 在需要的时候用来将表单项组合在一起，可以实现自定义的表单布局。

<template>
  <co-form-group alignment="flex-end">
    <co-form-item v-model="model.state1" label="field1" field-type="input" width="sm" />
    <co-form-item v-model="model.state2" label="field2" field-type="input" width="sm" />
  </co-form-group>

  <co-form-group title="表单组">
    <co-form-item v-model="model.state3" label="field3" field-type="input" width="sm" />
    <co-form-item v-model="model.state4" label="field4" field-type="input" width="sm" />
  </co-form-group>
</template>

<script lang="ts" setup>
import { reactive } from 'vue';

const model = reactive({
  state1: '',
  state2: '',
  state3: '',
  state4: '',
});
</script>

表单组还支持折叠功能，在一个大型表单中用于收纳暂不处理的一组表单项。

<template>
  <co-form-group title="表单组2" collapsible>
    <co-form-item v-model="model.state1" label="field3" field-type="input" width="sm" />
    <co-form-item v-model="model.state2" label="field4" field-type="input" width="sm" />
  </co-form-group>
</template>

<script lang="ts" setup>
import { reactive } from 'vue';

const model = reactive({
  state1: '',
  state2: '',
});
</script>

可以使用 tooltip 属性在标题右边显示提示语。

<template>
  <co-form-group title="表单组" tooltip="这是提示">
    <co-form-item v-model="model.state1" label="field3" field-type="input" width="sm" />
    <co-form-item v-model="model.state2" label="field4" field-type="input" width="sm" />
  </co-form-group>
</template>

<script lang="ts" setup>
import { reactive } from 'vue';

const model = reactive({
  state1: '',
  state2: '',
});
</script>

基础表单

一个基础的表单除了表单项，还有提交、重置按钮，Form 内置了这些按钮，同时在提交时给提交按钮添加了加载效果。

校验失败时，表单会自动滚动到第一个可见的出错字段（按文档顺序），所以被折叠、或被切走的页签里的字段不会抢走滚动位置；FormGroup、FormTabs、FormQuery 会各自把藏在里面的出错字段展开或切出来。

<template>
  <co-form :model="formModel" label-width="auto" :submit="onSubmit">
    <co-form-item
      v-model="formModel.name"
      prop="name"
      label="签约客户名称"
      field-type="input"
      width="md"
      :rules="[{ required: true }]"
    />
    <co-form-item
      v-model="formModel.company"
      prop="company"
      label="我方公司名称"
      field-type="input"
      width="md"
    />
    <co-form-item
      v-model="formModel.contract.name"
      prop="contract.name"
      label="合同名称"
      field-type="input"
      width="md"
    />
    <co-form-item
      v-model="formModel.contract.createTime"
      prop="contract.createTime"
      label="合同生效时间"
      field-type="daterange"
      width="md"
    />
    <co-form-item
      v-model="formModel.useMode"
      prop="useMode"
      label="合同约定生效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'chapter',
            label: '盖章后生效',
          },
        ],
      }"
      width="xs"
      readonly
    />
    <co-form-item
      v-model="formModel.unusedMode"
      prop="unusedMode"
      label="合同约定失效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'time',
            label: '履行完终止',
          },
        ],
      }"
      width="xs"
    />
    <co-form-item
      v-model="formModel.id"
      prop="id"
      label="主合同编号"
      field-type="input"
      width="sm"
    />
    <co-form-item
      v-model="formModel.project"
      prop="project"
      label="项目名称"
      field-type="input"
      disabled
      width="md"
    />
    <co-form-item
      v-model="formModel.mangerName"
      prop="mangerName"
      label="商务经理"
      field-type="input"
      disabled
      width="xs"
    />
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

行内表单

当垂直方向空间受限且表单较简单时，可以在一行内放置表单。

通过设置 inline 属性为 true 可以让表单域变为行内的表单域。

<template>
  <co-form :model="formModel" inline :submit="onSubmit">
    <co-form-item
      v-model="formModel.name"
      prop="name"
      label="签约客户名称"
      field-type="input"
      width="sm"
      :rules="[{ required: true }]"
    />
    <co-form-item
      v-model="formModel.company"
      prop="company"
      label="我方公司名称"
      field-type="input"
      width="sm"
    />
    <co-form-item
      v-model="formModel.contract.name"
      prop="contract.name"
      label="合同名称"
      field-type="input"
      width="sm"
    />
    <co-form-item
      v-model="formModel.contract.createTime"
      prop="contract.createTime"
      label="合同生效时间"
      field-type="daterange"
      width="sm"
    />
    <co-form-item
      v-model="formModel.useMode"
      prop="useMode"
      label="合同约定生效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'chapter',
            label: '盖章后生效',
          },
        ],
      }"
      width="xs"
      readonly
    />
    <co-form-item
      v-model="formModel.unusedMode"
      prop="unusedMode"
      label="合同约定失效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'time',
            label: '履行完终止',
          },
        ],
      }"
      width="xs"
    />
    <co-form-item
      v-model="formModel.id"
      prop="id"
      label="主合同编号"
      field-type="input"
      width="sm"
    />
    <co-form-item
      v-model="formModel.project"
      prop="project"
      label="项目名称"
      field-type="input"
      disabled
      width="sm"
    />
    <co-form-item
      v-model="formModel.mangerName"
      prop="mangerName"
      label="商务经理"
      field-type="input"
      disabled
      width="xs"
    />
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

等宽表单项

除了行内表单，也可以将所有表单项放到 FormGroup 组件里面，这同样起到行内的效果。

另外，可以在 Form 组件上设置 label-width 和 width 属性来统一让所有表单项的标签和控件宽度一致。

<template>
  <co-form :model="formModel" label-width="auto" width="sm" :submit="onSubmit">
    <co-form-group>
      <co-form-item
        v-model="formModel.name"
        prop="name"
        label="签约客户名称"
        field-type="input"
        :rules="[{ required: true }]"
      />
      <co-form-item
        v-model="formModel.company"
        prop="company"
        label="我方公司名称"
        field-type="input"
      />
      <co-form-item
        v-model="formModel.contract.name"
        prop="contract.name"
        label="合同名称"
        field-type="input"
      />
      <co-form-item
        v-model="formModel.contract.createTime"
        prop="contract.createTime"
        label="合同生效时间"
        field-type="daterange"
      />
      <co-form-item
        v-model="formModel.useMode"
        prop="useMode"
        label="合同约定生效方式"
        field-type="select"
        :field-props="{
          options: [
            {
              value: 'chapter',
              label: '盖章后生效',
            },
          ],
        }"
        readonly
      />
      <co-form-item
        v-model="formModel.unusedMode"
        prop="unusedMode"
        label="合同约定失效方式"
        field-type="select"
        :field-props="{
          options: [
            {
              value: 'time',
              label: '履行完终止',
            },
          ],
        }"
      />
      <co-form-item v-model="formModel.id" prop="id" label="主合同编号" field-type="input" />
      <co-form-item
        v-model="formModel.project"
        prop="project"
        label="项目名称"
        field-type="input"
        disabled
      />
      <co-form-item
        v-model="formModel.mangerName"
        prop="mangerName"
        label="商务经理"
        field-type="input"
        disabled
      />
    </co-form-group>
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

等宽行内表单

行内表单也可以统一设置标签和控件的宽度。

<template>
  <co-form :model="formModel" inline label-width="auto" width="sm" :submit="onSubmit">
    <co-form-item
      v-model="formModel.name"
      prop="name"
      label="签约客户名称"
      field-type="input"
      :rules="[{ required: true }]"
    />
    <co-form-item
      v-model="formModel.company"
      prop="company"
      label="我方公司名称"
      field-type="input"
    />
    <co-form-item
      v-model="formModel.contract.name"
      prop="contract.name"
      label="合同名称"
      field-type="input"
    />
    <co-form-item
      v-model="formModel.contract.createTime"
      prop="contract.createTime"
      label="合同生效时间"
      field-type="daterange"
    />
    <co-form-item
      v-model="formModel.useMode"
      prop="useMode"
      label="合同约定生效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'chapter',
            label: '盖章后生效',
          },
        ],
      }"
      readonly
    />
    <co-form-item
      v-model="formModel.unusedMode"
      prop="unusedMode"
      label="合同约定失效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'time',
            label: '履行完终止',
          },
        ],
      }"
    />
    <co-form-item v-model="formModel.id" prop="id" label="主合同编号" field-type="input" />
    <co-form-item
      v-model="formModel.project"
      prop="project"
      label="项目名称"
      field-type="input"
      disabled
    />
    <co-form-item
      v-model="formModel.mangerName"
      prop="mangerName"
      label="商务经理"
      field-type="input"
      disabled
    />
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

最小宽度

不设置 width 时，控件区会按剩余空间伸缩，空间紧张时就会被压得很窄。 给 Form 设置 min-width 可以定下伸缩下限（数值按 px，也可以用 xs ~ xl 预设）， 塞不下就整项换行，而不是继续挤。

下面两个表单容器一样宽：不设 min-width 时一行塞得下两个控件（每个约 198px）， 设成 320 之后每个控件都不窄于 320px，于是一行只剩一个。

<template>
  <div>
    <p style="margin: 0 0 8px; font-size: 12px; color: var(--vp-c-text-2)">不设 min-width</p>
    <co-form :model="formModel" inline label-width="auto">
      <co-form-item v-model="formModel.name" prop="name" label="客户" field-type="input" />
      <co-form-item v-model="formModel.company" prop="company" label="公司" field-type="input" />
      <co-form-item
        v-model="formModel.contract.name"
        prop="contract.name"
        label="合同"
        field-type="input"
      />
      <co-form-item v-model="formModel.owner" prop="owner" label="负责人" field-type="input" />
    </co-form>

    <p style="margin: 16px 0 8px; font-size: 12px; color: var(--vp-c-text-2)">min-width="320"</p>
    <co-form :model="formModel" inline label-width="auto" :min-width="320">
      <co-form-item v-model="formModel.name" prop="name" label="客户" field-type="input" />
      <co-form-item v-model="formModel.company" prop="company" label="公司" field-type="input" />
      <co-form-item
        v-model="formModel.contract.name"
        prop="contract.name"
        label="合同"
        field-type="input"
      />
      <co-form-item v-model="formModel.owner" prop="owner" label="负责人" field-type="input" />
    </co-form>
  </div>
</template>

<script lang="ts" setup>
import { reactive } from 'vue';

const formModel = reactive({
  name: undefined,
  company: undefined,
  contract: {
    name: undefined,
  },
  owner: undefined,
});
</script>

标签位置

顶部标签可以让表单控件有更多的空间。

<template>
  <co-form :model="formModel" label-position="top" :submit="onSubmit">
    <co-form-group>
      <co-form-item
        v-model="formModel.name"
        prop="name"
        label="签约客户名称"
        field-type="input"
        width="md"
        :rules="[{ required: true }]"
      />
      <co-form-item
        v-model="formModel.company"
        prop="company"
        label="我方公司名称"
        field-type="input"
        width="md"
      />
    </co-form-group>
    <co-form-group>
      <co-form-item
        v-model="formModel.contract.name"
        prop="contract.name"
        label="合同名称"
        field-type="input"
        width="md"
      />
      <co-form-item
        v-model="formModel.contract.createTime"
        prop="contract.createTime"
        label="合同生效时间"
        field-type="daterange"
        width="md"
      />
    </co-form-group>
    <co-form-group>
      <co-form-item
        v-model="formModel.useMode"
        prop="useMode"
        label="合同约定生效方式"
        field-type="select"
        :field-props="{
          options: [
            {
              value: 'chapter',
              label: '盖章后生效',
            },
          ],
        }"
        width="xs"
        readonly
      />
      <co-form-item
        v-model="formModel.unusedMode"
        prop="unusedMode"
        label="合同约定失效方式"
        field-type="select"
        :field-props="{
          options: [
            {
              value: 'time',
              label: '履行完终止',
            },
          ],
        }"
        width="xs"
      />
    </co-form-group>
    <co-form-item
      v-model="formModel.id"
      prop="id"
      label="主合同编号"
      field-type="input"
      width="sm"
    />
    <co-form-item
      v-model="formModel.project"
      prop="project"
      label="项目名称"
      field-type="input"
      disabled
      width="md"
    />
    <co-form-item
      v-model="formModel.mangerName"
      prop="mangerName"
      label="商务经理"
      field-type="input"
      disabled
      width="xs"
    />
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

栅格化布局

栅格化布局可以让表单在父容器不同宽度下展示不同的列数。使用 grid 启动栅格化布局，使用 row-props 和 col-props 设置栅格间隔、列数等。

<template>
  <co-form
    grid
    :row-props="{
      gutter: 32,
    }"
    :col-props="{
      xs: 24,
      sm: 12,
      md: 8,
      lg: 6,
      xl: 6,
    }"
    :model="formModel"
    :submit="onSubmit"
  >
    <co-form-item
      v-model="formModel.name"
      prop="name"
      label="签约客户名称"
      field-type="input"
      :rules="[{ required: true }]"
    />
    <co-form-item
      v-model="formModel.company"
      prop="company"
      label="我方公司名称"
      field-type="input"
    />
    <co-form-item
      v-model="formModel.contract.name"
      prop="contract.name"
      label="合同名称"
      field-type="input"
    />
    <co-form-item
      v-model="formModel.contract.createTime"
      prop="contract.createTime"
      label="合同生效时间"
      field-type="daterange"
    />
    <co-form-item
      v-model="formModel.useMode"
      prop="useMode"
      label="合同约定生效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'chapter',
            label: '盖章后生效',
          },
        ],
      }"
      readonly
    />
    <co-form-item
      v-model="formModel.unusedMode"
      prop="unusedMode"
      label="合同约定失效方式"
      field-type="select"
      :field-props="{
        options: [
          {
            value: 'time',
            label: '履行完终止',
          },
        ],
      }"
    />
    <co-form-item v-model="formModel.id" prop="id" label="主合同编号" field-type="input" />
    <co-form-item
      v-model="formModel.project"
      prop="project"
      label="项目名称"
      field-type="input"
      disabled
    />
    <co-form-item
      v-model="formModel.mangerName"
      prop="mangerName"
      label="商务经理"
      field-type="input"
      disabled
    />
  </co-form>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus';
import { reactive } from 'vue';

const formModel = reactive({
  name: '蚂蚁设计有限公司',
  company: undefined,
  contract: {
    name: undefined,
    createTime: undefined,
  },
  useMode: 'chapter',
  unusedMode: undefined,
  id: undefined,
  project: 'xxxx项目',
  mangerName: '启途',
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 500));
  ElMessage.success('提交成功');
};
</script>

所有表单项

下面演示了所有的表单项及其在只读状态下的展示。

<template>
  <el-segmented
    v-model="readonly"
    :options="[
      {
        label: '只读',
        value: true,
      },
      {
        label: '编辑',
        value: false,
      },
    ]"
    size="large"
    class="mb-5"
  />

  <co-form
    ref="form"
    :model="formModel"
    label-position="top"
    grid
    :row-props="{
      gutter: 32,
    }"
    :col-props="{
      xs: 24,
      sm: 12,
      md: 8,
      lg: 6,
      xl: 6,
    }"
    :readonly="readonly"
    :submit="onSubmit"
  >
    <co-form-item
      v-model="formModel.autocomplete"
      label="autocomplete"
      field-type="autocomplete"
      :field-props="{
        fetchSuggestions: querySearch,
      }"
    />
    <co-form-item
      v-model="formModel.cascader"
      label="cascader"
      field-type="cascader"
      :field-props="{ options: cascaderOptions }"
    />
    <co-form-item
      v-model="formModel.checkbox"
      label="checkbox"
      field-type="checkbox"
      :field-props="{ label: '记住密码' }"
    />
    <co-form-item
      v-model="formModel.checkboxgroup"
      label="checkboxgroup"
      field-type="checkboxgroup"
      :field-props="{ options }"
    />
    <co-form-item v-model="formModel.color" label="color" field-type="color" />
    <co-form-item v-model="formModel.year" label="year" field-type="year" />
    <co-form-item v-model="formModel.years" label="years" field-type="years" />
    <co-form-item v-model="formModel.month" label="month" field-type="month" />
    <co-form-item v-model="formModel.months" label="months" field-type="months" />
    <co-form-item v-model="formModel.date" label="date" field-type="date" />
    <co-form-item v-model="formModel.dates" label="dates" field-type="dates" />
    <co-form-item label="datetime" field-type="datetime" v-model="formModel.datetime" />
    <co-form-item v-model="formModel.week" label="week" field-type="week" />
    <co-form-item v-model="formModel.weekrange" label="weekrange" field-type="weekrange" />
    <co-form-item
      v-model="formModel.datetimerange"
      label="datetimerange"
      field-type="datetimerange"
    />
    <co-form-item v-model="formModel.daterange" label="daterange" field-type="daterange" />
    <co-form-item v-model="formModel.monthrange" label="monthrange" field-type="monthrange" />
    <co-form-item v-model="formModel.yearrange" label="yearrange" field-type="yearrange" />
    <co-form-item v-model="formModel.number" label="number" field-type="number" />
    <co-form-item v-model="formModel.mention" label="mention" field-type="mention" />
    <co-form-item v-model="formModel.password" label="password" field-type="password" />
    <co-form-item
      v-model="formModel.radiogroup"
      label="radiogroup"
      field-type="radiogroup"
      :field-props="{ options }"
    />
    <co-form-item v-model="formModel.rate" label="rate" field-type="rate" />
    <co-form-item
      v-model="formModel.segmented"
      label="segmented"
      field-type="segmented"
      :field-props="{ options }"
    />
    <co-form-item
      v-model="formModel.select"
      label="select"
      field-type="select"
      :field-props="{ options }"
    />
    <co-form-item
      v-model="formModel.selectv2"
      label="selectv2"
      field-type="selectv2"
      :field-props="{ options: virtualOptions }"
    />
    <co-form-item v-model="formModel.slider" label="slider" field-type="slider" />
    <co-form-item v-model="formModel.switch" label="switch" field-type="switch" />
    <co-form-item v-model="formModel.input" label="input" field-type="input" />
    <co-form-item v-model="formModel.textarea" label="textarea" field-type="textarea" />
    <co-form-item v-model="formModel.inputtag" label="inputtag" field-type="inputtag" />
    <co-form-item v-model="formModel.time" label="time" field-type="time" />
    <co-form-item v-model="formModel.timerange" label="timerange" field-type="timerange" />
    <co-form-item v-model="formModel.timeselect" label="timeselect" field-type="timeselect" />
    <co-form-item
      v-model="formModel.treeselect"
      label="treeselect"
      field-type="treeselect"
      :field-props="{
        data: treeSelectData,
      }"
    />
    <co-form-item
      v-model="formModel.transfer"
      label="transfer"
      field-type="transfer"
      :field-props="{
        data: transferData,
      }"
      :col-props="{
        xs: 24,
        sm: 24,
        md: 24,
        lg: 24,
        xl: 24,
      }"
    />
  </co-form>
</template>

<script lang="ts" setup>
import { reactive, ref, useTemplateRef } from 'vue';
import {
  loadAll,
  treeSelectData,
  cascaderOptions,
  options,
  virtualOptions,
  generateData,
  Option,
} from './data';
import dayjs from 'dayjs';
import { type FormExpose } from 'cosey/components';

const readonly = ref(false);

// autocomplete
interface RestaurantItem {
  value: string;
  link: string;
}

const restaurants = ref<RestaurantItem[]>(loadAll());

const querySearch = (queryString: string, cb: any) => {
  const results = queryString
    ? restaurants.value.filter(createFilter(queryString))
    : restaurants.value;
  cb(results);
};

const createFilter = (queryString: string) => {
  return (restaurant: RestaurantItem) => {
    return restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0;
  };
};

const transferData = ref<Option[]>(generateData());

const formModel = reactive({
  autocomplete: 'vue-router',
  cascader: ['component', 'form', 'cascader'],
  checkbox: true,
  checkboxgroup: ['Option2', 'Option3'],
  color: '#008CFF',
  year: new Date(),
  years: [new Date(2000, 0), new Date(2002, 0), new Date(2004, 0)],
  month: new Date(),
  months: [new Date(2000, 0), new Date(2000, 3), new Date(2000, 5)],
  date: new Date(),
  dates: [new Date(2000, 0, 1), new Date(2000, 0, 3), new Date(2000, 0, 5)],
  datetime: new Date(),
  week: new Date(),
  weekrange: [new Date(), dayjs().add(2, 'week').toDate()],
  datetimerange: [new Date(2000, 0, 1, 0, 0, 0), new Date(2000, 0, 31, 23, 59, 59)] as [Date, Date],
  daterange: [new Date(2000, 0, 1), new Date(2000, 0, 15)] as [Date, Date],
  monthrange: [new Date(2000, 0), new Date(2000, 6)] as [Date, Date],
  yearrange: [new Date(2000, 0), new Date(2005, 0)] as [Date, Date],
  number: 9999 as number | undefined,
  mention: 'admin',
  password: '123456',
  radiogroup: 'Option2',
  rate: 3,
  segmented: 'Option2',
  select: 'Option2',
  selectv2: 'Option2',
  slider: 75,
  switch: true,
  input: '一段文本',
  inputtag: ['tag1', 'tag2', 'tag3'],
  textarea: '一段多行文本',
  time: new Date(),
  timerange: [new Date(2000, 0, 1, 9, 0, 0), new Date(2000, 0, 1, 18, 0, 0)] as [Date, Date],
  timeselect: '12:00',
  transfer: [1, 3, 7],
  treeselect: '3-1-1',
});

const formRef = useTemplateRef<FormExpose>('form');

const onSubmit = () => {
  formRef.value?.validate().then(() => {
    console.log('验证成功');
  });
};
</script>

API

FormProps

继承 element-plus 的 Form Attributes ，并添加以下属性：

属性	描述	类型	默认值
width	统一设置 field 为固定宽度	FormItemWidth	-
min-width	统一设置 field 最小宽度，未设 width 时作为伸缩下限	FormItemWidth	-
grid	是否开启栅格化模式	boolean	false
row-props	栅格化模式下设置 Row 的属性	RowProps	-
col-props	栅格化模式下设置所有 field 共同的 Col 的属性	ColProps	-
readonly	设置表单内所有 field 为只读状态	boolean	false
submit	提交表单时触发的回调	() => any | Promise<any>	-
reset	重置表单时触发的回调	() => any	-
submit-text	提交按钮的文案	string	'提交'
reset-text	重置按钮的文案	string	'重置'
submit-props	提交按钮的属性	ButtonProps	-
reset-props	重置按钮的属性	ButtonProps	-
hide-submit	是否隐藏提交按钮	boolean	false
hide-reset	是否隐藏重置按钮	boolean	false
hide-buttons	同时隐藏提交和重置按钮	boolean	false

FormSlots

继承 element-plus 的 Form Slots ，并支持以下插槽。

插槽	描述	属性
button	自定义整个按钮区，优先于 submit / reset	{ submitting: boolean; submit: () => any | Promise<any>; reset: () => any;}
submit	自定义提交按钮	{ submitting: boolean; submit: () => any | Promise<any> }
reset	自定义重置按钮

FormEmits

继承 element-plus 的 Form 事件。

FormExpose

继承 element-plus 的 Form Exposes ，并添加以下属性：

属性	描述	类型
submit	提交表单	() => Promise<any>
reset	重置表单，callback会在 reset 属性调用前调用	(callback?: () => void) => void

FormItemProps

继承 element-plus 的 FormItem Attributes ，并添加以下属性：

属性	描述	类型	默认值
field-type	field 的类型	FieldType	'input'
field-props	field 的 props	MapFieldTypeComponentProps[FieldType]['componentProps']	-
field-slots	field 的 slots	MapFieldTypeComponentProps[FieldType]['componentSlots']	-
field-ref	获取 field 暴露的属性	(el: any) => void	-
model-value (v-model)	绑定 field 的值	NonNullable<MapFieldTypeComponentProps[FieldType]['componentProps']> ['modelValue']	-
width	设置 field 为固定宽度	FormItemWidth	-
placeholder	设置 field 占位符，仅对带有输入框的组件有效	string	-
disabled	设置 field 为禁用状态	boolean	false
readonly	设置 field 为只读状态	boolean	false
col-props	当 Form 开启栅格化模式时可以设置其内 Col 组件的 props	ColProps	-
tooltip	配置提示信息	VNodeChild	-
extra	额外的提示信息	VNodeChild	-

FormItemWidth

type FormItemWidth = number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | (string & {});

在某些场景下，我们需要根据页面展示效果对输入框进行自适应处理，除此以外一个表单区域应默认使用定宽规则。

• XS=104px 适用于短数字、短文本或选项。
• SM=216px 适用于较短字段录入、如姓名、电话、ID 等。
• MD=328px 标准宽度，适用于大部分字段长度。
• LG=440px 适用于较长字段录入，如长网址、标签组、文件路径等。
• XL=552px 适用于长文本录入，如长链接、描述、备注等，通常搭配自适应多行输入框或定高文本域使用。

FormItemSlots

继承 element-plus 的 FormItem Slots ，以及对应 field 的插槽，并添加以下插槽：

插槽	描述	属性
tooltip	配置提示信息	-
extra	额外的提示信息	-

FormItemEmits

事件	描述	类型
update:model-value	field 的值改变时触发	(value: unknown) => void

FormItemExpose

继承 element-plus 的 FormItem Exposes。

FormGroupProps

继承 element-plus 的 Space Attributes，并添加以下属性：

属性	描述	类型	默认值
alignment	对齐的方式 (align-items)	'stretch' | 'center' | 'flex-start' | 'flex-end'	'flex-start'
size	间隔大小	number | 'default' | 'small' | 'large' | [number, number]	[32, 0]
wrap	设置是否自动折行	boolean	true
title	设置表单组的标题	string	-
tooltip	设置表单组标题的提示语	string	-
border-style	设置边框样式	'none' | 'solid' | 'dashed' | 'dotted'	-
position	设置标题位置	'left' | 'right' | 'center'	'left'
collapsible	是否允许折叠	boolean	false
collapsed	设置是否为折叠状态	boolean	false

FormGroupSlots

插槽	描述	属性
default	自定义默认内容	-
title	自定义标题内容	-
tooltip	自定义标题提示语内容	-

FormGroupEmits

事件	描述	类型
update:collapsed	折叠状态改变时触发	(collapsed: boolean) => void

FieldType

autocomplete

同 element-plus 的 ElAutocomplete 组件。

cascader

同 element-plus 的 ElCascader 组件。

checkbox

同 element-plus 的 ElCheckbox 组件。

checkboxgroup

同 element-plus 的 ElCheckboxGroup 组件。并添加以下属性：

属性	描述	类型	默认值
options	使用配置对象来生成复选框	(Partial<CheckboxProps> | string | number)[]	-
label-key	自定义 options 中标签的键名	string	'label'
value-key	自定义 options 中值的键名	string	'value'
type	设置复选框的类型	'button' | 'checkbox'	'checkbox'
checkbox-width	设置复选框的宽度	string | number	-

color

同 element-plus 的 ElColorPicker 组件。

date

同 element-plus 的 ElDatePicker 组件。

daterange

同 element-plus 的 ElDatePicker 组件。并预设了 type="daterange" 属性。

dates

同 element-plus 的 ElDatePicker 组件。并预设了 type="dates" 属性。

datetime

同 element-plus 的 ElDatePicker 组件。并预设了 type="datetime" 属性。

datetimerange

同 element-plus 的 ElDatePicker 组件。并预设了 type="datetimerange" 属性。

input

同 element-plus 的 ElInput 组件。

inputtag

同 element-plus 的 ElInputTag 组件。

mention

同 element-plus 的 ElMention 组件。

month

同 element-plus 的 ElDatePicker 组件。并预设了 type="month" 属性。

monthrange

同 element-plus 的 ElDatePicker 组件。并预设了 type="monthrange" 属性。

months

同 element-plus 的 ElDatePicker 组件。并预设了 type="months" 属性。

number

同 element-plus 的 ElInputNumber 组件。

numberrange

同 InputNumberRange 组件。

password

同 element-plus 的 ElInput 组件。并预设了 type="password" 属性。

radiogroup

同 element-plus 的 ElRadioGroup 组件。并添加以下属性：

属性	描述	类型	默认值
type	设置单选框的类型	'button' | 'radio'	'radio'

rate

同 element-plus 的 ElRate 组件。

remoteselect

同 RemoteSelect 组件。

segmented

同 element-plus 的 ElSegmented 组件。

select

同 element-plus 的 ElSelect 组件。并添加以下属性：

属性	描述	类型	默认值
option-props	自定义 ElOption 属性	Record<PropertyKey, any> | (props: any, index: number) => Record<PropertyKey, any>	-

selectv2

同 element-plus 的 ElSelectV2 组件。并添加以下属性：

属性	描述	类型	默认值
option-props	自定义 ElOption 属性	(props: Record<PropertyKey, any>, index: number) => Record<PropertyKey, any>	-

slider

同 element-plus 的 ElSlider 组件。

switch

同 element-plus 的 ElSwitch 组件。

textarea

同 element-plus 的 ElInput 组件。并预设了 type="textarea" 属性。

time

同 element-plus 的 ElTimePicker 组件。

timerange

同 element-plus 的 ElTimePicker 组件。并预设了 is-range 属性。

timeselect

同 element-plus 的 ElTimeSelect 组件。

transfer

同 element-plus 的 ElTransfer 组件。

treeselect

同 element-plus 的 ElTreeSelect 组件。

upload

同 Upload 组件。

week

同 element-plus 的 ElDatePicker 组件。并预设了 type="week" 属性。

weekrange

同 WeekRangePicker 组件。

year

同 element-plus 的 ElDatePicker 组件。并预设了 type="year" 属性。

yearrange

同 element-plus 的 ElDatePicker 组件。并预设了 type="yearrange" 属性。

years

同 element-plus 的 ElDatePicker 组件。并预设了 type="years" 属性。