表单三件套:容器(s-form-layout 整页 / s-modal 弹窗 / s-drawer 抽屉)+ s-form(网格布局 + 校验)+ s-form-item(单字段)。
<s-form ref="formRef" :model="form" :rules="rules" :column="2">
<s-form-item label="名称" name="name">
<a-input v-model:value="form.name" placeholder="请输入名称" :maxlength="200" />
</s-form-item>
<s-form-item label="备注" name="remark" full>
<a-textarea v-model:value="form.remark" :rows="3" />
</s-form-item>
</s-form>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
model |
Object | {} |
表单数据对象 |
rules |
Object | {} |
校验规则,键是 s-form-item 的 name |
column |
Number / String | 1 |
每行列数,最大 4,超过按 4 处理 |
layout |
String | 'vertical' |
vertical 标签在上;horizontal 标签在左 |
labelWidth |
Number / String | 80 |
horizontal 时的标签宽度 px |
表单内部是 CSS Grid(repeat(column, 1fr)),格子宽度自动均分,不用写栅格。
const formRef = ref(null)
// 校验:Promise 式(推荐)
formRef.value.validate().then(() => { /* 通过 */ }).catch(() => { /* 未通过,可留空 */ })
// 校验指定字段
formRef.value.validate(['name', 'code']).then(...)
// 回调式(老项目迁移代码常见)
formRef.value.validate((valid, err) => { if (valid) submit() })
// 单字段校验
formRef.value.validateField('code')
formRef.value.setFieldsValue({ name: 'x' }) // 赋值
formRef.value.getFieldsValue() // 取值
formRef.value.resetFields() // 重置(回到初始值并清校验)
formRef.value.clearValidate() // 只清校验提示
const rules = {
name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
code: [
{ required: true, message: '请输入编码', trigger: 'blur' },
{ max: 50, message: '最多 50 个字符', trigger: 'blur' }
],
phone: [{ pattern: /^1[3-9]\d{9}$/, message: '手机号格式不正确', trigger: 'blur' }],
sort: [{ validator: positiveInteger, trigger: 'blur' }]
}
// 自定义校验:返回 resolve 通过,reject 报错
const positiveInteger = (rule, value) => {
if (!value) return Promise.resolve()
return /^[1-9]+[0-9]*$/.test(value) ? Promise.resolve() : Promise.reject(new Error('请输入正整数'))
}
规则依赖运行时状态(如"是否必填"跟着开关变)时,用 computed 生成 rules:
const rules = computed(() => ({
loginName: [{ required: createAccount.value, message: '请输入账号', trigger: 'blur' }]
}))
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
label |
String | '' |
字段标签 |
name |
String / Array | '' |
校验字段名,须与 model 字段一致;数组表示嵌套字段 ['db', 'code'] |
labelWidth |
Number / String | '100%' |
单独指定标签宽度 |
full |
Boolean | false |
多列布局下独占一整行 |
name 必须写,否则 rules 里对应的规则不生效、validate() 也校验不到这个字段。
隐藏字段照常放:
<s-form-item label="id" name="id" v-show="false">
<a-input :value="form.id" />
</s-form-item>
字段级禁用:直接给控件加 :disabled,或整体只读时给控件统一传。
布尔类属性(disabled / allowClear / showSearch / multiple …)统一传布尔值,用 !! 显式转换::disabled="!!(cond && obj.id)"。
自带标题栏、内容区、底部固定按钮(取消 / 保存),内容区超宽时居中并限宽。
<s-form-layout :title="$l('人员-新增')" :loading="spinning" @footer-callback="onFooter">
<template #form>
<s-form ref="formRef" :model="form" :rules="rules" :column="2">
<s-form-item label="姓名" name="name">
<a-input v-model:value="form.name" />
</s-form-item>
</s-form>
</template>
</s-form-layout>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
title |
String | 必填 | 页面标题 |
subTitle |
String | '' |
标题后问号图标的提示文案 |
loading |
Boolean | false |
内容区 loading 遮罩 |
showAnchor |
Boolean | true |
右侧锚点导航(配 #collapses 用) |
goBack |
Boolean | true |
显示"取消"按钮 |
isShowSave |
Boolean | true |
显示"保存"按钮 |
saveBtnText |
String | '保存' |
保存按钮文案 |
width |
String | '1000px' |
表单内容区宽度,超出容器时自适应 |
formStyle |
Object | {} |
表单区自定义样式 |
steps |
Array | [] |
步骤条标题数组,传了才显示步骤区 |
stepDefaultActive |
Number | 0 |
步骤条起始下标 |
stepValid |
Function | — | 切换下一步前的校验,返回 Promise<Boolean> |
tabs |
Array | [] |
页签配置,传了才显示页签 |
tabKey |
Object | { label: 'label', value: 'value' } |
页签字段映射 |
| 插槽 | 说明 |
|---|---|
form |
表单主体(放 s-form) |
collapses |
分组折叠区(放 s-collapses + s-collapses-item),配 showAnchor 自动生成右侧锚点 |
otherBtns |
标题栏右侧按钮 |
footer |
底部按钮区追加内容 |
other |
根节点末尾,通常放弹窗 |
@footer-callback="(type) => {}",type 取值:
| type | 触发时机 |
|---|---|
'save' |
点保存 |
'cancel' |
点取消(goBack 为 true 时) |
'prev' |
步骤条上一步,第二参为当前步 |
'next' |
步骤条下一步(stepValid 返回 true 才切) |
另有 @tabsChange="(item) => {}",参数是选中的那条 tabs 配置。
const onFooter = (type) => {
if (type === 'save') handleSave()
if (type === 'cancel') router.back()
}
<s-form-layout :title="$l('设备台账')">
<template #collapses>
<s-collapses>
<s-collapses-item title="基本信息" :column="2">
<s-form-item label="设备名称" name="name"><a-input v-model:value="form.name" /></s-form-item>
<s-form-item label="设备编号" name="no"><a-input v-model:value="form.no" /></s-form-item>
</s-collapses-item>
<s-collapses-item title="扩展信息" :column="3">
<s-form-item label="厂商" name="vendor"><a-input v-model:value="form.vendor" /></s-form-item>
</s-collapses-item>
</s-collapses>
</template>
</s-form-layout>
s-collapses-item 属性:title(分组标题)、column(组内列数,最大 4)、full(独占一行)。
用
#collapses时s-form-item的校验仍要挂在一个s-form上。做法:#form里放一个空的s-form包裹#collapses,或把整块内容放进#form里用s-collapses分隔(推荐后者,校验链完整)。
<s-modal v-model:value="visible" :title="title" width="50%" :loading="spinning" @handCancel="close">
<s-form ref="formRef" :model="form" :rules="rules" :column="2">
<s-form-item label="名称" name="name"><a-input v-model:value="form.name" /></s-form-item>
</s-form>
<template #footer>
<a-button @click="close">取消</a-button>
<a-button type="primary" :loading="spinning" @click="handleSave">保存</a-button>
</template>
</s-modal>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
Boolean | false |
显隐,v-model:value |
title |
String | '' |
标题(标题栏可拖动窗口) |
width |
String / Number | '60vw' |
弹窗宽度 |
loading |
Boolean | false |
内容区 loading 遮罩 |
centered |
Boolean | true |
垂直居中 |
maskClosable |
Boolean | true |
点遮罩关闭 |
mask |
Boolean | true |
显示遮罩 |
keyboardOpen |
Boolean | true |
支持 Esc 关闭 |
destroyOnClose |
Boolean | false |
关闭后销毁内容 |
showFullScreen |
Boolean | true |
标题栏显示全屏按钮 |
bodyStyle |
Object | 纵向滚动 | 内容区样式 |
tabs |
Array | [] |
页签配置 |
tabKey |
Object | { label, value } |
页签字段映射 |
steps |
Array | [] |
步骤条标题数组 |
stepDefaultActive |
Number | 0 |
— |
stepValid |
Function | — | 下一步前校验 |
saveBtnText |
String | '保存' |
内置底部保存按钮文案 |
| 事件 | 说明 |
|---|---|
update:value |
显隐变化(v-model 自动处理) |
handCancel |
点右上角关闭 / 遮罩关闭 |
afterClose |
关闭动画结束 |
handSave |
用了内置底部按钮时点"保存"(自定义 #footer 就不触发) |
| 插槽 | 说明 |
|---|---|
default |
弹窗内容 |
footer |
自定义底部按钮;不写则渲染"关闭 + 保存"两个按钮 |
父页面:
<template #other>
<FormModal ref="formRef" @reload="reload" />
</template>
const formRef = ref(null)
const reload = () => layoutRef.value.reload()
const add = () => formRef.value.add()
const edit = (record) => formRef.value.edit(record.id)
form.vue:
<s-modal v-model:value="visible" :title="title" width="50%" :loading="spinning">
<s-form ref="formRef" :model="form" :rules="rules" :column="2">...</s-form>
<template #footer>
<a-button @click="close">取消</a-button>
<a-button type="primary" :loading="spinning" @click="handleSave">保存</a-button>
</template>
</s-modal>
const emit = defineEmits(['reload'])
const visible = ref(false)
const spinning = ref(false)
const title = ref('')
const formRef = ref(null)
const form = reactive({ id: undefined, name: '' })
const add = () => {
title.value = '新增'
Object.assign(form, { id: undefined, name: '' })
formRef.value?.clearValidate()
visible.value = true
}
const edit = (id) => {
title.value = '编辑'
spinning.value = true
getById(id).then((res) => {
Object.assign(form, res)
visible.value = true
}).finally(() => (spinning.value = false))
}
const handleSave = () => {
formRef.value.validate().then(() => {
spinning.value = true
save({ ...form }).then(() => {
window.$notice.success({ message: '操作成功', description: '保存成功' })
visible.value = false
emit('reload')
}).finally(() => (spinning.value = false))
}).catch(() => {})
}
const close = () => { visible.value = false }
defineExpose({ add, edit })
要点:
visible,对外只暴露 add() / edit(id)。emit('reload') 让父页面刷新列表,再关弹窗。resetFields() 清空:它回到初始值而不是空值,新增/编辑切换容易串数据。要么 Object.assign 显式赋值,要么给弹窗加 destroyOnClose 让内容重建。<s-drawer v-model:value="visible" title="编辑" mode="right" :width="600" @confirm="handleSave">
<s-form ref="formRef" :model="form" :rules="rules">...</s-form>
</s-drawer>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
Boolean | false |
显隐,v-model:value |
title |
String | '' |
标题 |
mode |
String | 'right' |
right / left / top / bottom |
width |
Number | 500 |
左右方向宽度 px |
height |
Number | 378 |
上下方向高度 px |
事件:update:value、confirm(点内置"确定")。插槽:default、footer(不写则内置"取消 + 确定")。
不用 s-form-layout 但需要贴底按钮条时:
<s-footer-tool-bar>
<template #extra>
<span>共 12 项</span>
</template>
<a-button @click="close">取消</a-button>
<a-button type="primary" @click="save">保存</a-button>
</s-footer-tool-bar>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
fixed |
Boolean | true |
是否贴底固定 |
extra |
String / Object | '' |
左侧内容(有 #extra 插槽时以插槽为准) |
插槽 #extra 左区,默认插槽右区。用 fixed 时记得给页面内容留底部空间。
列表页 import 按钮已内置一个,需要独立调用时:
<s-import-modal
v-model:value="importVisible"
:upload-url="IMPORT_UPLOAD_URL"
:columns="importColumns"
:apis="{ templateDownload, importPreview, importData, exportExceptionData }"
@reload="reload"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
Boolean | false |
显隐,v-model:value |
title |
String | '批量导入' |
— |
width |
String / Number | 1000 |
— |
uploadUrl |
String | '' |
文件上传地址(含网关名) |
columns |
Array | [] |
预览表头,接口返回 headerRow 后以接口为准 |
apis |
Object | {} |
{ templateDownload, importPreview, importData, exportExceptionData } |
typeSelect |
Object | null |
附加下拉 { options, value, placeholder, loading } |
extraKey |
String | 'deviceTypeId' |
下拉值提交时的字段名 |
事件:update:value、reload(导入成功)。
详情用 s-form-layout + s-form,所有控件统一禁用即可(不用另找展示组件):
<s-form-layout :title="$l('详情')" :isShowSave="false" @footer-callback="onFooter">
<template #form>
<s-form :model="form" :column="2">
<s-form-item label="名称"><a-input :value="form.name" disabled /></s-form-item>
<s-form-item label="状态">
<a-select :value="form.status" disabled>
<a-select-option :value="1">启用</a-select-option>
</a-select>
</s-form-item>
</s-form>
</template>
</s-form-layout>
或者用 s-panel-layout(只有标题栏 + 内容区,没有底部按钮):
<s-panel-layout title="设备详情" height="100%">
<div>...</div>
</s-panel-layout>
s-panel-layout 属性:title、showTitle(默认 true)、height(默认 '100%')、width(默认 '100%',传固定值则居中)、headerSticky(内容滚动时标题吸顶)。插槽:default、title、extra、footer。