03-组件文档-表单与弹窗.md 14 KB

组件文档 · 表单与弹窗

表单三件套:容器(s-form-layout 整页 / s-modal 弹窗 / s-drawer 抽屉)+ s-form(网格布局 + 校验)+ s-form-item(单字段)。


一、s-form(表单核心)

<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>

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)),格子宽度自动均分,不用写栅格。

实例方法

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' }]
}))

二、s-form-item

属性 类型 默认 说明
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(整页表单)

自带标题栏、内容区、底部固定按钮(取消 / 保存),内容区超宽时居中并限宽。

<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>

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<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(弹窗)

<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>

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 自定义底部按钮;不写则渲染"关闭 + 保存"两个按钮

弹窗表单标准写法

父页面:

<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(抽屉)

<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-footer-tool-bar(自定义底栏)

不用 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 时记得给页面内容留底部空间。


七、s-import-modal(导入弹窗)

列表页 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。