# 组件文档 · 表单与弹窗 表单三件套:**容器**(`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 取消 保存 ``` | 属性 | 类型 | 默认 | 说明 | |---|---|---|---| | `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`。