sapit-ui-基座说明与业务使用.md 64 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-plus 只有运行时需要的内容(不是基座源码工程):

node_modules/sapit-ui-plus/
├─ lib/              # 编译产物:js / css / 图片,业务 import 的就是它
├─ docs/             # 本文档,由内置 /docs 页渲染
├─ vite-plugins/     # 业务 vite.config.js 里按需引入的插件(如 sso-plugin)
├─ static/           # 静态资源(登录页图片等)
└─ package.json

业务只需要引三处:入口 sapit-ui-plus、样式 sapit-ui-plus/lib/css/style.css、按需的 vite-plugins/*。


二、基座提供的内容

2.1 全局组件

组件全部由基座全局注册,业务页面直接写标签即可,不需要 import、也不需要局部注册(如 <s-modal>、<s-user-select>、<s-table>)。

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

每个组件的 props / 事件 / 方法 / 插槽、可运行预览与示例代码,统一看内置组件页 /components(另有「工具/配置」标签页,列出 web-config 全部配置项与 $utils 全部方法)。

几条使用口径:

  • 组件注册名是 PascalCase(SForm / STable),模板里写 <SForm> 或 <s-form> 都能解析,保持一致即可。
  • @ant-design/icons-vue 图标已全部全局注册,并把图标集合挂在 $icons。
  • 基座内部有几个不对外使用的辅助组件(如 ModalHeader、CropperModal、SettingColumns / SettingFilter),业务不要直接引用。

2.2 全局属性 / 方法

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

名称 说明
$registerGlobalConfig(config, pages) 初始化入口(见 4.2)
$utils 工具类集合:$utils.env / $utils.ls / $utils.http 及通用方法
env 合并后的环境配置(= $utils.env)
$i18n / $l(name) 国际化(见 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)

按钮级权限(v-action 指令 / $utils.hasAction)与 $utils 各方法见 2.6;主题色变量与 .s-theme-* 工具类见 2.8。

2.3 布局

业务页面默认跑在 BasicLayout 的内容区里,外层布局有三种:

布局 用途
BasicLayout 顶栏 + 侧边/顶部菜单 + 内容区(动态路由、静态路由都默认包它)
UserLayout 登录、扫码、找回密码、激活这类免登录页面
BlankLayout 只要一个空壳,不要菜单与顶栏

业务页面高度:内容区高度由 BasicLayout 算好并透传给 router-view,页面根节点写 height: 100% 就会自动撑满。不要自己写 calc(100vh - 58px) 这类减法:顶栏高度、页脚、页签都会让这个数对不上,表现就是分页浮在中间或多出一条滚动条。

页面主体用布局组件(SListLayout / SFormLayout / SSkeletonLayout / SPanelLayout …),它们自己吃掉剩余高度并在内部滚动,业务只写内容。

页面主体布局组件怎么选:

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

2.4 路由

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

路径 说明
/login/index 登录页(默认基座,可被业务覆盖,见 4.3)
/login/:officeCode 同上,带单位编码进入(编码写入 $utils.ls 的 officeCode,见 2.10)
/user/qrCode、/user/forgotPassword、/user/activate 扫码登录 / 找回密码 / 账号激活三张独立页,父级 /user 带 meta.public,登录前可达(见 2.10)
/workplace/index 默认首页(VITE_APP_DEFAULT_PATH,可被覆盖)
/workbench/index、/message/index 工作台 / 消息
/docs、/components 内置文档 / 组件页(public 免登录、hidden 不进菜单)
/404、/403、/500、/:pathMatch(.*)* 错误页;通配渲染 404(不用 redirect,保证刷新动态路由不掉 404),渲染位置与文案见 2.11

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

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

动态路由:登录后按后端 menus 生成路由树,根节点是 BasicLayout;叶子节点用菜单的 hrefs 匹配业务 src/views/** 下的页面路径(或组件名),匹配不到回退 404。

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

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)。新增词条文件、新增目录都不用改任何代码,放进去即可。

页面里不用注册也能翻译:$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 控制。

业务侧接入(只在这里讲一次)

  1. 词条按上文放 views/<模块>/i18n.js,新增文件、新增目录都不用改代码。
  2. 在业务 src/config/app-config.js 里聚合一次,由 main.js 的 { ...config, ...appConfig } 交给 $registerGlobalConfig:
// src/config/app-config.js
const locales = import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true })
export default {
  // ...其它业务配置
  locales
}
  1. src/locales/** 用来覆盖基座词条:src/locales/components/i18n.js 对应命名空间 components(组件库通用词),业务同名优先。
  2. 语言切换器由 .env 的 VITE_APP_LANG_ENABLE 控制(true 显示);false 时词条照常工作,中文直出。
  3. 老写法 home-i18n.js / login-i18n.js 这类带前缀的文件名已废弃:一律用 i18n.js,否则推导出的命名空间是 default/home、default/login 这种不存在的名字,词条不会命中。

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. 菜单配色:另有一套 --s-menu-* 变量,按主题色推导(light)或固定 antd 黑(dark),业务只选模式、改不了色值 —— 见 2.12 菜单配色。
.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) 遮罩

业务样式一律用 var(--s-*),不要写字面色值(#1677ff / #e8e8e8 / rgba(0,0,0,.65) 这类):主色相关走主题令牌,灰阶走中性令牌,状态走语义令牌,换主题时才不用改代码。

主题色只有 blue / green / orange / pink / customer 这几套可选,业务只能选,不能自己加。

2.9 其它内置能力

内置 业务怎么用
登录 / 单点 / 找回密码 / 激活 全套接口 走基座登录页即可,细节见 2.10,换版式见 4.3
内置页面:工作台、待办、消息、403/404/500、/docs、/components 直接访问;工作台 / 首页可用业务自己的页面覆盖
静态资源、全局样式、主题令牌 packages/static、packages/style 已随包发布,业务不需要复制
常用依赖 sapit-ui-plus 的 dependencies 已随包装好,业务直接 import,清单见 4.8

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 静态资源由基座提供:业务项目不用再维护 public/ 下的 sso.js / sso.html,只需在 vite.config.js 里引入插件:

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

插件会在 dev 与构建时提供这两个文件。注意:sso.html 换 token 读的是同源 localStorage,跨 origin 的平台单点不能直接套用。

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 错误页(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

跳转表现:错误页是在内容区里切换的 —— 侧边菜单、顶栏、页脚保持原样,不会整页顶掉外壳。页面 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 })

改颜色 / 改文案:

  • 文案全部走 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% 铺满内容区,内部超长只在卡片里滚动,不会撑出页面级滚动条。

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

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

菜单色板由主题色推导(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 的不受影响。

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

业务可选的只有 3 个:

配置 默认 说明
VITE_APP_MENU_BAR left left 侧边 / top 顶部(布局项)
VITE_APP_MENU_THEME light light 跟主题色的浅色系 / dark 黑色
VITE_APP_THEME_FOLLOW_SYSTEM true 是否跟随系统深浅色(prefers-color-scheme)

下面 11 个颜色 / 调色键由基座锁定,在基座启动时强制回填,所以业务 .env、src/config/web-config.js、部署目录 config.json 三处写的菜单颜色全都无效 —— 所有业务项目的菜单外观与基座 demo 完全一致,这是有意为之:

键 默认 作用
VITE_APP_MENU_BG theme 一级菜单底: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 空 分组标题文字色

想自己验证一次:在业务 config.json 里写 "VITE_APP_MENU_BG": "#ff0000",刷新后菜单还是按主题色推导的那套值。

注意事项

  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 无需手动刷新。

三、构建与配置

3.1 基座更新后业务怎么拿到

基座以 npm 包(sapit-ui-plus)的形式发布,业务用的是预构建产物,不是源码:

场景 生效方式
基座改了组件 / 配置 / 文案 基座发版 → 业务更新依赖(npm start 或删锁文件后 npm i)才生效
只改了业务自己的页面 业务重启 dev 即可

业务侧更新依赖时必须删掉锁文件(package-lock.json / yarn.lock / node_modules/.package-lock.json),否则会钉在旧提交上,看起来像「基座的新功能没生效」。

3.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 是否启用国际化

菜单配色相关的 14 个键(VITE_APP_MENU_BAR / _THEME / THEME_FOLLOW_SYSTEM 可选,其余 11 个由基座锁定)统一列在 2.12 菜单配色,这里不重复。

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 兜底,配置仍建议规范写。

3.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 仅更新不启动。 这个命令通常在基座项目有更新时才会用到。

四、业务项目接入

4.1 安装

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

4.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 匹配。

4.3 登录页 / 首页覆盖

app-config.js:

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

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

4.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 时业务覆盖基座内置。

4.5 业务页面与菜单

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

4.6 子路径部署(示例 /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/(带尾斜杠)。

4.7 使用组件与权限

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

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


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

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.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. 组件全局可用:S* 组件、STable 都由基座全局注册,直接写标签,不要 import、不要重复局部注册。
  5. 主题 / 菜单配色 / 国际化:定义都在基座。业务只选 VITE_APP_THEME_VALUE、VITE_APP_MENU_THEME、VITE_APP_THEME_FOLLOW_SYSTEM 三个值,只写 i18n 文案;VITE_APP_MENU_* 色值写了也会被回填(见 2.7 / 2.8 / 2.12)。
  6. 不能深路径 import 基座内部模块:lib 产物只有 lib/js/index.js 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性($utils / $modal 那样)。
  7. 功能去留:源码(老 Vue2 项目)有的我们就有,源码没有的不要"顺手补齐"。新增功能前先确认参照实现。

5.2 业务字典 / 表单约定(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. 接口报错会跳内置错误页:403(含 301)→ /403、404 → /404,在内容区 router-view 内切换且不再叠加通知;5xx 不跳,仍走通知。后台轮询等非主流程请求传 { skipErrorPage: true } 可保住当前页面。URL 参数、文案口径与改色方法见 2.11:
this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })

六、在线文档入口

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