# 组件文档 · 表单与弹窗
表单三件套:**容器**(`s-form-layout` 整页 / `s-modal` 弹窗 / `s-drawer` 抽屉)+ **`s-form`**(网格布局 + 校验)+ **`s-form-item`**(单字段)。
---
## 一、s-form(表单核心)
```vue
```
### Props
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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)`),格子宽度自动均分,不用写栅格。
### 实例方法
```js
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() // 只清校验提示
```
### 校验规则
```js
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:
```js
const rules = computed(() => ({
loginName: [{ required: createAccount.value, message: '请输入账号', trigger: 'blur' }]
}))
```
---
## 二、s-form-item
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `label` | String | `''` | 字段标签 |
| `name` | String / Array | `''` | 校验字段名,须与 `model` 字段一致;数组表示嵌套字段 `['db', 'code']` |
| `labelWidth` | Number / String | `'100%'` | 单独指定标签宽度 |
| `full` | Boolean | `false` | 多列布局下独占一整行 |
`name` 必须写,否则 `rules` 里对应的规则不生效、`validate()` 也校验不到这个字段。
隐藏字段照常放:
```vue
```
字段级禁用:直接给控件加 `:disabled`,或整体只读时给控件统一传。
布尔类属性(`disabled` / `allowClear` / `showSearch` / `multiple` …)统一传布尔值,用 `!!` 显式转换:`:disabled="!!(cond && obj.id)"`。
---
## 三、s-form-layout(整页表单)
自带标题栏、内容区、底部固定按钮(取消 / 保存),内容区超宽时居中并限宽。
```vue
```
### Props
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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\ |
| `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` 配置。
```js
const onFooter = (type) => {
if (type === 'save') handleSave()
if (type === 'cancel') router.back()
}
```
### 分组表单
```vue
```
`s-collapses-item` 属性:`title`(分组标题)、`column`(组内列数,最大 4)、`full`(独占一行)。
> 用 `#collapses` 时 `s-form-item` 的校验仍要挂在一个 `s-form` 上。做法:`#form` 里放一个空的 `s-form` 包裹 `#collapses`,或把整块内容放进 `#form` 里用 `s-collapses` 分隔(推荐后者,校验链完整)。
---
## 四、s-modal(弹窗)
```vue
取消
保存
```
### Props
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` | 自定义底部按钮;不写则渲染"关闭 + 保存"两个按钮 |
### 弹窗表单标准写法
父页面:
```vue
```
```js
const formRef = ref(null)
const reload = () => layoutRef.value.reload()
const add = () => formRef.value.add()
const edit = (record) => formRef.value.edit(record.id)
```
`form.vue`:
```vue
...
取消
保存
```
```js
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(抽屉)
```vue
...
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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-footer-tool-bar(自定义底栏)
不用 `s-form-layout` 但需要贴底按钮条时:
```vue
共 12 项
取消
保存
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `fixed` | Boolean | `true` | 是否贴底固定 |
| `extra` | String / Object | `''` | 左侧内容(有 `#extra` 插槽时以插槽为准) |
插槽 `#extra` 左区,默认插槽右区。用 `fixed` 时记得给页面内容留底部空间。
---
## 七、s-import-modal(导入弹窗)
列表页 `import` 按钮已内置一个,需要独立调用时:
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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`,所有控件统一禁用即可(不用另找展示组件):
```vue
启用
```
或者用 `s-panel-layout`(只有标题栏 + 内容区,没有底部按钮):
```vue
...
```
`s-panel-layout` 属性:`title`、`showTitle`(默认 true)、`height`(默认 `'100%'`)、`width`(默认 `'100%'`,传固定值则居中)、`headerSticky`(内容滚动时标题吸顶)。插槽:`default`、`title`、`extra`、`footer`。