sapit-ui-基座说明与业务使用.md 129 KB

sapit-ui 基座说明与业务使用文档

适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、sapit-base-template(业务示例)

本文档也是基座内置文档页 /docs 与组件页 /components 的数据源。


目录


一、总览

1.1 五者关系

工程 角色 说明
sapit-ui-framework 基座(源码) 内置组件与常用依赖的库工程,Vite lib 模式打包
sapit-ui-plus 发布产物 基座 dist 推送后的 git 仓库(lib/、docs/、vite-plugins/)
sapit-base-template 业务使用者 以 sapit-ui-plus git 依赖为底层,编写业务页面/配置
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template

1.2 目录结构(基座)

sapit-ui-framework/
├─ packages/                 # 发布内容来源(入口依赖图)
│  ├─ index.js               # 库入口,导出 registerGlobalConfig
│  ├─ components/            # 内置组件 S*
│  ├─ layouts/               # BasicLayout / BlankLayout / UserLayout / RouteView / PageView
│  ├─ router/                # 常量路由 + 动态路由 + 静态路由 + 守卫
│  ├─ store/ api/ utils/ locales/ static/ style/
│  └─ pages/      # 登录、工作台、待办、消息、404/403/500、docs 文档页
├─ docs/                     # 本文档(供内置 /docs 渲染)
├─ vite-plugins/             # docs-viewer 插件
├─ src/                      # 基座自身调试壳
└─ vite.config.js / package.json

二、基座提供的内容

2.1 全局组件

packages/index.js 用 import.meta.glob('./components/**/*.vue') 把 components/**/*.vue 按文件名全局注册,模板直接以文件名标签使用(如 <s-modal>、<s-user-select>)。

分类 组件
布局类 SSkeletonLayout(骨架布局:标题 + 按钮组 + 内容区,见 2.16)、SListLayout、SListCardLayout(卡片列表,见 2.19)、SListTableTreeLayout、SSuperListLayout(高级列表,见 2.20)、SFormLayout、SPanelLayout、SCollapses/SCollapsesItem、SDrawer
弹层类 SModal、SModalTemplate、ModalHeader、SIconModal、SImportModal(批量导入,见 2.11)
表单/筛选 SForm、SFormItem(多列 + full 独占整行,见 3.4)、SExtendFieldsForm/SExtendFieldsFormItem(动态扩展字段)、SFilterWrap、SFilterItem(full 独占整行,见 3.4)、SFilterToolbar(查询区外壳:主区 + 更多筛选折叠 + 条件重置,见 3.4)、STableToolbar(表格区外壳:表体高度自动贴合内容区,与 SFilterToolbar 成对使用,见 3.4)、SFilterTableToolbar(查询区 + 表格区组合件,见 2.22)、SCascader、STree、STreeSelect、SDataRangeTreeSelect(数据权限范围树)、SUserSelect、SUserSelectButton、SChooseUser(带数据权限选人弹窗,见 2.14)、SBelowChoosePosition(选岗位弹窗,见 2.15)、SOfficeSelect、SIconSelect(图标下拉,可搜索/多选)、SIconSelectPopover(图标网格面板)、SIconModal(图标浏览弹窗)
上传类 SFileUpload、SDraggerUpload、SCopperUpload、CropperModal
展示/其它 STab/STabItem(标签栏,超出宽度自动出左右箭头,见 2.21)、SEditor、SEmpty、SIcon、SSvg、SAnchor、SColorPicker、SToggleLanguage、SettingFilter、SettingColumns、SSideMenu/STopMenu

组件用法见内置组件页 /components(含「s组件」「工具/配置」两个标签页;「工具/配置」列出 web-config 全部配置项与 $utils 全部方法)。

注册规则:components/**/*.vue 按文件名全局注册(SForm.vue → <SForm>,不是 kebab-case),冲突后者覆盖。 Table/index.jsx 是 .jsx、import.meta.glob 匹配不到,基座在packages/index.js 里单独注册为全局 STable(<s-table> 可直接用,无需 import)。 @ant-design/icons-vue 图标全部全局注册并挂到 $icons。 另有内部辅助组件不对外使用:ModalHeader(SModal)、CropperModal(SCopperUpload)、CustomInput/SettingColumns/SettingFilter(SSuperListLayout)。

2.1.1 布局组件选择

场景 用哪个
标题 + 按钮 + 自定义内容(无表格/分页/表单) SSkeletonLayout(见 2.16,自带标题条与权限按钮)
普通列表页 SListLayout
卡片列表 SListCardLayout(卡片网格 + 三插槽,见 2.19)
列表 + 左侧树 SListTableTreeLayout(左侧树容器类名必须是 .side.s-side-tree,见 3.5)
带高级搜索/高级表格的列表 SSuperListLayout(列设置 + 高级筛选,见 2.20)
新增/编辑/详情(路由式) SFormLayout(#form 插槽放 SForm,#footer-callback 收 save/cancel/prev/next)
表单作为弹窗内容 SModal(不要套 SFormLayout)
后端下发字段的动态表单 SExtendFieldsForm(data + defaultValue,ref 调 validate/clearValidate/getModel)
数据权限范围选择 SDataRangeTreeSelect(autoSysConfig 托管系统 dataScope 配置)

2.2 全局属性 / 方法

$registerGlobalConfig 执行后可用(this.$xxx / 模板 $xxx / window.$xxx):

名称 说明
$registerGlobalConfig(config, pages) 初始化入口(见 5.2)
$utils 工具类集合:$utils.env / $utils.ls / $utils.http 及通用方法
env 合并后的环境配置(= $utils.env)
$i18n / $l(name, key) 国际化(见 2.7)。挂在 globalProperties 上:模板里直接用 $l('xx');<script setup> 脚本内必须写 window.$l('xx')(setup 作用域没有 this)
$theme / $staticRoutes / $pinia 主题对象 / 静态路由列表 / 用户 store 实例
$modal / $message / $notice / $confirm antd 的 Modal / message / notification / Modal.confirm(列表组件按钮 api 分支会调 this.$confirm)
$push(path, query) / $open(...) 站内跳转 / 新窗口(自动拼 VITE_APP_BASE_URL)
$filter / $icons / $socket 日期格式化 / 图标集合 / websocket 封装。$icons 是 @ant-design/icons-vue 全量按 Pascal 名注册的映射(InfoCircleOutlined),同时挂在 window.$icons(供 $utils.iconOf 在非组件上下文取用)。<a-icon type="info-circle"> 这类 antd v1 写法用 $utils.iconOf('info-circle') 换算;SIcon 的 name 只吃 Pascal 名
$getPdf({ el, title }) 页面导出 PDF(老项目 Vue.prototype.getPdf 的 Vue3 版)。截图容器与文件名显式传:<a-button @click="$getPdf({ el: '#pdfDom', title: htmlTitle })">导出</a-button>。内部动态 import html2canvas + jsPDF,不点按钮不加载;A4 自动分页,返回 Promise<boolean>。可选 fileName / scale / backgroundColor / beforeCapture / afterCapture / onError。同时挂了无 $ 的 getPdf 兼容老写法(默认容器 #pdfDom、标题取 document.title)

2.3 布局

packages/layouts/index.js:BasicLayout(头部+侧边菜单+内容区)、BlankLayout、UserLayout(登录)、RouteView、PageView。

BasicLayout 的高度链路(业务布局组件必须与它对齐,详见第三章):

.basic-layout-common (100vh)
→ .ant-layout
→ .main-content
→ .container (height = mainHeight = clientHeight - headerHeight)
   └─ 有页脚时再减 footerHeight(56)
   → router-view (height = contentHeight, overflow: hidden auto)
      → 业务布局组件(.list-layout / .form-layout,flex:1)

mainHeight / contentHeight 用真实 header.offsetHeight(不是写死 58)计算,避免与实际渲染不一致产生溢出滚动条。

2.4 路由

常量路由(packages/router/index.js):

路径 说明
/login/index 登录页(默认基座,可被业务覆盖,见 5.3)
/login/:officeCode 同上,带单位编码进入(登录页把编码写进 $utils.ls 的 officeCode,后续登录沿用)
/user/qrCode、/user/forgotPassword、/user/activate 扫码登录 / 找回密码 / 账号激活三张独立页,父级 /user 带 meta.public,登录前可达;/user/login 重定向到 VITE_APP_LOGIN_PATH(见 2.10)
/workplace/index 默认首页(VITE_APP_DEFAULT_PATH,可被覆盖)
/workbench/index、/message/index 工作台 / 消息
/docs、/components 内置文档 / 组件页(public 免登录、hidden 不进菜单)
/404、/403、/500、/:pathMatch(.*)* 错误页;通配渲染 404(不用 redirect,保证刷新动态路由不掉 404)。四者都挂在 BasicLayout 下,只在内容区 router-view 内切换,侧边菜单与顶栏保持不变

错误页的触发规则、URL 参数、文案口径与改色方法见 2.17 错误页。

静态路由(staticRoutes,不依赖后端菜单):见 5.4。基座内置 /docs、/components。

动态路由(packages/router/generator-routers.js):登录后按后端 menus 生成树,根节点 BasicLayout;叶子节点用 item.hrefs 匹配业务 pages(import.meta.glob('@/views/**/*.vue') 的 key),匹配不到回退 404。注册在守卫中完成(内存标记,刷新重注册)。

守卫:公开页(meta.public)直接放行;实时读 token;未登录跳登录;已登录访问登录页/根跳默认首页;取用户信息失败清理并回登录页(避免 pending)。URL 带 code 时在守卫里换取 token(见 5.8 权限与 6.1)。

2.5 状态管理(pinia)

packages/store/user.js(useUserStore):state user/menus/permissions/clients/dynamicRouter/menuOpenKeys;actions Info()(拉取并写 localStorage)、setDynamicRouter()、setMenuOpenKeys();localStorage 持久化。

2.6 工具类($utils)

模块 说明
$utils.env 环境配置对象
$utils.ls 本地存储(命名空间 VITE_APP_SYS_SERVER_NAME)
$utils.http axios 实例(token/client-id 注入、响应解包、登录超时、文件下载)
parseAppUrl / innerRedirect 等 站内地址拼 base(支持子路径),外部 http(s) 原样
messageFormat(str, values) {0} / {name} 占位符替换,用于确认弹窗等文案
filterSelectOption(iv, opt) antd4 版 :filterOption(读 option.label / option.value)
randomDrawerPlacement() 随机返回 left / right / top / bottom(源项目交互保留)
getTableHeight({ selector, offset }) 列表页表格高度 = 窗口高 − 搜索区高 − 偏移(默认 .table-page-search-wrapper / 320,不传参即老项目原行为)。老项目固定高度撑表才用,基座 SListLayout 走 flex 自适应
iconOf(type) antd v1 <a-icon type="info-circle"> 遗留写法的换算:kebab / snake / Pascal 入参 → 图标组件。用法 <component :is="$utils.iconOf('info-circle')" />
hasAction(name) 按钮级权限函数式判断,与 v-action 同源;用于 v-if 里的「或 / 且」、算 disabled
其它 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等

⚠️ 类型判断 ≠ 格式校验:$utils.isNumber / isInt / isDate 是 Object.prototype.toString 类型判断($utils.isNumber('123') 恒 false),不是字符串格式校验。业务侧的正则版同名方法(如 isNumber(str) 用 /^(?:-?\d+|...)/)不可按名字替换过来。

同理 $utils.uuid(len) 是纯随机串,与「时间戳 + 随机数」型 getUUID() 产出格式不同,涉后端主键时不可换。

v-action:xxx 按钮级权限指令:<a-button v-action="'add'">添加</a-button>。

  • 内部直接调用 $utils.hasAction(actionName),指令与函数只有一套判定逻辑
  • 数据源优先级:permission(单数,router/index.js 守卫写入的「当前路由按钮数组」)→ 取不到再回退 permissions(复数,store/user.js 写入的全量「路由 → 按钮」map)+ CURRENT_ROUTER_KEY
  • 匹配规则:String(button_code) === String(actionName),整体相等(add 不会命中 batchAdd)
  • 函数式用法:<a-button v-if="$utils.hasAction('add') || $utils.hasAction('edit')">

2.7 国际化

语言包文件名统一为 i18n.js,放在模块的一级文件夹下,不带任何前缀,结构是扁平字典:

// src/views/user/i18n.js  ->  命名空间 user
export default {
  取消: 'Cancel'
}

命名空间取 views/ 或 packages/ 之后的第一段目录名(views/user/i18n.js → user,packages/components/i18n.js → components)。构建期由 import.meta.glob 统一聚合,新增文件、新增目录都不用改任何代码。

页面里不用注册也能翻译:$l('中文') 会自动找该页面所在目录的 i18n.js(路由加载组件时按源文件路径打标 __i18nNs,取不到再用路由 path 首段)。需要强制指定别的命名空间时才显式注册:

export default {
  created() {
    this.useI18n('user') // Options API,显式指定,优先级最高
  }
}
// <script setup>:可显式传,也可不传(不传就按当前目录自动推断)
const { $l } = useI18n() // 自动
const { $l } = useI18n('user') // 显式

$l(name) 查找顺序:当前命名空间(显式注册 > 同目录 i18n > 路由首段)→ components 通用词 → 全局兜底字典(packages/locales/lang/dict.js)→ 原样返回 + console.warn(同一个词只提示一次)。命名空间不存在时 useI18n 也会 console.warn,不阻断渲染。

调用位置 写法 是否带命名空间
模板 / 组件内 this.$l(...) {{ $l('取消') }} 带,自动按上述优先级解析
组件内 const { $l } = useI18n() $l('取消') 带,同上
组件外 JS(api / utils) window.$l('取消') 不带,只查 components + 全局字典

排查用:控制台执行 $i18nDebug(),会打印已加载的全部命名空间、当前组件解析到的命名空间及其词条数;$i18nNamespaces 是命名空间全量对象。

中文模式直接返回原文;英文模式查不到译文时原样返回中文并告警。antd 自身语言由 a-config-provider 的 locale 控制。

2.8 主题

定义只由基座维护:packages/config/web-config.js 的 VITE_APP_THEME(每套含 color/lightColor/darkColor/borderColor/bgColor);业务只用 VITE_APP_THEME_VALUE 选(blue/green/orange)。业务/config.json 传入的 VITE_APP_THEME 会被忽略。

生效方式:

  1. antd:a-config-provider token(colorPrimary/colorLink)。
  2. CSS 变量:启动时把选中主题算成整套令牌写入 :root(主题色系 10 个 + 语义色 11 个 + 中性色 11 个),并内置工具类 .s-theme-bg、.s-theme-color、.s-theme-border、.s-theme-border-top、.s-theme-icon-bg。
  3. body 类:theme-<VITE_APP_THEME_VALUE>(如 theme-blue)。
  4. 菜单配色:启动时按主题色推导(light)或固定 antd 黑(dark),全部输出实色 #rrggbb,不含透明度,写入 :root 的 --s-menu-bg、--s-menu-sub-bg、--s-menu-text、--s-menu-text-hover、--s-menu-text-active、--s-menu-hover-bg、--s-menu-active-bg、--s-menu-active-text,同时写入 window.$menuTheme(reactive,含 antd Menu token,isLightBg 标记实际明暗)。

菜单默认 light(按主题色相推导浅色底:orange #f9f1e1 / blue #e1ebf9 / green #e1f9ef)。具体色值只由基座控制:业务只能通过 VITE_APP_MENU_THEME 选浅 / 深,色值写在业务 .env / config.json 里会被基座强制回填掉。色板推导、系统深浅色跟随与锁定机制见 2.18 菜单配色。

light 下底色、悬停、选中、文字全部按主题色推导,切 VITE_APP_THEME_VALUE 整套跟着变,文字对比度按底求解仍 ≥ 4.6。默认还跟随系统深浅色(VITE_APP_THEME_FOLLOW_SYSTEM),系统切深色时菜单自动换黑。侧边菜单、顶部菜单(VITE_APP_MENU_BAR: 'top')、logo 明暗、顶栏文字色共用 window.$menuTheme.isLightBg 这一套判断。

.my-box {
  color: var(--s-color);
  background: var(--s-bg-color);
}

完整令牌清单(由 packages/utils/theme-vars.js 启动时写入 :root,组件与业务只用 var(--s-*),不写字面色值):

分组 令牌 默认值(blue) 说明
主题色系 --s-color #1677ff 主色,取 VITE_APP_THEME
--s-light-color、--s-dark-color、--s-border-color、--s-bg-color #6495ed、#00008b、#b0c4de、#f0f2f5 取主题定义
--s-color-hover / --s-color-active #4592ff / #146be6 悬停(混白 20%)/ 按下(混黑 10%)
--s-color-bg / --s-color-bg-hover / --s-color-border #e8f1ff / #d5e7ff / #adcfff 选中浅底 / 悬停浅底 / 浅边框
语义色 --s-color-success、--s-color-warning、--s-color-error、--s-color-info #52c41a、#faad14、#ff4d4f、#1677ff 状态语义,不随主题变
--s-color-success-bg、--s-color-warning-bg、--s-color-error-bg #f6ffed、#fffbe6、#fff1f0 状态浅底
--s-color-warning-light / --s-color-error-light #ffc069 / #ff7875 状态浅色变体(错误页插图)
--s-color-warning-border / --s-color-error-border rgba(250,140,22,.42) / rgba(245,34,45,.42) 状态半透明描边
中性色 --s-text-color #262626 主要文字
--s-text-color-regular #595959 常规文字
--s-text-color-secondary、--s-text-color-disabled、--s-text-color-inverse #8c8c8c、#bfbfbf、#ffffff 次要 / 禁用 / 反白
--s-border-color-base、--s-border-color-light、--s-border-color-split #d9d9d9、#e8e8e8、#f0f0f0 边框三级
--s-bg-color-container / --s-bg-color-hover #ffffff / #f5f5f5 容器底 / 悬停底
--s-mask-color rgba(0,0,0,.45) 遮罩

组件里已不再出现字面色值:主色相关走主题令牌,灰阶走中性令牌,状态走语义令牌。新增组件沿用同一套,不要再写 #1677ff / #e8e8e8 / rgba(0,0,0,.65)。

新增主题:基座 VITE_APP_THEME 加一套,业务 VITE_APP_THEME_VALUE 选它,antd 与 var(--s-*) 自动跟随。

2.9 API / 页面组件 / 其它

  • packages/api:login.js(登录、getCode、verify、rsaPublicKey、getLoginConfig 等)、common.js、upload.js、workbench.js。
  • packages/pages:login.vue、login-common/LoginForm.vue、workbench.vue、todo.vue、message.vue、403/404/500.vue、docs.vue、components-doc.vue。
  • 静态资源 packages/static/*;样式 packages/style/*;antd 图标、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.* 等已内置。

2.10 登录 / 单点

  • 登录页 /login/index:账号密码登录;登录失败达 getLoginConfig 策略(enabled + codeThreshold)时出现图片验证码(/user/verify),verificationCode 原文提交 + verificationCodeId。
  • 单点回调:URL 带 code 时由守卫调 getCode(code) 换 token → 存 $utils.ls → 去掉 code 整页刷新(与参照项目一致)。
  • 关联配置:VITE_APP_CLIENT_ID 必须等于业务在认证中心的 client;接口网关用 VITE_APP_PORTAL_SERVER_NAME。

四套登录主题(VITE_APP_LOGIN_PATH_THEME,取值 1~4,未配置或非法值回落 1):

packages/pages/login/index.vue 只负责取主题编号、透传 logo/sysName、渲染语言切换,具体版式在 login-themes/ 下的页面级组件里,互不影响、可单独改。

编号 组件 版式
1 LoginTheme1.vue 左右分栏:左侧 login-cover.png + logo + 系统名,右侧表单
2 LoginTheme2.vue 整屏 login-cover-right.png,表单靠左(padding-left: 336px)
3 LoginTheme3.vue 整屏 login-cover-center.png,表单居中(web-config 默认值)
4 LoginTheme4.vue 左深蓝品牌区 + 右白卡片,门户运营端同款(完整版,见下)

主题 4 能力清单(login-themes/LoginTheme4.vue):

  • 账号密码登录 + 记住我(存 LOGIN_ACCOUNT,只存账号不存密码)。
  • 图形验证码:登录失败达 getLoginConfig 阈值后出现,点击图片刷新。
  • 账号锁定倒计时:后端返回 lockUser(lockEndTime/nowTime)后按钮进入 a-statistic-countdown,结束前禁用登录。
  • 「激活账号」入口:由 getSysAccountConfig 的 defaultActivateAccount 控制显隐。
  • 「忘记密码」「扫码登录」:跳基座内置的 /user/forgotPassword、/user/qrCode。
  • 单位编码:/login/:officeCode 进入时写入 $utils.ls 的 officeCode。
  • 登录成功后:写 token / USER-TOKEN;带 redirect_client_id 时按客户端列表跳 sso.html 做客户端授权,否则回 VITE_APP_DEFAULT_PATH。
  • 右侧表单区用 flex 弹性居中(align-items: safe center + justify-content: center)。不用 overflow-y: auto:父级 .login-page 是 overflow: hidden,靠滚动救不了;safe center 让视口装不下时退化成顶部对齐,卡片顶部不会被顶出可视区。

登录辅助页(packages/pages/login/,均为 meta.public,登录前可达):

路由 组件 说明
/user/qrCode qr-code.vue 扫码登录:qrLogin/generate 取 key,a-qrcode 渲染,有效期倒计时,过期遮罩 + 刷新
/user/forgotPassword forgot-password.vue 找回密码四步:选择方式 → 填账号 → 验证码校验(拿临时 token)→ 设新密码;密码策略取 sysPwdConfig
/user/activate activate.vue 账号激活四步:身份核验(+图形验证码)→ 短信/邮箱验证码 → 设密码(强度条)→ 完成信息卡
/user/login — 重定向到 VITE_APP_LOGIN_PATH,供三张页面里的「返回登录」统一跳转

账号类接口统一在 packages/api/account.js(登录前白名单链路,走 VITE_APP_PORTAL_SERVER_NAME):

方法 说明
getSysAccountConfig 激活入口开关(sysAccountConfig/listByActivate)
getPwdConfig 密码策略(sysPwdConfig/getFirstData)
getLoginQrCodeKey 扫码登录 key(qrLogin/generate)
getValidationCodeWithoutToken 找回密码发送验证码
checkValidationCodeWithoutToken 找回密码校验验证码 → 临时 access_token
updatePasswordWithoutToken 用临时 token 重置密码(账号/密码需 Base64,token 走 user-token 头)
checkUseInfo 激活身份核验
getActivateValidationCode 激活发送验证码
checkActivateValidationCode 激活校验验证码
activateUpdatePassword 激活设置新密码

SSO 静态资源已收编进基座:源在 packages/sso/(sso.js / sso.html),随 npm 包分发(files 加 sso,build 拷 dist/sso)。业务项目不再维护 public/ 下的 sso 文件,只需在 vite.config.js 里:

import ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'
ssoPlugin()

dev 由插件中间件提供(注册在内部中间件前,用包内版本遮蔽 public)。sso.html 换token 读的是同源 localStorage(vue-ls 包装),跨 origin 的平台 sso 不能直接用。

redirect_uri 三种处理(sso.js):

  1. 含 {token} → 用本地 token 直接替换回跳,不换 code。
  2. 跳回当前应用自身(client_id = 本应用自己的 client,redirect_uri 同源、且无 {code} 占位符)→ 账密登录场景,本地已有登录态,不调用单点(不校验授权、不换 code),直接回跳。
  3. 第三方跳转(功能模块弹窗跳别的 client / 系统)→ 走完整授权码流程:authorizationCodeValidate 校验 + oauth2/code 换码;有 {code} 就替换,无占位符则自动追加 ?code=xxx。

「当前应用自己的 client」用本应用 base 定位 namespace(loginHref 为锚点)精确读取,不走 key 后缀模糊匹配 —— 同 origin 多应用共用 localStorage 时才不会取到别的应用的 clientId。

2.11 SImportModal 通用批量导入弹窗

三步式导入:上传文件 → 数据预览(可编辑/删除行)→ 导入结果(含异常数据导出)。文件限制:.xls/.xlsx、≤ 500KB。

<s-import-modal
  ref="importModalRef"
  :upload-url="IMPORT_UPLOAD_URL"
  :columns="importColumns"
  :apis="importApis"
  :type-select="importTypeSelect"
  @reload="handChange"
/>

<script setup>
importModalRef.value.show() // 打开(内部会重置状态)

const importApis = { templateDownload, importPreview, importData, exportExceptionData }
const importColumns = [{ title: '设备SN码', dataIndex: 'sn', width: 150 }]
// 可选:导入时附带的业务参数下拉,选中值以 extraKey 随各接口一起提交
const importTypeSelect = computed(() => ({
  options: [{ label: '摄像头', value: '1' }],
  placeholder: '选择设备分类'
}))
</script>
props 类型 默认值 说明
value Boolean false 显隐(v-model:value)
title String '批量导入' 弹窗标题
width String / Number 1000 弹窗宽度
uploadUrl String '' 上传地址(完整网关地址,如 /monitor/DeviceInfo/Uploader)
columns Array [] 预览/结果表格列 [{ title, dataIndex, width }]
apis Object {} 四个导入接口(见下)
typeSelect Object null { options, placeholder, loading },不需要业务参数时不传
extraKey String 'deviceTypeId' typeSelect 选中值提交时的字段名
events 说明
update:value 显隐变化(v-model)
reload 导入成功/关闭后需要刷新列表
methods(ref 调用) 说明
show() 打开弹窗并重置状态

接口约定(均返回 Promise,组件内部兼容 { code, data } 与直接返回数据两种格式):

接口 入参 返回
templateDownload { ...extraParams } { url }(组件用 url 触发下载)
importPreview { fileName, ...extra } { dataRow: [] }
importData { list, ...extra } { resultType, snum, fnum, failResult: [] }
exportExceptionData { list, ...extra } { url }
上传(内部) FormData(file) → uploadUrl { name } / { fileName }(后续接口回传 fileName)

⚠️ SImportModal 是三步式(上传 → 预览编辑 → 结果/异常导出)。 业务项目里如果存在「选文件即导入」的单步式导入组件(如 hy-monitor 的 views/people/components/ImportModal.vue、views/basicData/components/ImportModal.vue), 两者在布局、API、事件、调用页契约上都不同,不能当同一个组件替换,仍按各自实现保留。

2.12 SDataRangeTreeSelect 数据权限范围树

数据权限(组织/校区/单位)范围选择,内部走 findOfficeList / getOfficeByIds / getSysConfigByCode('dataScope')。

<s-data-range-tree-select v-model:value="ids" :auto-sys-config="true" />

常用 props:value(id 数组) / multiple / treeCheckable / allowClear / placeholder / maxTagCount / disabledGroup('1'组织 '2'校区 '3'单位,可传数组)/ showOnlyOrganization / treeSelectData(传数组则不请求接口)/ isDataScopeFilter / autoSysConfig / defaultValue。 events:update:value、change(均输出 id 数组)。

⚠️ 模板写死了 label-in-value + tree-check-strictly,antd 要求内部 value 必须是 { label, value } 对象数组。 因此回显必须先 getOfficeByIds(ids) 转成节点对象再赋值,直接赋裸 id 字符串会触发 Invalid prop value 警告且输入框显示成裸数字 ID。

2.13 SExtendFieldsForm 动态扩展字段表单

后端下发字段配置(fillModeConfig 为 JSON 串,含 showType / config),前端按配置渲染。

<s-extend-fields-form ref="extRef" :data="fields" :default-value="values" type="edit" :cols="2" />
<script setup>
// ref 暴露三个方法
extRef.value.validate() // Promise<boolean>
extRef.value.clearValidate()
extRef.value.getModel() // [{ fieldCode, value }](对象值已 JSON.stringify)
</script>
props 类型 默认值 说明
data Array [] 扩展字段定义(fieldCode/fieldName/fillModeConfig)
type String 'add' add / edit / view(view 不校验)
defaultValue Array [] 编辑态回显值 [ { fieldCode, value } ]
cols Number 2 每行列数(非整行字段按 100/cols% 宽)
labelWidth String auto' label 宽度

自动占满整行的 showType:textarea、upload、select 且 config.multiple。默认值按 showType 转类型:datePicker → dayjs 对象、number → Number、select 多选 → 逗号切数组。

2.14 SChooseUser 选择人员弹窗(带数据权限)

弹窗式人员选择:左侧组织树 + 右侧人员列表(头像/姓名/工号 + 单位),搜索区内置人员类型过滤(全部/教职工/学生/校外人员),支持单选/多选、滚动分页加载、全选/反选、多选时右侧已选清单。确认后自动关闭弹窗。

与 SUserSelect 的差异(选型依据):

对比项 SUserSelect SChooseUser
形态 只读输入框 + 弹窗一体 纯弹窗,显隐由业务控制
数据权限 组织树/列表接口不带数据权限 走 levelOneChildrenWithAuth / levelTwoChildrenWithAuth / findUsersWithAuth,按登录人权限过滤
人员类型 无过滤 内置教职工/学生/校外人员过滤
取值契约 v-model:value 直接绑 id(单选字符串/多选数组) v-model:value 控显隐;v-model:selectedIds/selectedId 绑已选 id;@callback 回抛选中对象列表
<s-choose-user
  v-model:value="userScopeVisible"
  v-model:selectedIds="userScopeIds"
  :multiple="true"
  @callback="userScopeCallback"
/>
<script setup>
// 确认(单选/多选): payload = [{ id, name, cover, userid, company, department }](单选也是单元素数组)
// 取消/关闭: payload = undefined
const userScopeCallback = (payload) => {
  if (payload) userNames.value = payload.map((u) => u.name).join(',')
  userScopeVisible.value = false
}
</script>
props 类型 默认值 说明
value Boolean false 弹窗显隐(v-model:value)
title String '选择人员' 弹窗标题
multiple Boolean false 多选(右侧出现已选清单)
searchPlaceholder String '按姓名、工号/学号、手机号搜索' 搜索框占位
required Boolean false 确认时未选则提示且不关闭
selectedIds Array [] 多选回显 id 数组(v-model:selectedIds),内部 getBUseryIds 拉对象渲染已选
selectedId String '' 单选回显 id(v-model:selectedId),内部 getUserById 拉对象
events 说明
update:value 关闭弹窗(确认/取消均自动置 false,业务无需手动关)
update:selectedIds 已选 id 数组双向绑定
update:selectedId 单选 id
callback 确认回抛选中对象数组;关闭时无参

⚠️ 接口全部内置在基座 packages/api/common.js(findUsersWithAuth = /user/users/authorized 等),业务无需传接口;无后端的预览环境树/列表为空属正常。列表中 userid 展示的是 loginName(工号/学号)。

2.15 SBelowChoosePosition 选择岗位弹窗

弹窗式岗位选择(源自业务项目 /components/BelowChoosePosition,已收编进基座):左侧树用 getBelowUnit 一次性拉「根节点及其以下所有单位」的完整树(范围由 rootId 决定),右侧列表查岗位(findJobs),支持单选/多选。

与基座其它选择器的差异:SOfficeSelect/SUserSelect 查组织/人员且左树递归懒加载;本组件查岗位、左树一次性全量。确认后不自动关闭弹窗,业务需在 callback 中手动关闭(与源项目行为一致)。

<s-below-choose-position
  v-model:value="visible"
  v-model:selectedIds="positionIds"
  multiple
  :root-id="campusId"
  @callback="onCallback"
/>
<script setup>
// 确认(多选): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }
// 确认(单选): payload = { selected: { id, name, ... } }
// 取消/关闭: payload = false
const onCallback = (payload) => {
  if (payload && payload.selectedList) {
    names.value = payload.selectedList.map((i) => i.name).join(',')
  }
  visible.value = false // 确认后组件不自动关闭,必须手动关
}
</script>

props 与 SChooseUser 相同(title 默认 '选择岗位'、searchPlaceholder 默认 '按岗位名称、岗位编号搜索'),另有一个专有 prop:

props 类型 默认值 说明
rootId String '' 左树根节点 id,决定树的数据范围;变化时自动重载左树,未传按 '-1' 查
methods(ref 调用) 说明
initLeftTreeData(id) 手动重载左侧组织树
events 说明
update:value 仅取消时置 false;确认不关窗,业务手动关
update:selectedIds 已选岗位 id 数组双向绑定(回显走 getPositionByIds)
update:selectedId 单选 id(回显走 getPositionById)
callback 确认回抛 { selectedList } / { selected } 对象;关闭回抛 false

⚠️ callback 载荷形态与 SChooseUser 不同(对象 { selectedList } vs 数组),且确认后关窗行为相反,两个组件的 callback 写法不可混用。


2.16 SSkeletonLayout 骨架布局(标题 + 按钮组 + 内容区)

2026-10-28 新增。用于页面级「标题条 + 操作按钮 + 内容区」的骨架外观,与 SListLayout / SFormLayout 同级但更轻:不带表格、不带表单、不带分页,内容区完全由插槽决定。

<s-skeleton-layout
  :title="$l('采集任务')"
  :buttons="[
    { key: 'add', name: '新增', icon: true },
    { key: 'remove', name: '删除', disabled: true },
    { key: 'export', name: '导出', icon: 'DownloadOutlined' }
  ]"
  bg-color="#fff"
  @btnCallback="onBtnClick"
>
  <div class="my-content">...</div>
  <template #otherBtns><a-button>自定义</a-button></template>
  <template #other>底部内容</template>
</s-skeleton-layout>
props 类型 默认 说明
title String — 必填,标题条文本
buttons Array [] 按钮配置数组,见下表
buttons 每项字段:
字段 类型 说明
key String 唯一键,点击时回抛该值;'add' 时按钮自动为 primary
name String 按钮文案(内部走 $l,可直接写源中文)
icon String | Boolean 字符串 = 图标组件名(如 'PlusOutlined');true = 按 key 查内置 iconMap;缺省不出图标
action String v-action 权限码,缺省用 key(会真正做权限过滤,无权限时按钮被移除)
show Boolean 默认 true;false 时 v-show 隐藏(仍占位、仍注册权限)
disabled Boolean 置灰
type String 覆盖 a-button 的 type
slots 说明
默认 内容区(.skeleton-layout-main)
otherBtns 按钮组右侧追加内容
other 底部区域
events 说明
btnCallback 回抛被点击按钮的 key
methods(ref 调用) 说明
— 无。高度由 flex 自动分配,不需要业务调任何方法(见下)

内置 iconMap 的 key:add / edit / delete / remove / import / export / assign / execute / pause / resume / approve / setting / TopOfType / TOP / synchronize。

高度实现(2026-10-28 修订):根节点 height:100%; display:flex; flex-direction:column,标题条 flex:0 0 60px,内容区 flex:1 1 auto; min-height:0; overflow:hidden auto,底部槽 flex:0 0 auto。零 JS、零 resize 监听,窗口缩放 / 侧栏折叠自动跟随。

前提:父容器要有确定高度。基座 BasicLayout 的 router-view 已带 :style="{ height: contentHeight + 'px' }",会透传到页面根组件,通常无需额外处理;若页面外层是自己写的 height:auto 容器,需给该容器一个确定高度。

旧版本的 initLayoutHeight() 方法已移除,layoutHeight 也不再暴露(原实现是 parentNode.offsetHeight - 76 且只在 mounted 算一次)。

2.17 错误页(301 / 403 / 404 / 500)

基座内置三张错误页,同一张页面承接「页面本身出错」和「接口报错」两种来源,靠 URL 上的 ?api= 区分文案。

路径 组件 状态码来源 主色
/403 pages/403.vue 接口 403 无权限、接口 301 地址变更、页面无权限 橙色 #fa8c16
/404 pages/404.vue 路由没命中(通配 /:pathMatch(.*)*)、接口 404 主题色 var(--s-color)
/500 pages/500.vue 仅可直接访问;接口 5xx 不跳转,仍走通知 红色 #f5222d

渲染位置:buildErrorRoute() 把三页统一包在 BasicLayout 下,作为 children: [{ path: '' }] 的嵌套子路由——跳转时只替换内容区 router-view,侧边菜单、顶栏、页脚保持原样。页面 404(通配)与接口 404 共用同一套结构,表现完全一致。

免登录:/403、/404、/500 带 meta.public(接口报错时 token 可能已失效,不能让它再卡在登录守卫里);通配 /:pathMatch(.*)* 不带 public,未登录访问不存在的地址仍回登录页。

接口报错的映射(packages/utils/request.js):

HTTP 状态 行为 目标 URL
301 跳 403 页,文案「接口地址已变更」 /403?api=<接口>&status=301&from=<出错页>
403 跳 403 页,文案「接口无权限」 /403?api=<接口>&status=403&from=<出错页>
404 跳 404 页,文案「接口不存在」 /404?api=<接口>&status=404&from=<出错页>
其它(含 5xx) 不跳,照旧弹通知 —

URL 参数:

参数 含义
api 报错接口地址。有它即切「接口口径」文案;页面自身出错时不带
status 原始状态码;301 单独走「接口地址已变更」这一档文案
from 出错来源页面地址(已剥掉 VITE_APP_BASE_URL),页面显示为「出错地址」

文案口径:

来源 403 页 404 页
页面(无 api) 页面权限不足 页面走丢了
接口(有 api) 接口无权限 接口不存在
接口 301 接口地址已变更 —

两个按钮:「返回首页」走 VITE_APP_DEFAULT_PATH(默认 /workplace/index);「返回上一页」用 router.back(),没有历史记录时自动退回首页,避免点了没反应。

跳过跳转(后台轮询、辅助接口等非主流程请求,避免一条辅助接口失败把整页顶掉):

// 第三个参数支持 { skipErrorPage: true }(也可写在请求 meta 里)
window.$utils.http.post(url, data, { skipErrorPage: true })

并发与兜底:错误页跳转是串行排队、后到优先,同时来 403 和 404 不会互相取消;导航结束后回读 currentRoute 校验是否真的到达(兼容目标被 redirect 改写路径),没到达重试 2 次,仍失败才 location.replace 整页兜底,保证用户一定看到错误页。已经在错误页且已带 api 时不再覆盖,防止错误页自身挂的辅助接口把真实原因顶掉。

改颜色 / 改文案:

  • 文案全部走 i18n 词条(packages/pages/i18n.js,命名空间 pages),改词条即改三页文字。
  • 403 / 500 各自在根节点定义了 --e-color(主色)、--e-light-color(浅色)、--e-border-color(虚线边框),业务侧用同名变量覆盖即可换色;404 用主题色 --s-color,跟随 VITE_APP_THEME_VALUE。
  • 三页根节点都是 height:100%; overflow:hidden,装饰光斑包在 __deco 里自裁,超出部分只在卡片内部滚动,不会撑出页面滚动条。

错误页挂在 BasicLayout 下,布局层会带发 getSystemIcon 与消息计数两个请求。这两个接口若是本身会失败的辅助接口,建议加 skipErrorPage: true,否则可能从 403 再跳到 404。

2.18 菜单配色(侧边 / 顶部)

菜单色板由主题色推导(light)或固定 antd 黑(dark),启动时 packages/utils/menu-theme.js 输出实色 #rrggbb(不含 rgba / 透明度),落到 :root 的 --s-menu-*,同时挂到 window.$menuTheme(含 antd Menu token 与 isLightBg)。改 VITE_APP_THEME_VALUE 换主题色,整套菜单跟着变,不再是写死的淡蓝。

部位 CSS 变量 light(orange 默认) light(blue) light(green) dark
一级菜单底 --s-menu-bg #f9f1e1 #e1ebf9 #e1f9ef #001529
子菜单展开区 --s-menu-sub-bg #fcf9f2 #f2f7fc #f2fcf8 #000c17
悬停项 --s-menu-hover-bg #f4e4c8 #c8daf4 #c8f4e1 #1a2c3e
选中块 --s-menu-active-bg #fff1d6 #dae9ff #d6f4e7 #FFA500(主题主色)
普通文字 --s-menu-text #514734 #344051 #345145 #d7dde6
悬停文字 --s-menu-text-hover #825d17 #1f5aad #14714a #ffffff
选中文字 --s-menu-text-active、--s-menu-active-text #8b6318 #1a4d93 #157950 #ffffff
分组标题文字 $menuTheme.groupTitle #8a7a5c #5c6f8a #5c8a77 #737e89
isLightBg — true true true false

三列 light 是同一套规则在不同主题色下的输出(VITE_APP_MENU_BG: 'theme'):色相取主题色、饱和度受 _BG_SATURATION 限制、亮度由 _BG_LIGHTNESS 定,文字色按对比度求解(≥ 4.6)。dark 的底色固定 antd 黑,不读 VITE_APP_MENU_BG,只有选中块跟主题色。

跟随系统深浅色

VITE_APP_THEME_FOLLOW_SYSTEM(默认 true)由 packages/utils/color-scheme.js 处理:监听 prefers-color-scheme,系统切深色时立即把菜单按 dark 重算、中性色令牌换成暗色版、body 加 scheme-dark,切回浅色全量还原 —— 运行时生效,不用刷新。

令牌 浅色 深色
--s-text-color #262626 #e8e8e8
--s-text-color-secondary #8c8c8c #a6a6a6
--s-bg-color-container #ffffff #1f1f1f
--s-border-color-base #d9d9d9 #3d3d3d
--s-color-warning-bg #fffbe6 #2b2413(语义浅底压暗)

⚠️ 暗色令牌只对用 var(--s-*) 取色的地方生效。业务页面里硬编码的 background: #fff 不会自动变暗,要适配深色得换成 var(--s-bg-color-container);也可以直接用 body.scheme-dark 写自己的覆盖。 关掉跟随(VITE_APP_THEME_FOLLOW_SYSTEM: false)后深浅固定按 VITE_APP_MENU_THEME 走,业务本来配 dark 的不受影响。

业务只能选模式,不能改颜色

配置 默认 业务可否覆盖 说明
VITE_APP_MENU_THEME light ✅ light 跟主题色的浅色系 / dark 黑色
VITE_APP_MENU_BAR left ✅ left 侧边 / top 顶部(布局项)
VITE_APP_THEME_FOLLOW_SYSTEM true ✅ 是否跟随系统深浅色(prefers-color-scheme)
VITE_APP_MENU_BG / _SUB_BG / _HOVER_BG / _ACTIVE_BG / _TEXT / _TEXT_HOVER / _TEXT_ACTIVE / _GROUP_TITLE / _BG_LIGHTNESS / _BG_SATURATION / _BG_ACTIVE_MIX 见 4.2 ❌ 11 个颜色 / 调色键,一律被基座回填

锁定机制:packages/config/web-config.js 导出 menuColorKeys(上表 ❌ 的 11 个键),packages/index.js 在 registerGlobalConfig 里于 loadRemoteConfig() 合并之后按清单把 env 中这些键强制回填成基座默认值。因此业务 .env、src/config/web-config.js、部署目录 config.json 三处写的菜单颜色全部无效,所有业务项目的菜单与基座 demo 完全一致。

想临时验证「业务传色确实无效」:在业务 config.json 里写 "VITE_APP_MENU_BG": "#ff0000",刷新后菜单仍是按主题色推导的那套值。

要改整套色板(基座维护,不是单个业务能自己改的事):

  1. 色值:改 packages/config/web-config.js 的 VITE_APP_MENU_* 默认值;
  2. 推导规则:light 分支在 packages/utils/menu-theme.js(dark 分支固定黑色体系,不读 VITE_APP_MENU_BG);
  3. CSS 兜底:同步改 packages/style/theme.less 的 --s-menu-*;
  4. 重新打包基座 → 业务更新 sapit-ui-plus(见 4.1)。

注意事项

  1. light 下把 VITE_APP_MENU_BG 配成 dark 会被忽略并告警(黑底属于 dark 模式),仍按浅色推导。
  2. 单项颜色覆盖只对 light 生效,dark 保持纯黑体系,不会出现「黑底 + 淡蓝子菜单」。
  3. 业务样式不要写死 #001529、rgba(255,255,255,.1) 这类菜单色,直接 var(--s-menu-*)。
  4. 侧边菜单、顶部菜单(VITE_APP_MENU_BAR: 'top')、logo 明暗、顶栏文字色共用 window.$menuTheme.isLightBg 判断,不看 VITE_APP_MENU_THEME —— 系统深色跟随会改写它,所以判断必须走这个字段。
  5. window.$menuTheme 是 reactive 对象:深浅色切换时只改属性不换引用,SSideMenu 的 computed 读 window.$menuTheme.token 会自动重算,antd Menu token 无需手动刷新。

2.19 SListCardLayout 卡片列表布局

与 SListLayout 同一套骨架(标题条 + 查询区 + 分页),中间换成卡片网格。卡片正方形、圆角 8px,头部 / 内容 / 底部三段全部由插槽控制。

<s-list-card-layout title="卡片列表" :column="5" :load-data="loadData" @card-action="onCardAction">
  <!-- 头部:不传则取数据项 title,title 也为空则不渲染 header -->
  <template #cardHeader="{ item }">{{ item.title }}</template>

  <!-- 内容区:完全自定义,作用域含 item / index -->
  <template #default="{ item, index }">
    <div>名称:{{ item.name }}</div>
  </template>

  <!-- 底部:不传则为默认按钮区(编辑 / 删除),传了则完全替换 -->
  <template #cardFooter="{ item }">
    <a-button type="link" size="small" @click="edit(item)">编辑</a-button>
  </template>
</s-list-card-layout>
参数 类型 默认 说明
title String 必填 标题条文字
column Number / String 5 每行卡片数,内部 repeat(column, 1fr)
loadData Function 必填 ({ pageNo, pageSize }) => { list, total }
rowKey String / Function 'id' 卡片 key;字段 / 函数取不到时退回下标
buttons Array 添加 / 批量删除 / 导入 / 导出 与 SListLayout 同构(name/key/show/type/icon/api)
showPagination Boolean true 是否显示分页
pSize Number / String 20 默认每页条数
pageSizeOptions Array ['10', '20', '40', '80'] 每页条数可选项
插槽 作用域 说明
default { item, index } 卡片内容区,完全自定义
cardHeader { item, index } 卡片头部;不传用 item.title,两者都空则不渲染 header
cardFooter { item, index } 卡片底部;不传为默认「编辑 / 删除」,点击抛 cardAction
filter / filterMore / desc / tabs / tree / empty / other / otherBtns 同 SListLayout 与普通列表布局一致

事件:cardAction(key, item, index)(key 为 edit / delete)、btnCallback(key, selections)、reset。ref 上可调 reload(forceFirst) / fetchList()。

样式约定(都写在组件内 scoped,类名统一 s-card-* 前缀,避免误伤业务里的通用 card-*):

类名 说明
s-card-grid display:grid + gap:12px,列数由 column 决定
s-card-item aspect-ratio: 1/1 正方形 + border-radius: 8px
s-card-header 头部,单行超出省略
s-card-body 内容区,撑满剩余高度,超出内容在卡片内部裁切
s-card-footer 底部按钮区,min-height:36px,左右两端对齐
s-card-empty 空态,grid-column: 1 / -1 跨满整行
s-card-pagination 分页条,高度从卡片区里扣掉,避免双滚动条

取数归一化:list(或 data)取行、total / pagination.total / totalCount 取总数、pageNo / pageNum / pagination.current 回写当前页;接口异常只 console.warn 并清空,不会一直转圈。切每页条数时统一在 change 里判断,避免同一动作发两次请求。

2.20 SSuperListLayout 高级列表(列设置 + 高级筛选)

在 SListLayout 基础上多两个抽屉:右上角「高级表格」改列、「高级搜索」加条件。两者都是草稿 + 确定生效:抽屉里改的是副本,点「确定」才回写并刷新表格,点「关闭」直接丢弃,不会出现「点一下表格就跳」。

<s-super-list-layout title="高级列表" :columns="columns" :load-data="loadData" />
参数 类型 默认 说明
title String 必填 标题条文字
columns Array [] 列配置,见下方
loadData Function 必填 取数,入参含高级筛选结果
rowKey String / Function 'id' 行 key
buttons Array 添加 / 批量删除 / 导入 / 导出 与 SListLayout 同构
isSelection Boolean false 是否显示勾选列
showPagination Boolean true 是否显示分页
pSize Number / String 20 默认每页条数

列配置在 SListLayout 基础上多两项:

字段 说明
filterConfig 配了才会出现在「高级搜索」的可选字段里;不配则该列只能看不能筛
width px / 纯数字 → 直接生效,并带进「高级表格」的列宽输入框;% → 仅作表头宽度,高级表格里的像素框留空

filterConfig 可用键:filterType / filterApi / filterData / props / precision / step / minValue / maxValue / length / startDate / endDate。 filterType:[INPUT 输入框、INT 整数、FLOAT 浮点、DATE 日期、DATETIME 时间、SINGLE_SELECT 单选、MULTIPLE_SELECT 多选、GANDER 性别、IS 是否、USER 用户、OFFICE 组织机构]。下拉类的选项优先取 filterData,没配才用 filterApi 拉一次并回填。

列设置(SettingColumns)

  • 显示 / 隐藏:勾选即改草稿,确定后 show === false 的列不进表格(仍可被高级搜索使用);
  • 冻结 / 取消冻结:记住每列最初的冻结方向,取消后再冻结还原原来的 left / right;操作列(action)永远 right 且禁用;
  • 列宽:表头 width 是 px 或纯数字 → 四舍五入带进输入框;20% 这类百分比不带入;用户主动清空则恢复「自适应」;
  • 「确定」→ 回写列配置并关抽屉;「重置」→ 恢复调用方传入的 columns;「关闭」→ 丢弃草稿。

高级筛选(SettingFilter)

  • 可选字段 = 配了 filterConfig 的列(列被隐藏也能筛);
  • 运算符按类型收窄:文本(INPUT 或未配类型)可 includes / excludes / equal / notequal / null / notnull;选择、数字、日期只留 equal / notequal / null / notnull;
  • 换字段时运算符按新类型重置(文本默认「包含」,其余默认「等于」);
  • null / notnull 不需要填值;其余没填值的条件行在提交时丢弃,不会把空条件发给后端。

提交后的取数入参:

loadData({
  pageNo,
  pageSize,
  filterMode, // 1
  filterConditions: [{ dataIndex, equals, value }],
  [dataIndex]: value // equal / includes 这类单值条件额外铺平一份
})

equal / includes 的单值条件会同时铺平成同名字段(params[dataIndex] = value),后端按字段名直接取用即可,不用解析 filterConditions。

2.21 STab 标签栏(超出宽度自动出左右箭头)

一行横向标签,放得下就不出箭头,放不下时左右各出一个 32×32 箭头:点箭头等于「选中上一个/下一个标签 + 把它滚进可视区」。

两种用法,任选其一:

<!-- 用法一:传数组,组件自己渲染 -->
<s-tab v-model:activeKey="active" :tabs="tabs" @change="onChange" />

<script setup>
const tabs = [
  { label: '任务配置', value: '1' },
  { label: '执行日志', value: '2' }
]
const active = ref('1')
const onChange = (key, item) => {
  /* item 仅数组模式提供 */
}
</script>

<!-- 用法二:自己写 s-tab-item(需要自定义标签内容时用) -->
<s-tab v-model:activeKey="active">
  <s-tab-item value="1">任务配置</s-tab-item>
  <s-tab-item value="2">
    <span>执行日志</span>
    <a-badge :count="3" />
  </s-tab-item>
</s-tab>

默认选中:不传 activeKey 也能用 —— 传 default-active-key 就选中它,两者都没传则自动选中第一项(组件挂载后补默认值,并通过 update:activeKey 同步给父级,@change 不算用户操作、不会触发)。

<s-tab :tabs="tabs" default-active-key="2" />
项 说明
v-model:activeKey 当前选中值,String/Number;不传 / 传空('')都会自动选中(见下一行)
defaultActiveKey 默认选中值:activeKey 没传或传空时生效;它也没传就默认选中第一项
tabs [{ label, value }];字段名不同用 tabKey(默认 { label: 'label', value: 'value' })
tabKey 字段映射,与 SFormLayout/SSkeletonLayout 的 tabs 约定一致
stepRatio 已到首个/末个标签但仍可滚动时,一次滚多少屏,默认 0.6
@change (key, item);插槽模式下 item 为 undefined
插槽 默认插槽放 s-tab-item;一旦使用默认插槽,tabs 不再参与渲染
expose syncArrow() / scrollToActive() / scrollRef

交互规则

场景 行为
内容放得下 不渲染箭头,标签铺满整行
内容超出 左右箭头出现
点右箭头 选中下一个标签并滚进可视区;已是最后一个则退化为「纯滚动一屏」
箭头禁用 既没有上一个/下一个标签,也无法再滚动时禁用
滚轮 纵向滚轮转横向滚动,不会带动整页
鼠标拖动 按住左键左右拖动即可平移标签栏(仅溢出时生效);位移超过 5px 才算拖动,不会误触发标签切换;悬停不显示抓手光标,按下才变抓手
触摸 不接管,保持系统原生横向滚动与惯性
键盘 标签聚焦后左右方向键切换

⚠️ 只给标签栏,不给内容区。内容请自己按 activeKey 渲染(切显隐用 v-show,不要用 v-if,否则隐藏页签里的组件实例会丢)。 典型例子:权限配置里按客户端分的多个表格,保存时要同时读到所有页签的勾选,必须全部渲染、只切显示。

配色跟随主题(组件内没有写死颜色,换 VITE_APP_THEME_VALUE 自动跟着变)

元素 取色 对应变量
选中 / 悬停标签 主题主色 --s-color
未选中标签、箭头 主题主色 30% 混入中性灰 → 带主题倾向的灰(对比度 ≥ 4.5:1) color-mix(… var(--s-tab-color) 30%, #595959)
箭头到头(禁用) 主题描边色 --s-border-color

想单独调整标签栏配色,在外层覆盖这几个变量即可,不用改组件、也不用动主题:

.my-page {
  --s-tab-color: #333; // 未选中 / 箭头(参与颜色调和)
  --s-tab-active-color: #fa541c; // 选中 / 悬停
  --s-tab-disabled-color: #ddd; // 箭头到头
}

老浏览器(不认识 color-mix)自动退化为中性灰 #595959,不会出现「文字继承不到颜色」的问题。

2.22 SFilterTableToolbar(查询区 + 表格区组合件)

SFilterToolbar + STableToolbar 的现成组合:上半查询区、下半表格区,表格吃掉剩余高度并在内部滚动。

<s-filter-table-toolbar :columns="columns" :data="page" row-key="id" @reset="onReset">
  <template #filter>
    <s-filter-item label="名称">
      <a-input v-model:value="query.name" @pressEnter="reload" />
    </s-filter-item>
  </template>

  <!-- 列插槽按 dataIndex 命名,与 s-table 一致 -->
  <template #action="{ record }">
    <a @click="edit(record)">修改</a>
  </template>
</s-filter-table-toolbar>
项 说明
查询区插槽 filter、filterMore(透传给 SFilterToolbar)
表格插槽 其余插槽全部透传给 STableToolbar(列名插槽、bodyCell、expandedRowRender…)
其余属性 columns / data / rowKey / pageSize / size / scrollX / tableHeight,其余通过 $attrs 透传给 s-table(如 showPagination)
@reset 只抛事件,查询参数在业务侧,清空后自己调 refresh()
expose refresh(deleteFlag) / reload() / resize() / tableRef

高度前提:组件根节点是 height:100% 的 flex 列,需要外层给到确定高度才会撑满 ——

  • 放进 SFormLayout 的 #form 插槽 ✅(form-container-wrap 已是 flex:1)
  • 放进 SSkeletonLayout 默认插槽 ✅(.skeleton-container 已是 flex:1)
  • 直接丢进普通 div ❌,高度会退化成内容高度(这是 CSS 的规矩,不是组件 bug)

三、布局与高度规范

本章是基座内部布局组件的强制约定。业务页面只管用 layout,不要自己写高度;如果要新增布局组件,必须先满足本章规则。

3.1 高度:优先 CSS flex 撑满;需要动态计算时按三条约束做

2026-10-28 修订:旧标题「禁止 JS 减法算高度」已作废。业务内容区需要出滚动条时,高度就该动态计算,只是必须按下面的约束写,不能每页抄魔数。

错误做法(早期 SListLayout / SFormLayout 都犯过):

// ❌ 用 offsetHeight 减法算子区域高度
this.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16

为什么必错:offsetHeight 读的是当前渲染结果,而这个结果又取决于你即将写入的 height —— 循环依赖。表现是:

  • 数据不满页时分页浮在中间,底部空 15~588px;
  • 表格/表单区溢出容器 1~N px,页面多出一条滚动条;
  • 改一个固定魔数(如 tpH = 103)其它页面全歪。

首选做法(零 JS):父容器 height:100% + display:flex; flex-direction:column,主体区 flex:1 1 auto; min-height:0; overflow:auto,底部条 flex:0 0 auto。列表页、表单页绝大多数场景用这个就够。

2026-11-06 现状:SSkeletonLayout、SListLayout、SListTableTreeLayout、SSuperListLayout、SNewestDataListLayout、SListCardLayout、SListBasicLayout、SFormLayout、SFormBasicLayout、SPanelLayout、SFilterTableToolbar 已全部改为纯 CSS flex,零 JS 测量高度。业务页面不需要再写任何高度代码。

布局组件根节点的标准写法(新增布局组件请照抄):

.xxx-layout {
  height: 100%; /* 吃满父容器,父级必须有确定高度 */
  min-height: 0; /* ✅ 必须:允许被压缩 */
  display: flex;
  flex-direction: column;
  overflow: hidden;
}

两个必须记住的点:

点 说明
✅ 必须写 min-height: 0 flex item 默认 min-height: auto = 内容最小高度。不写它,内容一多就会被顶开、把父级(PageView 的 .page-view-common)撑破,表现为外层 router-view 多出一条滚动条。
❌ 不要写 max-height: 100% 父级高度不是显式值时,这个百分比会把根节点压成 0/极小,整条 flex 链瞬间塌掉(表格只剩表头、左侧树错位)。防塌陷靠父级显式高度,不靠 max-height。

中间层必须一起贯通,漏一层就断链:

  • a-spin 夹在中间时:.ant-spin-nested-loading、.ant-spin-container 都要 flex:1 1 auto; min-height:0; display:flex; flex-direction:column
  • 滚动包裹层(如 .form-layout-main-scroll)也要设成 flex 列,否则里面的 flex:1 拿不到高度
  • 分隔条、滚动条这类固定尺寸元素写 flex: 0 0 <尺寸>,不要只写 width —— 否则空间一紧就被压成 0(左边树拖不动的元凶)

现在唯一还需要 JS 的地方:表格的 scroll.y。它只用于启用 antd 固定表头,值取 .ant-table-body 的真实 clientHeight,不参与布局(CSS 已用 max-height: none !important 覆盖 antd 写入的内联 max-height)。

需要 JS 动态计算的情形(内容区要出滚动条、容器高度随窗口或兄弟节点变化):允许并推荐动态计算,但必须满足三条:

  1. 收敛到一处:同一种布局只留一个 calcXxxHeight(),不要每页一份魔数
  2. 跟着容器走:用 ResizeObserver 观察父容器重算,别只监听 window.resize
  3. 不读 $parent.$el:父级 DOM 结构一变就错,用 ref 取自己的容器

仍然禁止的错法:拿「自己即将写入 height 的那个祖先」的 offsetHeight 做减法 —— 循环依赖。要读就读不依赖自身高度的量(window.innerHeight、上级固定头/脚节点的高度)。

3.2 表格区撑满链路(列表页分页贴底的关键)

STable 的 body 要靠 flex 拿到剩余高度,链路上任何一层漏掉都会导致撑不开:

.table-content {
  flex: 1;
  display: flex;
  flex-direction: column;
  min-height: 0;
}
.tabs-wrap {
  flex: 0 0 auto;
}
.table-container {
  flex: 1 1 auto;
  min-height: 0;
  display: flex;
  flex-direction: column;
}
.table-wrapper {
  flex: 1 1 auto;
  ...;
} /* STable 组件根节点,漏它整条链断 */
.ant-table-wrapper {
  flex: 1 1 auto;
  ...;
}
.ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container {
  margin-left: 10px;
} /* 表格缩进走 margin,不走 padding */
.ant-table-header {
  flex: 0 0 auto;
}
.ant-table-body {
  flex: 1 1 auto;
  min-height: 0;
  max-height: none !important;
}
.ant-table-pagination {
  margin-bottom: 0;
  flex: 0 0 auto;
} /* 差一个 margin 就是 15~16px 空隙 */

要点:

  1. .table-wrapper 不能漏 —— 它是 STable 组件根节点,实测漏掉它 body 就撑不开;
  2. scroll.y 写入的 max-height 必须 none !important 覆盖掉,否则和 flex 打架;
  3. 分页 margin-bottom: 0,否则分页与容器底边恒差一个 margin;
  4. 表格缩进用 :deep(.ant-table-container){margin-left:10px},不要用 padding-left(会挤压 body 宽度计算)。

3.3 .tools 头部条统一 60px

所有布局的 .tools(标题 + 按钮条)统一:

.tools {
  height: 60px;
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0 16px;
  box-sizing: border-box;
  border-bottom: 1px solid #f0f2f5;
}
.list-filter-wrap {
  padding: 10px 16px;
  box-sizing: border-box;
}

⚠️ 若某天调整了 .tools 高度,所有布局里 initTable() 的减数(如 - 76)必须同步改,否则全站列表页一起歪。

3.4 表单布局 SFormLayout

.form-layout 用同一套 flex 撑满,initStyle() 里只算 footer 宽度(collapses + anchor 场景要避开右侧锚点),不再算高度:

.form-layout {
  height: 100%;
  overflow: hidden;
  :deep(.ant-spin-nested-loading),
  :deep(.ant-spin-container) {
    /* a-spin 包裹层必须逐层撑满,否则 form-layout 高度取不到 */
    height: 100%;
    display: flex;
    flex-direction: column;
    min-height: 0;
  }
}
.tools,
.step-wrap,
.tabs-wrap,
.modal,
.form-fixed-footer {
  flex: 0 0 auto;
}
.form-layout-main {
  flex: 1 1 auto;
  min-height: 0;
  overflow: hidden auto;
}
.form-fixed-footer {
  height: 60px;
}

多列与独占整行(full)

SForm 的 a-form 与 SCollapsesItem 的内容区都是 display:grid; grid-template-columns: repeat(column, 1fr)。多列时想让某一项独占整行,给子项加 full 即可(内部落成 grid-column: 1 / -1):

<!-- 表单 3 列,备注独占一行 -->
<s-form :column="3" :model="form">
  <s-form-item label="名称" name="name"><a-input /></s-form-item>
  <s-form-item label="编码" name="code"><a-input /></s-form-item>
  <s-form-item label="备注" name="remark" full><a-textarea /></s-form-item>
</s-form>

<!-- 折叠分组 2 列 -->
<s-collapses>
  <s-collapses-item title="基础信息" :column="2">
    <s-form-item label="姓名" name="a"><a-input /></s-form-item>
    <s-form-item label="年龄" name="b"><a-input /></s-form-item>
    <s-form-item label="详细地址" name="c" full><a-input /></s-form-item>
  </s-collapses-item>
</s-collapses>

筛选区独占整行(SFilterItem 的 full)

SFilterWrap 是 display:flex; flex-wrap:wrap; gap:10px 容器,子项宽度默认由 width(px,默认 280)决定。加 full 后该项宽度拉满 100%(flex: 1 1 100%),自然独占一行,后面的项自动换到下一行:

<s-filter-wrap>
  <s-filter-item label="名称"><a-input /></s-filter-item>
  <s-filter-item label="状态"><a-select /></s-filter-item>
  <!-- 备注太长,让它单独占一行 -->
  <s-filter-item label="备注" full><a-textarea /></s-filter-item>
</s-filter-wrap>
  • full 优先于 width:同时传时忽略 width。
  • label 仍按 labelWidth(默认 70)渲染,剩余宽度全部给内容区,a-select 会自动撑满。
  • 只有 SFilterItem 有这个属性;SFilterWrap 本身不需要配列数。
参数 类型 默认 归属
full Boolean false SFormItem、SCollapsesItem、SFilterItem
  • 单列时 1 / -1 等价于一整行,没有副作用,所以同一个表单项在 1 列 / N 列之间切换不用改代码。
  • column 是 SCollapsesItem 的 prop,不是 SCollapses 的;写在 <s-collapses column="2"> 上不生效。
  • SFormItem 的 full 已声明为 prop,不会透传到内部 a-form-item 上触发 antd 警告;SFilterItem 同理,不会落到内层节点。
  • 实现方式不同:SFormItem / SCollapsesItem 落在 grid-column: 1 / -1,SFilterItem 落在 flex-basis: 100%,用法一致。

查询区外壳(SFilterToolbar)

只想要查询区(不带表格、不带布局外壳)时用 SFilterToolbar:主查询区常显 + 「更多 / 收起」折叠 + 条件重置。功能与 SListLayout / SListBasicLayout 的 filter / filterMore 插槽一致,但内部已包 SFilterWrap,业务只写 SFilterItem。

<s-filter-toolbar @reset="reset" @toggle="onFilterToggle">
  <template #filter>
    <s-filter-item label="关键字" :width="320"><a-input v-model:value="query.keyword" /></s-filter-item>
    <s-filter-item label="状态" :width="220"><a-select v-model:value="query.status" /></s-filter-item>
  </template>
  <!-- 可选:没有这个插槽时「更多 / 收起」按钮不渲染 -->
  <template #filterMore>
    <s-filter-item label="维度" full><check-box v-model:value="query.scopeIds" /></s-filter-item>
  </template>
</s-filter-toolbar>
插槽 说明
filter 主查询区,常显
filterMore 折叠区,v-show 控制;不传则按钮不渲染
事件 参数 说明
reset — 点「条件重置」,父级清空查询参数后自行 reload
toggle isMoreFilter 折叠状态变化;表格区用 STableToolbar 时无需处理(它自己观察容器尺寸),自建表格才需要重算
  • 「更多 / 收起」按钮紧跟查询内容右侧(居左),重置按钮推到最右,与 SListLayout 的 .filter-more-btn / .reset-wrap 完全同款。
  • 查询区高度随折叠变化。表格区优先用 STableToolbar,它内部 ResizeObserver 观察自身容器,折叠后自动重算表体高度,父级零配置。
  • defineExpose:isMoreFilter、toggleFilter()、filterReset()、collapse()(切 tab 时主动收起)。

表格区外壳(STableToolbar)

SFilterToolbar 的固定搭档:封装 STable + 分页 + 表体高度自适应,替业务承担「内容区 − 查询区 − 表头 − 分页」这套算法,保证不出页面级滚动条。

<!-- 父级只负责纵向排布,不需要给表格区写 flex / height -->
<div class="page">
  <s-filter-toolbar @reset="reset">
    <template #filter>...</template>
    <template #filterMore>...</template>
  </s-filter-toolbar>

  <s-table-toolbar ref="tableToolbar" row-key="id" :columns="columns" :data="page" :page-size="10">
    <!-- 单元格插槽与 SListLayout 一致:列 dataIndex 就是插槽名 -->
    <template #ruleName="{ record }">
      <a @click="detail(record)">{{ record.ruleName }}</a>
    </template>
    <template #action="{ record }">
      <a @click="edit(record)" v-action="'edit'">修改</a>
    </template>
  </s-table-toolbar>
</div>
.page {
  height: 100%;
  min-height: 0;
  display: flex;
  flex-direction: column;
}
prop 默认值 说明
columns / data — 同 STable,data 必填
rowKey 'id' 同 STable
pageSize 10 同 STable
size 'middle' 同 STable
scrollX '100%' 横向滚动;表体 y 由组件自己算,父级传 scroll 会被忽略
tableHeight 300 scroll.y 的初值;真实高度由布局 flex 决定,父级一般不用传
  • 属性除上表外原样透传给 STable。
  • 单元格插槽与 SListLayout 完全一致:列 dataIndex 就是插槽名,参数 { text, record, index, column },没有同名插槽的列按原值渲染。#headerCell / #expandedRowRender / #emptyText 这类非列插槽仍原样透传。
  • 不要再写 #bodyCell:组件内部已经占用了它做列分发,业务再写会被忽略,该列整列空白(操作列"消失"就是踩的这个坑)。
  • 高度:纯 flex 撑满,不做算术。根节点 → .table-wrapper → .ant-table-wrapper → .ant-spin-container → .ant-table → .ant-table-container 逐层 flex:1 1 auto;min-height:0,表头/分页 flex:0 0 auto,表体 flex:1 1 auto;max-height:none!important。容器 overflow: hidden,所以永远不会顶出页面级滚动条。
  • 布局可视内容区变化(filterMore 展开、tab 切换、窗口缩放、侧栏收起)由布局自动跟随,父级不用写 onFilterToggle。
  • defineExpose:resize()(手动重算)、refresh(deleteFlag)(转发 STable.refresh 并在刷新后补算分页高度)、reload()、tableRef、scrollY。
  • 父级根节点必须给「有高度 + flex 纵向」的排布(height:100%; display:flex; flex-direction:column),组件靠 flex: 1 1 0% 接手剩余空间。

3.5 左侧树容器高度统一(.s-side-tree)

SListLayout / SListTableTreeLayout / SListCardLayout 的 .side 都是 padding: 10px(四边),树容器高度必须等于「.side 盒高 − 上下 padding(20px)」,否则双滚动条或树被截断。

规则写在全局 packages/style/tree.less 的 .s-side-tree(.side 的唯一化追加类,避免通用名被业务覆盖),业务页面 scoped 里禁止再写副本。覆盖两种树来源:

  • ① 标准 <s-tree>:根节点即 .s-tree-common,height:100%;
  • ② 原生 <a-spin><a-tree>:逐层撑高 .ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder,由 .ant-tree-list-holder 承担 overflow-y:auto。

⚠️ ② 的分支必须用 > 从 .s-side-tree 直接起算,不能写成后代选择器 —— STree 内部同样是 .ant-tree,后代写法会误伤 ①。

3.6 STree 自适应与横向省略

STree 的 height prop 默认值必须是 undefined(不能写死 300):

height: { type: Number, default: undefined }

原因:antd 的 Tree 会把 height 转成虚拟列表 holder 的行内 max-height:300px,导致树被截断且自身产生内层滚动条。

横向文字不换行、超出省略、宽度随父容器拉伸 —— 这套结构规则已统一写在全局 packages/style/tree.less(.s-tree-common / .ant-tree* / .node-title),组件和业务页面都不要再用 scoped 副本:

/* packages/style/tree.less(节选,实际见文件) */
.s-tree-common {
  height: 100%;
  width: 100%;
  overflow-x: hidden;
  overflow-y: auto;
}
.ant-tree,
.ant-tree-list,
.ant-tree-list-holder,
.ant-tree-list-holder-inner {
  width: 100%;
  min-width: 0;
}
.ant-tree-node-content-wrapper {
  min-width: 0;
  overflow: hidden;
}
.ant-tree-title,
.ant-tree-title > .node-title {
  display: block;
  width: 100%;
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}

.node-title 是通用类名,全局规则统一写成 .ant-tree-title > .node-title(限树标题层内),避免污染业务同名类。

3.7 树样式统一文件与主题变量(packages/style/tree.less)

所有树的样式只在这一个文件里,common.less 末尾 @import './tree.less' 引入。原先散落在 STree.vue(scoped)、SBelowChoosePosition.vue(scoped 副本)、common.less(全局)三处的规则已全部收编。

覆盖的树类型:

类型 选择器根 用到的组件
目录树 / 普通树(a-directory-tree / a-tree) .s-tree-common、.ant-tree* STree、SBelowChoosePosition、业务原生 <a-tree>
树下拉弹层(a-tree-select) .s-tree-select-popup STreeSelect、SDataRangeTreeSelect(popup-class-name 挂类)
侧栏树容器高度 .s-side-tree SListLayout / SListTableTreeLayout / SListCardLayout

颜色与尺寸全部走 --s-tree-* 变量,默认值等于改造前的硬编码值,视觉零变化:

变量 默认值 说明
--s-tree-node-height 30px 节点内容行高(弹层同用)
--s-tree-node-line-height 32px 树本体标题行高
--s-tree-node-padding-x 4px 弹层节点左右内边距
--s-tree-row-gap 4px 行间距(整行底色留缝)
--s-tree-node-radius 8px 整行圆角(悬浮 + 选中,画在 ::before 上)
--s-tree-switcher-color #000000a6 展开箭头色
--s-tree-hover-bg var(--s-color-bg) 悬浮整行底色,跟随主题主色(主色混白 90%;暗色下自动换主色深底)
--s-tree-selected-bg var(--s-color, #1677ff) 选中整行底色,已跟随主题主色
--s-tree-selected-text #fff 选中整行文字/箭头色
--s-tree-directory-selected-bg #bae7ff 目录树选中浅色底(antd blue-2)
--s-tree-directory-selected-text #000000a6 目录树选中文字色
--s-tree-icon-color #fff 节点类型图标文字色
--s-tree-icon-bg transparent 节点图标默认底色
--s-tree-icon-bg-g / -c / -d #a9a9f5 / #d3b403 / #f09191 节点图标 G/C/D 类型底色

换主题色时按需覆盖即可,不用改组件:

/* 纯 CSS 主题:body 上已由基座挂 theme-xxx 类(见 §2.8) */
body.theme-green {
  --s-tree-selected-bg: #00b96b;
  --s-tree-directory-selected-bg: #d9f7e9;
  --s-tree-directory-selected-text: #1f1f1f;
}

/* 全局微调尺寸 */
:root {
  --s-tree-node-height: 32px;
  --s-tree-row-gap: 6px;
}

注意两点:

  1. --s-tree-selected-bg 默认是 var(--s-color, #1677ff),切主题色会自动跟随;浅色档 --s-tree-directory-selected-bg 默认仍是 antd blue-2,要跟随就显式覆盖。
  2. 变量只放「颜色/长度」本身,不要往里塞整条声明(如 --x: background:red)。

3.8 排查渲染问题的铁律

页面渲染/高度问题必须用 puppeteer 登录后量真实 offsetHeight/offsetLeft/盒模型,禁止静态读代码猜根因。

// 量:容器高、主体高、底部条位置差、文档溢出
const r = await page.evaluate(() => {
  const q = (s) => document.querySelector(s)
  const box = (s) => {
    const el = q(s)
    if (!el) return null
    const b = el.getBoundingClientRect()
    return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) }
  }
  return {
    container: box('.list-layout-main'),
    tableContent: box('.table-content'),
    pagination: box('.ant-table-pagination'),
    docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight
  }
})

验收标准(全部为 0 才算过):

指标 通过条件
documentOverflowY 0(页面不出现滚动条)
pagination.bottom 减容器底 0(分页刚好卡在视口底部)
表格主体溢出容器 0

多视口抽查(建议 1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440)全过才算改完。


四、构建与配置

4.1 构建与发布

npm run dev      # 基座本地开发
npm run build    # lib 构建 + 复制 docs/vite-plugins/package.json 到 dist + git push
npm run lint

基座构建 不 drop console($utils/i18n 调试输出由运行时 VITE_CONFIG_sapit-base-template 控制);业务构建才 drop。

产物:入口 ./packages/index.js,vue external,输出 dist/lib,打包内容为入口依赖图(不是整个项目);package.json 的 files: ["lib","docs","vite-plugins"]。

4.2 配置来源与优先级

基座默认 defaultEnv  <  业务 web-config.js  <  .env.[sapit-base-template](构建时写入 config.json)  <  部署 config.json(运行时覆盖)
  • web-config.js:可写默认值或 import.meta.env.VITE_APP_*;
  • .env / .env.[sapit-base-template]:各环境一套(dev/test/uat/prod),由业务 vite.config.js 写入 config.json;
  • config.json:站点根(子路径为 <base>config.json),启动时 loadRemoteConfig() 拉取并覆盖,部署后可直接改、无需重打包;.env 值为字符串,基座会把 "true"/"false" 归一为布尔。

常用开关(业务可按需覆盖;判断统一用 !== false,即未配置时取基座默认值):

配置项 默认值 说明
VITE_APP_FOOTER_VISIBLE false 是否显示页脚
VITE_APP_MESSAGE_VISIBLE true 是否显示右上角消息铃铛(设 false 隐藏)
VITE_APP_SOCKET_URL ws://127.0.0.1:8080/websocket socket 地址:只写协议+主机+端口,不要带 /apig/ 等路径;为空或 / 时走同源;本地占位地址在非本机环境下自动跳过
VITE_APP_SOCKET_PATH /apig/ws/websocket socket.io 握手路径,需与后端一致(真正的服务路径只认这一项)
VITE_APP_LANG_ENABLE false 是否启用国际化
VITE_APP_MENU_BAR left 菜单布局:left / top(业务可选)
VITE_APP_MENU_THEME light 菜单配色模式:light 跟主题色的浅色系 / dark 黑色(业务可选)
VITE_APP_THEME_FOLLOW_SYSTEM true 是否跟随系统深浅色(prefers-color-scheme):系统切深色时菜单换黑 + 中性色令牌换暗色版,运行时即时生效(业务可选)
VITE_APP_MENU_BG theme 基座锁定:light 一级底;theme 跟随主题色(默认)/ #RRGGBB 固定
VITE_APP_MENU_BG_LIGHTNESS 93 基座锁定:一级底亮度 0-100
VITE_APP_MENU_BG_SATURATION 66 基座锁定:饱和度上限 0-100
VITE_APP_MENU_BG_ACTIVE_MIX 16 基座锁定:选中块里主题色的占比 0-100
VITE_APP_MENU_SUB_BG 空 基座锁定:子菜单展开区底色;空 = 按主题色相推导
VITE_APP_MENU_HOVER_BG 空 基座锁定:悬停项底色;空 = 按主题色相推导
VITE_APP_MENU_ACTIVE_BG 空 基座锁定:选中块底色;空 = 主题色兑白(占比见 _BG_ACTIVE_MIX)
VITE_APP_MENU_TEXT 空 基座锁定:普通文字色;空 = 按主题色相推导
VITE_APP_MENU_TEXT_HOVER 空 基座锁定:悬停文字色
VITE_APP_MENU_TEXT_ACTIVE 空 基座锁定:选中文字色
VITE_APP_MENU_GROUP_TITLE 空 基座锁定:分组标题文字色

标「基座锁定」的 11 项即使写进业务 .env、src/config/web-config.js 或部署目录 config.json,也会被基座强制回填成上表默认值;业务能决定的只有 VITE_APP_MENU_THEME(选哪套)、VITE_APP_MENU_BAR(侧边 / 顶部)与 VITE_APP_THEME_FOLLOW_SYSTEM(是否跟随系统深浅色)。机制与色板推导见 2.18。

socket 是整站一条连接(packages/utils/socket.js,单例,与源项目 VueSocketIO 只注册一次一致),消息与扫码登录共用同一个地址、同一个 path,只靠事件名区分:

业务 上报事件 接收事件 模块
右上角消息铃铛 sendUserId(userId) wsEvent packages/utils/message-socket.js
扫码登录 QRCodeKey(qrId) QRWsEvent packages/utils/qr-login-socket.js

数量逻辑:进入系统先调 message/center/counts 取 totalCount,之后由 socket 推送的 wsEvent 触发重新拉取。业务侧无需注册任何东西,只要把 VITE_APP_SOCKET_URL / VITE_APP_SOCKET_PATH 配到网关即可。

VITE_APP_SOCKET_URL 里写了路径会踩坑:socket.io 把 URL 的 path 当 namespace(io('http://h:50001/apig/') → namespace /apig/),服务端回 Invalid namespace,握手成功但永远不 connect,也不报 connect_error。基座虽已在 resolveSocketUrl 里剥掉 path 兜底,配置仍建议规范写。

4.3 业务项目启动(npm start)

业务项目(sapit-base-template)的 npm start 执行内置脚本 refresh-sapit-base-template.ps1:

  1. 清理 node_modules/.vite、node_modules/sapit-ui-plus 及锁文件(package-lock.json/yarn.lock/pnpm-lock.yaml/node_modules/.package-lock.json);
  2. npm install 拉取 sapit-ui-plus 最新发布版本;
  3. 自动执行 npm run dev 启动。

作用:清理依赖缓存,更新业务依赖并一键启动。也可双击 refresh-sapit-base-template.cmd;-NoStart 仅更新不启动。 这个命令通常在基座项目有更新时才会用到。

五、业务项目接入

5.1 安装

{ "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } }

5.2 入口 main.js

import { createApp } from 'vue'
import App from './App.vue'
import config from './config/web-config'
import appConfig from './config/app-config'
import SapitUiPlus from 'sapit-ui-plus'
import 'sapit-ui-plus/lib/css/style.css'

async function init() {
  const pages = import.meta.glob('@/views/**/*.vue')
  const app = createApp(App)
  app.use(SapitUiPlus)
  await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)
  app.mount('#app')
}
init()
  • config:环境配置(web-config);
  • appConfig:构建期配置(登录/首页覆盖、静态路由、语言包),不进入 config.json;
  • pages:业务所有页面,用于动态路由按 hrefs 匹配。

5.3 登录页 / 首页覆盖

app-config.js:

export default {
  components: {
    login: () => import('@/views/login/index.vue'),
    home: () => import('@/views/home/index.vue')
  }
}

不配置则用基座默认(pages/login.vue、todo.vue)。

5.4 静态页面 staticRoutes

export default {
  staticRoutes: [
    {
      path: '/help',
      name: 'Help',
      component: () => import('@/views/help/index.vue'),
      meta: { title: '帮助' } // hidden: 不进菜单;public: 免登录
    }
  ]
}

layout: false / raw: true 时不包 BasicLayout;同 path 时业务覆盖基座内置。

5.5 业务页面与菜单

后端菜单 hrefs 需匹配业务 views 路径(或组件名);页面放 src/views/** 即可被动态路由识别。侧边菜单渲染「动态菜单 + staticRoutes」,基座常量菜单不进菜单。

5.6 国际化 / 主题

国际化

  • 词条文件:views/<模块>/i18n.js,扁平 { '中文': 'English' },命名空间 = views 之后的第一段目录名。
  • 页面里不用写 useI18n:$l('中文') 自动按页面所在目录命中;跨目录强制指定用 this.useI18n('<模块>')(Options API)或 window.useI18n('<模块>')(<script setup>)。
  • 聚合只在业务 src/config/app-config.js 里做一次,新增文件 / 新增目录都不用改代码:
// src/config/app-config.js
const locales = import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true })
export default {
  // ...其它业务配置
  locales // 由 main.js 的 { ...config, ...appConfig } 交给 $registerGlobalConfig 与基座合并
}
  • locales/** 用来覆盖基座词条:src/locales/components/i18n.js 对应命名空间 components(组件库通用词),业务同名优先。
  • 语言切换器由 .env 的 VITE_APP_LANG_ENABLE 控制(true 显示);false 时词条照常工作,中文直出。
  • 老写法 home-i18n.js / login-i18n.js 这类带前缀的文件名已废弃:一律用 i18n.js,否则推导出的命名空间是 default/home、default/login 这种不存在的名字,词条不会命中。

主题

只改 VITE_APP_THEME_VALUE;样式用 var(--s-*) 或 .s-theme-*。菜单配色只由基座决定(跟随主题色推导 + 系统深色跟随),业务只能选 VITE_APP_MENU_THEME 的 light / dark、以及要不要开 VITE_APP_THEME_FOLLOW_SYSTEM(见 2.18)。

5.7 子路径部署(示例 /monitor/)

  1. .env:VITE_APP_BASE_URL=/monitor/;
  2. 业务 vite.config.js:base: getViteEnv(res.sapit-base-template, 'VITE_APP_BASE_URL') || '/';
  3. 基座路由 base、$push/$open、redirectLogin、parseAppUrl 均读该值自动带前缀;
  4. nginx:
location /monitor/ {
    alias /home/project/tmp/dist/;
    index index.html;
    try_files $uri $uri/ /monitor/index.html;
}
location = /monitor/config.json {
    alias /home/project/tmp/dist/config.json;
    add_header Cache-Control "no-store";
}

createWebHistory base、Vite base、window.location 跳转三者必须都是 /monitor/(带尾斜杠)。

5.8 使用组件与权限

<template>
  <s-list-layout :columns="columns" :loadData="page" title="示例" />
  <s-user-select v-sapit-base-templatel:value="ids" />
  <a-button v-action="'add'">添加</a-button>
</template>

后端下发 permissions 后基座写入 permission,用 v-action:xxx 控制按钮级权限。文档访问:<业务base>/docs、<业务base>/components。


5.9 内置依赖(业务开箱即用)

sapit-ui-plus 的 dependencies 会随基座一起装进业务 node_modules,业务无需再装即可直接 import(业务 package.json 里通常只见 sapit-ui-plus 一项)。

依赖 版本 用途
dayjs ^1.11.12 日期格式化(推荐,$utils 内也用)
axios ^1.7.3 请求(已封装为 window.$utils.http,一般不用直接用)
qs ^6.13.0 参数序列化(stringify)
lodash.get / lodash.clonedeep ^4.4.2 / ^4.5.0 安全取值 / 深拷贝
crypto-js ^4.2.0 加解密
js-base64 ^3.7.2 Base64 编解码
jsencrypt ^3.3.2 RSA 加密
moment ^2.30.1 日期(老代码兼容,新代码用 dayjs)
html2canvas ^1.4.1 页面截图
nprogress ^0.2.0 顶部加载进度条
@vueuse/core ^11.0.3 组合式工具函数
vue-cropper ^1.1.4 图片裁剪(SCopperUpload 用它)
vuedraggable ^4.1.0 拖拽排序
v-clipboard ^3.0.0-next.1 复制到剪贴板(v-clipboard 指令)
vue-ls ^4.2.0 localStorage 封装(已包成 $utils.ls)
jodit 3.24.7 富文本编辑器(SEditor)
less / less-loader ^4.2.0 / ^12.2.0 样式编译
vite-plugin-html / vite-plugin-generate-file ^3.2.2 / ^0.2.0 构建插件(生成 config.json 等)
@ant-design/icons-vue 随 ant-design-vue 图标,全部已全局注册为组件

单例依赖:基座不做打包,业务必须自己安装(vite.config.js 的 external),否则会出现两个模块实例(路由注入不上、pinia 对不上、主题/消息上下文丢失):

依赖 版本
vue ^3.4.29
vue-router ^4.3.3
pinia ^2.1.7
vue-i18n ^9.14.0
ant-design-vue 4.x

用法:import dayjs from 'dayjs' 直接可用;但不要在业务里再装一份与基座不同大版本的 vue/ant-design-vue/pinia,版本以基座为准。

5.10 全局注入(无需 import)

名称 说明
$utils 工具类:$utils.http(请求)、$utils.ls(本地存储)、$utils.env(配置)等
$message / $modal / $notice ant-design-vue 的 message / Modal / notification
$push / $open 站内跳转 / 新窗口打开(自动拼接部署 base)
$l 国际化取词($l('中文'))
$theme 当前主题变量;CSS 变量 --s-color 等
$icons 全部 antd 图标组件
$socket / $filter / $pinia / $i18n websocket / 过滤器 / 用户 store / i18n 实例
env 同 $utils.env
$staticRoutes 静态页面路由(含业务自定义)
$getPdf({ el, title }) 页面导出 PDF;html2canvas + jsPDF 动态加载(见 2.2)

六、注意事项

6.1 业务侧

  1. 依赖是预构建产物:基座改动需 npm run build 推送且业务重装依赖才生效;基座 dev 立即生效。
  2. 锁文件会钉住旧提交:更新前删 package-lock.json、yarn.lock、node_modules/.package-lock.json。
  3. 子路径:VITE_APP_BASE_URL 与 Vite base 保持一致且带尾斜杠。
  4. 全局组件命名:按文件名注册(SForm.vue → <SForm>,不是 kebab-case);冲突后者覆盖。
  5. 主题 / 菜单配色 / 国际化:定义都在基座。业务只选 VITE_APP_THEME_VALUE、VITE_APP_MENU_THEME(light / dark)、VITE_APP_THEME_FOLLOW_SYSTEM(是否跟随系统深浅色)、只写 i18n 文案;VITE_APP_MENU_* 颜色与调色项由基座锁定,业务写了也会被回填(见 2.18)。
  6. 不能深路径 import 基座内部模块:lib 产物只有 lib/js/index.js 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性($utils / $modal 那样)。
  7. 功能去留:源码(老 Vue2 项目)有的我们就有,源码没有的不要"顺手补齐"。新增功能前先确认参照实现。

6.2 开发 / 构建

  1. 不要并发跑两个 vite build:会报 Rollup failed to resolve import "sapit-ui-plus",是缓存冲突的假报错,串行重跑即恢复。若串行仍报错,检查 node_modules/sapit-ui-plus 是否被清空(npm 重装常清掉)——恢复方式:
   # 基座 dist 就是 npm 包内容(build 脚本把 package.json + docs + vite-plugins 拷进 dist)
   cp -r <基座>/dist/lib <基座>/dist/docs <基座>/dist/vite-plugins <基座>/dist/package.json <业务>/node_modules/sapit-ui-plus/
   cp -r <基座>/packages/sso <基座>/packages/static <业务>/node_modules/sapit-ui-plus/
  1. vite build --emptyOutDir false:清空 dist 会被批量删除守卫拦截;只验证编译时用这个参数,不要为了验证去执行会 git push 内网仓库的 npm run build(对外发布动作,须先确认)。
  2. 不要并发跑两个基座构建 / 业务安装,避免缓存互相污染。
  3. vite build 不检查未定义变量:模板/脚本里引用不存在的变量照样通过。改完大段代码必须 git diff 复核增删行,配合未使用 import 扫描发现误删。
  4. npm 国内网络:registry.npmjs.org 基本不通,装 sapit-ui-plus 会卡在大包上(最重的是 ant-design-vue 解压 78MB、jodit 23MB)。装包指定国内源:

    npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com
    

    若 npm 进程内的 git ls-remote 返回 403(沙箱/网络拦截,手工 git ls-remote 却通),只能临时摘掉该 git 依赖装其余包,再按第 8 条从基座本地 dist 恢复。

    1. npm 包必须含根级 static/:lib 构建不重写 new URL('../../static/...', import.meta.url),运行时从 lib/js/*.js 解析到包根 static/。缺它业务 dev 登录页图片全 404,而基座自身 dev 正常、生产正常,极具迷惑性。
    2. lib 构建图片:Vite 对 build.lib 强制内联所有资产 → 产物可能出现 MB 级 base64 data URI(超 Chrome URL 上限)。vite-plugins/sso-plugin 的 closeBundle 会把 >100KB 的 data URI 抽为 lib/img/ 真实文件;源码资产引用一律改 import。

    6.3 业务字典 / 表单约定(hy-monitor)

    1. 下拉 value / 文案一律取字典项的 value(字典值),绝不用 id(主键)。字典调mapByDictTypes('a','b') 一次性取多个,按下划线转驼峰取返回值(recycle_status → res.recycleStatus),项为 {label, value, id}。
    2. a-select 的 placeholder 只在值为 undefined/null 时显示,空字符串 '' 会被视为已有值。所有下拉类字段(搜索参数、表单字段)初始值一律 undefined,禁用 ''(多选绑定 [] 正常)。
    3. 时间范围参数统一传毫秒时间戳(dayjs(x).valueOf()),不是 unix 秒。依据:源码 DateRange 的 onChange 输出 date.map(o => dayjs(o).valueOf()),useFormValues.fieldMapToTime 默认 format='' 原样透传。
    4. 接口请求不写 catch(错误由全局拦截器统一提示)。但三类 catch 必须保留:① 表单校验链 .catch(() => {});② try { await validate() } catch { return };③ JSON.parse 解析容错。
    5. 接口报错会跳内置错误页:HTTP 403(含 301)→ /403、404 → /404,在内容区 router-view 内切换(保留侧边菜单与顶栏,不整页顶掉外壳),且不再叠加通知。跳转 URL 带 ?api=<接口地址>&status=<原始状态码>,错误页据此切换成接口口径文案(403「接口无权限」、301「接口地址已变更」、404「接口不存在」)并显示接口地址;不带 ?api= 时仍是页面口径(页面无权限 / 页面不存在)。5xx 不跳错误页,仍走原来的通知提示(/500 页面保留,可直接访问)。后台轮询等非主流程请求若要保住当前页面,可传 { skipErrorPage: true } 跳过跳转:
    this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })
    

七、常见全局方法速查

调用 作用
$l('中文'[, key]) 国际化
$push(path, query) / $open(path, query) 跳转 / 新窗口(自动拼 base)
$message.* / $modal.* / $notice.* / $confirm(...) 轻提示 / 弹窗 / 通知 / 确认框
this.$utils.ls.get/set/clear 本地存储
this.$utils.http(config) 发起请求(默认 POST)
$filter.dateFormat(v, fmt) 日期格式化
v-action:code 按钮级权限(按 button_code 全等匹配)
$utils.hasAction(code) 按钮级权限(函数式,可做「或 / 且」)
$utils.iconOf('info-circle') antd v1 type 写法换图标组件
$utils.messageFormat(str, values) {0} / {name} 占位符替换
$utils.filterSelectOption(iv, opt) antd4 版下拉过滤
$utils.randomDrawerPlacement() 随机抽屉方向
var(--s-color) / .s-theme-color 主题色(CSS 变量 / 工具类)

八、在线文档入口

地址 内容
<base>/docs 说明文档(本文)
<base>/components s组件(基座内置组件:左菜单 + 预览 + 源码)