Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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影响(里面的控件照常受影响)。