FormSection 表单分组
把一张长表单按内容分成几组,每组有一个带主色竖条的标题和一条分隔线,可以折叠。放在 NsForm 里,里面照常写 NsFormItem。
引入
import { NsFormSection } from '@ns/ui'
基础用法
title 设置标题,默认插槽放表单项。相邻两个分组之间自动留出距离,第一个分组上面不留。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsFormSection, NsInput } from '@ns/ui'
const form = reactive({ name: '', phone: '', email: '' })
</script>
<template>
<NsForm :model="form" label-width="80px">
<NsFormSection title="基础信息">
<NsFormItem label="姓名" prop="name">
<NsInput v-model="form.name" />
</NsFormItem>
</NsFormSection>
<NsFormSection title="联系方式">
<NsFormItem label="手机号" prop="phone">
<NsInput v-model="form.phone" />
</NsFormItem>
<NsFormItem label="邮箱" prop="email">
<NsInput v-model="form.email" />
</NsFormItem>
</NsFormSection>
</NsForm>
</template>
可折叠
collapsible 在标题行右侧显示折叠按钮,展开时文字是“收起”、收起时是“展开”,后面的箭头跟着转向;收起、展开有高度动画。用 v-model:expanded 读取和控制展开状态,默认展开。
<script setup lang="ts">
import { ref } from 'vue'
import { NsForm, NsFormItem, NsFormSection, NsInput } from '@ns/ui'
const expanded = ref(false)
</script>
<template>
<NsForm label-width="80px">
<NsFormSection v-model:expanded="expanded" title="高级设置" collapsible>
<NsFormItem label="编码">
<NsInput />
</NsFormItem>
</NsFormSection>
</NsForm>
</template>
v-model:expanded 是双向的:点折叠按钮会改绑定的值,改绑定的值也会展开、收起分组。下面用外面的按钮控制两个分组:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsFormSection, NsInput, NsSpace } from '@ns/ui'
const baseExpanded = ref(true)
const advancedExpanded = ref(false)
const setAll = (value: boolean) => {
baseExpanded.value = value
advancedExpanded.value = value
}
</script>
<template>
<NsSpace wrap>
<NsButton size="small" @click="setAll(true)">全部展开</NsButton>
<NsButton size="small" @click="setAll(false)">全部收起</NsButton>
<span
>基础信息:{{ baseExpanded ? '展开' : '收起' }},高级设置:{{
advancedExpanded ? '展开' : '收起'
}}</span
>
</NsSpace>
<NsForm label-width="80px" style="margin-top: 16px">
<NsFormSection v-model:expanded="baseExpanded" title="基础信息" collapsible>
<NsFormItem label="名称">
<NsInput />
</NsFormItem>
</NsFormSection>
<NsFormSection v-model:expanded="advancedExpanded" title="高级设置" collapsible>
<NsFormItem label="编码">
<NsInput />
</NsFormItem>
<NsFormItem label="排序">
<NsInput />
</NsFormItem>
</NsFormSection>
</NsForm>
</template>
collapse-text、expand-text 改按钮文字,例如英文界面:
<template>
<NsFormSection title="Advanced" collapsible collapse-text="Collapse" expand-text="Expand">
...
</NsFormSection>
</template>
可以直接试的版本:
<template>
<NsForm label-width="80px">
<NsFormSection title="Advanced" collapsible collapse-text="Collapse" expand-text="Expand">
<NsFormItem label="Code">
<NsInput />
</NsFormItem>
</NsFormSection>
</NsForm>
</template>
标题、提示和右侧按钮
title插槽替换标题文字,可以放必填星号这类内容;tip插槽显示在标题后面,是次要色的小一号文字,适合放说明或帮助图标;extra插槽放在标题行右侧、折叠按钮前面,适合放“新增”这类按钮。
<script setup lang="ts">
import { NsFormSection, NsButton, NsIcon, NsTooltip } from '@ns/ui'
</script>
<template>
<NsFormSection title="联系人" collapsible>
<template #tip>至少填写一位联系人</template>
<template #extra>
<NsButton size="small" type="primary" icon="plus">新增</NsButton>
</template>
...
</NsFormSection>
<NsFormSection>
<template #title>结算信息 <span style="color: var(--ns-color-danger)">*</span></template>
<template #tip>
<NsTooltip content="开票信息以财务系统为准">
<NsIcon name="help" />
</NsTooltip>
</template>
...
</NsFormSection>
</template>
放进表单的完整例子:点“新增”加一位联系人,联系人超过一位时每行可以删除;“结算信息”的标题用插槽加了红色星号,提示是一个带气泡说明的图标。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsButton, NsForm, NsFormItem, NsFormSection, NsIcon, NsInput, NsTooltip } from '@ns/ui'
let seed = 1
const form = reactive({
contacts: [{ id: seed, name: '', phone: '' }],
taxNo: ''
})
const addContact = () => form.contacts.push({ id: ++seed, name: '', phone: '' })
const removeContact = (index: number) => form.contacts.splice(index, 1)
</script>
<template>
<NsForm :model="form" label-width="80px">
<NsFormSection title="联系人" collapsible>
<template #tip>至少填写一位联系人</template>
<template #extra>
<NsButton size="small" type="primary" icon="plus" @click="addContact">新增</NsButton>
</template>
<div v-for="(contact, index) in form.contacts" :key="contact.id" class="contact-row">
<NsFormItem :label="`联系人 ${index + 1}`" :prop="`contacts.${index}.name`">
<NsInput v-model="contact.name" placeholder="姓名" />
</NsFormItem>
<NsFormItem label="电话" :prop="`contacts.${index}.phone`">
<NsInput v-model="contact.phone" />
</NsFormItem>
<NsButton
v-if="form.contacts.length > 1"
variant="text"
type="danger"
icon="trash"
aria-label="删除这位联系人"
@click="removeContact(index)"
/>
</div>
</NsFormSection>
<NsFormSection>
<template #title>结算信息 <span style="color: var(--ns-color-danger)">*</span></template>
<template #tip>
<NsTooltip content="开票信息以财务系统为准">
<NsIcon name="help" />
</NsTooltip>
</template>
<NsFormItem label="税号" prop="taxNo">
<NsInput v-model="form.taxNo" />
</NsFormItem>
</NsFormSection>
</NsForm>
</template>
<style scoped>
.contact-row {
display: flex;
flex-wrap: wrap;
align-items: flex-start;
column-gap: var(--ns-spacing-4);
}
.contact-row > :deep(.ns-form-item) {
flex: 1;
min-width: 200px;
}
</style>
不同尺寸
size 有 large、default、small 三种:
| 尺寸 | 标题 | 提示、折叠按钮文字 | 折叠箭头 | 标题行最小高度 | 标题线到内容、分组之间的距离 |
|---|---|---|---|---|---|
| large | 18px | 16px | 18px | 40px | 20px |
| default | 16px | 14px | 16px | 32px | 16px |
| small | 14px | 12px | 14px | 24px | 12px |
标题行的最小高度和同尺寸的按钮一样,extra 里放同尺寸的按钮时标题行不会变高。不写 size 时跟随所在 NsForm 的 size,表单也没写时跟随 NsConfigProvider,都没有时是 default。
下面三个分组分别写了 size,标题、提示、折叠按钮和右侧同尺寸的按钮一起对比:
<template>
<NsForm label-width="80px">
<NsFormSection title="大(large)" size="large" collapsible>
<template #tip>提示文字</template>
<template #extra>
<NsButton size="large" icon="plus">新增</NsButton>
</template>
<NsFormItem label="名称" size="large"><NsInput /></NsFormItem>
</NsFormSection>
<NsFormSection title="默认(default)" size="default" collapsible>
<template #tip>提示文字</template>
<template #extra>
<NsButton icon="plus">新增</NsButton>
</template>
<NsFormItem label="名称"><NsInput /></NsFormItem>
</NsFormSection>
<NsFormSection title="小(small)" size="small" collapsible>
<template #tip>提示文字</template>
<template #extra>
<NsButton size="small" icon="plus">新增</NsButton>
</template>
<NsFormItem label="名称" size="small"><NsInput /></NsFormItem>
</NsFormSection>
</NsForm>
</template>
没写 size 的分组跟随表单,例如 <NsForm size="large"> 里的分组就是 large。切换表单的 size,分组、表单项和控件一起变:
<script setup lang="ts">
import { ref } from 'vue'
import { NsForm, NsFormItem, NsFormSection, NsInput, NsSegmented } from '@ns/ui'
import type { FormSize } from '@ns/ui'
const size = ref<string | number>('large')
const sizes = [
{ label: '大(large)', value: 'large' },
{ label: '默认(default)', value: 'default' },
{ label: '小(small)', value: 'small' }
]
</script>
<template>
<NsSegmented v-model="size" :options="sizes" />
<NsForm :size="size as FormSize" label-width="80px" style="margin-top: 16px">
<NsFormSection title="基础信息" collapsible>
<template #tip>跟随表单的 size</template>
<NsFormItem label="名称"><NsInput /></NsFormItem>
</NsFormSection>
<NsFormSection title="联系方式">
<NsFormItem label="手机号"><NsInput /></NsFormItem>
</NsFormSection>
</NsForm>
</template>
分组里用栅格
分组的内容区就是普通的容器,可以放 NsRow、NsCol 排多列。
<template>
<NsForm label-width="80px">
<NsFormSection title="基础信息">
<NsRow :gutter="24">
<NsCol :span="12"
><NsFormItem label="名称"><NsInput /></NsFormItem
></NsCol>
<NsCol :span="12"
><NsFormItem label="编码"><NsInput /></NsFormItem
></NsCol>
</NsRow>
</NsFormSection>
</NsForm>
</template>
校验失败时展开分组
收起的分组里的表单项照常参与校验,但提示被藏起来看不到。可以在 validate() 之后检查没通过的字段属于哪个分组,把那个分组的 expanded 设回 true。下面“高级设置”默认收起,里面的“编码”必填,直接点“保存”试试:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsFormSection, NsInput, NsMessage } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const advancedExpanded = ref(false)
const form = reactive({ name: '默认名称', code: '' })
const rules: Record<string, FormRule[]> = {
name: [{ required: true, message: '请输入名称' }],
code: [{ required: true, message: '请输入编码' }]
}
// 高级设置分组里的字段
const advancedFields = ['code']
const save = async () => {
const { valid, errors } = await formRef.value!.validate()
if (valid) {
NsMessage.success('保存成功')
return
}
if (Object.keys(errors).some((prop) => advancedFields.includes(prop))) {
advancedExpanded.value = true
}
}
</script>
<template>
<NsForm ref="formRef" :model="form" :rules="rules" label-width="80px" @submit.prevent>
<NsFormSection title="基础信息">
<NsFormItem label="名称" prop="name">
<NsInput v-model="form.name" />
</NsFormItem>
</NsFormSection>
<NsFormSection v-model:expanded="advancedExpanded" title="高级设置" collapsible>
<NsFormItem label="编码" prop="code">
<NsInput v-model="form.code" />
</NsFormItem>
</NsFormSection>
<NsFormItem>
<NsButton type="primary" @click="save">保存</NsButton>
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | - | 分组标题;也可以用 title 插槽 |
| collapsible | boolean | false | 是否可折叠。为 false 时内容一直显示,不显示折叠按钮 |
| expanded | boolean | true | 是否展开,支持 v-model:expanded。只在 collapsible 时起作用 |
| collapseText | string | '收起' | 展开时折叠按钮的文字 |
| expandText | string | '展开' | 收起时折叠按钮的文字 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随所在 NsForm 的 size,再没有就跟随 NsConfigProvider,都没有时是 'default' |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:expanded | (expanded: boolean) | 点折叠按钮切换展开状态时触发,v-model:expanded 用的就是它 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 分组的内容,一般是 NsFormItem |
| title | - | 自定义标题,替换 title 属性 |
| tip | - | 标题后面的提示,次要色、比标题小一号 |
| extra | - | 标题行右侧的内容,在折叠按钮前面 |
方法
没有对外暴露的方法。用 v-model:expanded 控制展开和收起。
类型
import type { FormSectionProps, FormSectionEmits, FormSectionSize } from '@ns/ui'
type FormSectionSize = 'large' | 'default' | 'small'
interface FormSectionProps {
title?: string
collapsible?: boolean
expanded?: boolean
collapseText?: string
expandText?: string
size?: FormSectionSize
}
interface FormSectionEmits {
'update:expanded': [expanded: boolean]
}
注意事项
- 收起时内容用
v-show隐藏,里面的表单项不会销毁:值保留,resetFields照常重置,校验时也照常参与。收起的分组里校验没通过时,提示被藏起来看不到,可以在校验失败后把对应分组的expanded设回true。 - 分组之间的距离用的是上内边距,不会和上面表单项的
margin-bottom(16px)合并:上面是分组还是普通表单项,看上去的距离都一样。第一个分组(父元素里的第一个子元素)上面不留距离。 - 只有标题、
tip、extra都没有,也不可折叠时,才不渲染标题行,这时只剩内容。 - 折叠按钮是
type="button"的原生按钮,放在<form>里点它不会提交表单;它能用 Tab 聚焦,回车、空格触发,带aria-expanded和指向内容区的aria-controls。分组的根元素是role="group",用标题作可读名称。 - 只有点折叠按钮才会切换,点标题文字不会。
- 左侧竖条是主色(
--ns-color-primary),分隔线是--ns-border-color-light,暗色主题和配色方案切换时自动跟着变。 - 分组不是表单控件,不会登记到
NsFormItem,也不受表单的disabled影响(里面的控件照常受影响)。