FormGroup 折叠表单组

简介

FormGroup 是 ElSpace 的高阶组件，用于把表单字段分组 —— 可选带标题、边框和折叠。 有 title 时会渲染边框，collapsible 打开后点标题即可收起 / 展开。

size、direction、alignment、wrap 等 ElSpace 的能力都会原样透传， 所以横向排列、纵向堆叠、自定义间距都可以直接用。

放在 Form 里使用时，校验失败会自动展开包含出错字段的分组： 收起状态下字段是被 display: none 藏起来的，FormItem 却仍然参与校验， 错误信息用户根本看不见。

代码演示

基础用法

有 title 时渲染标题与边框；没有 title 时只是一个分组容器，不渲染边框。

<template>
  <co-form-group title="基本信息">
    <co-form-item v-model="model.name" label="姓名" width="sm" />
    <co-form-item v-model="model.mobile" label="手机号" width="sm" />
  </co-form-group>

  <!-- 没有 title 时不渲染边框，只是把字段分成一组 -->
  <co-form-group>
    <co-form-item v-model="model.company" label="公司" width="sm" />
    <co-form-item v-model="model.job" label="职位" width="sm" />
  </co-form-group>
</template>

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

const model = reactive({
  name: '',
  mobile: '',
  company: '',
  job: '',
});
</script>

可折叠

设置 collapsible 后点标题即可收起 / 展开，标题左侧会出现指示箭头。

collapsed 支持 v-model:collapsed，所以折叠状态也可以完全交给外部控制。

<template>
  <co-form-group title="基本信息" collapsible v-model:collapsed="collapsed.basic">
    <co-form-item v-model="model.name" label="姓名" width="sm" />
    <co-form-item v-model="model.mobile" label="手机号" width="sm" />
  </co-form-group>

  <co-form-group title="高级设置" collapsible v-model:collapsed="collapsed.advanced">
    <co-form-item v-model="model.timeout" label="超时时间" width="sm" />
    <co-form-item v-model="model.retry" label="重试次数" width="sm" />
  </co-form-group>

  <el-space>
    <el-button @click="collapsed.advanced = !collapsed.advanced">切换「高级设置」</el-button>
    <el-button @click="collapseAll">全部收起</el-button>
  </el-space>
</template>

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

const model = reactive({
  name: '',
  mobile: '',
  timeout: '',
  retry: '',
});

// collapsed 支持 v-model:collapsed，所以折叠状态也可以完全交给外部控制
const collapsed = reactive({
  basic: false,
  advanced: true,
});

const collapseAll = () => {
  collapsed.basic = true;
  collapsed.advanced = true;
};
</script>

标题位置

position 控制标题贴在左边、居中还是右边，默认在左。

<template>
  <co-form-group title="标题在左" position="left">
    <co-form-item v-model="model.name" label="姓名" width="sm" />
    <co-form-item v-model="model.mobile" label="手机号" width="sm" />
  </co-form-group>

  <co-form-group title="标题居中" position="center">
    <co-form-item v-model="model.company" label="公司" width="sm" />
    <co-form-item v-model="model.job" label="职位" width="sm" />
  </co-form-group>

  <co-form-group title="标题在右" position="right">
    <co-form-item v-model="model.city" label="城市" width="sm" />
    <co-form-item v-model="model.detail" label="详细地址" width="sm" />
  </co-form-group>
</template>

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

const model = reactive({
  name: '',
  mobile: '',
  company: '',
  job: '',
  city: '',
  detail: '',
});
</script>

边框样式

border-style 支持 solid / dashed / dotted / none， 不设置时沿用 ElSpace 的边框变量（实线）；none 可以只保留标题和留白。

<template>
  <co-form-group title="solid（默认）" border-style="solid">
    <co-form-item v-model="model.name" label="姓名" width="sm" />
    <co-form-item v-model="model.mobile" label="手机号" width="sm" />
  </co-form-group>

  <co-form-group title="dashed" border-style="dashed">
    <co-form-item v-model="model.company" label="公司" width="sm" />
    <co-form-item v-model="model.job" label="职位" width="sm" />
  </co-form-group>

  <co-form-group title="dotted" border-style="dotted">
    <co-form-item v-model="model.city" label="城市" width="sm" />
    <co-form-item v-model="model.detail" label="详细地址" width="sm" />
  </co-form-group>

  <co-form-group title="none（只要标题，不要边框）" border-style="none">
    <co-form-item v-model="model.remark" label="备注" width="md" />
  </co-form-group>
</template>

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

const model = reactive({
  name: '',
  mobile: '',
  company: '',
  job: '',
  city: '',
  detail: '',
  remark: '',
});
</script>

自定义标题与提示

用 title 插槽自定义标题内容（比如补一个标签），用 tooltip 插槽自定义标题旁边的提示气泡。

<template>
  <co-form-group>
    <template #title>
      <span>收货信息</span>
      <el-tag style="margin-inline-start: 6px" type="danger" size="small">必填</el-tag>
    </template>
    <template #tooltip>请填写真实地址与电话，否则可能无法配送。</template>

    <co-form-item v-model="model.name" label="收件人" width="sm" required />
    <co-form-item v-model="model.tel" label="手机号" width="sm" required />
    <co-form-item v-model="model.address" label="详细地址" width="md" />
  </co-form-group>
</template>

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

const model = reactive({
  name: '',
  tel: '',
  address: '',
});
</script>

间距、方向与对齐

size 默认 [32, 0]（横向间距 32、纵向 0），传数组可以分别控制两个方向的间距。

alignment 在各项高度不一致时才有视觉效果 —— 比如下面第三个分组里，多行输入框比单行输入框高。

<template>
  <co-form-group title="自定义间距" :size="[16, 16]">
    <co-form-item v-model="model.a" label="字段一" width="sm" />
    <co-form-item v-model="model.b" label="字段二" width="sm" />
  </co-form-group>

  <co-form-group title="纵向排列" direction="vertical" alignment="flex-start" :size="[0, 16]">
    <co-form-item v-model="model.c" label="字段三" width="sm" />
    <co-form-item v-model="model.d" label="字段四" width="sm" />
  </co-form-group>

  <co-form-group title="垂直居中" alignment="center" :size="[16, 16]">
    <co-form-item v-model="model.e" label="单行" width="sm" />
    <co-form-item v-model="model.f" label="多行" width="sm" field-type="textarea" />
  </co-form-group>
</template>

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

const model = reactive({
  a: '',
  b: '',
  c: '',
  d: '',
  e: '',
  f: '',
});
</script>

嵌套分组

分组可以嵌套，内层同样可以折叠。

<template>
  <co-form-group title="订单信息" direction="vertical" :size="[0, 16]">
    <co-form-item v-model="model.no" label="订单号" width="sm" />
    <co-form-item v-model="model.amount" label="金额" width="sm" />

    <co-form-group title="收货地址" collapsible v-model:collapsed="collapsed" :size="[16, 16]">
      <co-form-item v-model="model.city" label="城市" width="sm" />
      <co-form-item v-model="model.detail" label="详细地址" width="md" />
    </co-form-group>
  </co-form-group>
</template>

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

const model = reactive({
  no: '',
  amount: '',
  city: '',
  detail: '',
});

const collapsed = ref(false);
</script>

校验失败自动展开

第二个分组默认收起，点「提交」后会自动展开；配合表单的滚动定位，能直接看到是哪个字段出错。

不需要这个行为时，把 switch-to-invalid 设为 false。

<template>
  <co-form :model="formModel" :submit="onSubmit" label-width="auto">
    <co-form-group title="基本信息" collapsible v-model:collapsed="collapsed.basic">
      <co-form-item v-model="formModel.name" prop="name" label="姓名" width="sm" required />
      <co-form-item v-model="formModel.mobile" prop="mobile" label="手机号" width="sm" />
    </co-form-group>

    <co-form-group title="紧急联系人" collapsible v-model:collapsed="collapsed.emergency">
      <co-form-item v-model="formModel.contact" prop="contact" label="联系人" width="sm" required />
      <co-form-item v-model="formModel.contactTel" prop="contactTel" label="联系电话" width="sm" />
    </co-form-group>
  </co-form>
</template>

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

const formModel = reactive({
  name: '',
  mobile: '',
  contact: '',
  contactTel: '',
});

// 第二个分组默认是收起的，提交后会自动展开
const collapsed = reactive({
  basic: false,
  emergency: true,
});

const onSubmit = async () => {
  await new Promise((resolve) => setTimeout(resolve, 300));
  ElMessage.success('校验通过');
};
</script>

API

FormGroupProps

继承 element-plus 的 Space Attributes，并有以下额外属性。

属性	描述	类型	默认值
alignment	主轴对齐方式	'stretch' | 'center' | 'flex-start' | 'flex-end'	'flex-start'
size	间距	number | 'default' | 'small' | 'large' | [number, number]	[32, 0]
wrap	是否自动换行	boolean	true
title	分组标题，有标题时渲染边框	VNodeChild	-
tooltip	标题旁的提示内容	VNodeChild	-
border-style	边框样式	'none' | 'solid' | 'dashed' | 'dotted'	-
position	标题位置	'left' | 'right' | 'center'	'left'
collapsible	是否可折叠	boolean	-
collapsed	是否收起（支持 v-model:collapsed）	boolean	-
switch-to-invalid	校验失败时自动展开，把出错的字段露出来	boolean	true

FormGroupSlots

插槽名	描述
default	分组内容
title	自定义标题
tooltip	自定义提示内容

FormGroupEmits

事件名	描述	参数
update:collapsed	折叠状态变化	(collapsed: boolean)