适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、mode(业务示例)
本文档也是基座内置文档页
/docs与组件页/components的数据源。
| 工程 | 角色 | 说明 |
|---|---|---|
sapit-ui-framework |
基座(源码) | 内置组件与常用依赖的库工程,Vite lib 模式打包 |
sapit-ui-plus |
发布产物 | 基座 dist 推送后的 git 仓库(lib/、docs/、vite-plugins/) |
mode |
业务使用者 | 以 sapit-ui-plus git 依赖为底层,编写业务页面/配置 |
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> mode
sapit-ui-framework/
├─ packages/ # 发布内容来源(入口依赖图)
│ ├─ index.js # 库入口,导出 registerGlobalConfig
│ ├─ components/ # 内置组件 S*
│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView
│ ├─ router/ # 常量路由 + 动态路由 + 静态路由 + 守卫
│ ├─ store/ api/ utils/ locales/ static/ style/
│ └─ pages-components/ # 登录、工作台、待办、消息、404/403/500、docs 文档页
├─ docs/ # 本文档(供内置 /docs 渲染)
├─ vite-plugins/ # docs-viewer 插件
├─ src/ # 基座自身调试壳
└─ vite.config.js / package.json
packages/index.js 用 import.meta.glob('./components/**/*.vue') 把 components/**/*.vue 按文件名全局注册,模板直接以文件名标签使用(如 <s-modal>、<s-user-select>)。
| 分类 | 组件 |
|---|---|
| 布局类 | SListLayout、SListCardLayout、SListTableTreeLayout、SSuperListLayout、SFormLayout、SPanelLayout、SCollapses/SCollapsesItem、SDrawer |
| 弹层类 | SModal、SModalTemplate、ModalHeader、SIconModal |
| 表单/筛选 | SForm、SFormItem、SFilterWrap、SFilterItem、SCascader、STree、STreeSelect、SUserSelect、SOfficeSelect、SIconSelect、CustomInput |
| 上传类 | SFileUpload、SDraggerUpload、SCopperUpload、CropperModal |
| 展示/其它 | SEditor、SEmpty、SIcon、SSvg、SAnchor、SToggleLanguage、SettingFilter、SettingColumns、SSideMenu/STopMenu |
组件用法见内置组件页
/components。注意:
components/Table/index.jsx是.jsx,不在全局注册范围,需手动import。@ant-design/icons-vue图标全部全局注册并挂到$icons。
$registerGlobalConfig 执行后可用(this.$xxx / 模板 $xxx / window.$xxx):
| 名称 | 说明 |
|---|---|
$registerGlobalConfig(config, pages) |
初始化入口(见 4.2) |
$utils |
工具类集合:$utils.env / $utils.ls / $utils.http 及通用方法 |
env |
合并后的环境配置(= $utils.env) |
$i18n / $l(name, key) |
国际化(见 2.7) |
$theme / $staticRoutes / $pinia |
主题对象 / 静态路由列表 / 用户 store 实例 |
$modal / $message / $notice |
antd 的 Modal / message / notification |
$push(path, query) / $open(...) |
站内跳转 / 新窗口(自动拼 VITE_APP_BASE_URL) |
$filter / $icons / $socket |
日期格式化 / 图标集合 / websocket 封装 |
packages/layouts/index.js:BasicLayout(头部+侧边菜单+内容区)、BlankLayout、UserLayout(登录)、RouteView、PageView。
常量路由(packages/router/index.js):
| 路径 | 说明 |
|---|---|
/login/index |
登录页(默认基座,可被业务覆盖,见 4.5) |
/workplace/index |
默认首页(VITE_APP_DEFAULT_PATH,可被覆盖) |
/workbench/index、/message/index |
工作台 / 消息 |
/docs、/components |
内置文档 / 组件页(public 免登录、hidden 不进菜单) |
/404、/403、/500、/:pathMatch(.*)* |
错误页;通配渲染 404(不用 redirect,保证刷新动态路由不掉 404) |
静态路由(staticRoutes,不依赖后端菜单):见 4.6。基座内置 /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(见 4.8 单点)。
packages/store/user.js(useUserStore):state user/menus/permissions/clients/dynamicRouter/menuOpenKeys;actions Info()(拉取并写 localStorage)、setDynamicRouter()、setMenuOpenKeys();localStorage 持久化。
$utils)| 模块 | 说明 |
|---|---|
$utils.env |
环境配置对象 |
$utils.ls |
本地存储(命名空间 VITE_APP_SYS_SERVER_NAME) |
$utils.http |
axios 实例(token/client-id 注入、响应解包、登录超时、文件下载) |
parseAppUrl / innerRedirect 等 |
站内地址拼 base(支持子路径),外部 http(s) 原样 |
| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等 |
v-action:xxx 按钮级权限指令:<a-button v-action="'add'">添加</a-button>。
语言包构建时聚合 packages/**/*-i18n.js 与 src/views/**/*-i18n.js,key 为文件名前缀(如 layouts.add、components.upload)。
$l(name, key):中文/未开启国际化 → 返回 name;英文模式传了 key → 取 lang.en[key],取不到把 key 当英文;未传 key → 走中文→英文兜底字典(packages/locales/lang/dict.js)。
<span>{{ $l('添加') }}</span> <span>{{ $l('账户密码登录', 'account password') }}</span>
key为路径时需先在对应*-i18n.js定义,否则原样显示该 key。antd 自身语言由a-config-provider的locale控制。
定义只由基座维护: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 会被忽略。
生效方式:
a-config-provider token(colorPrimary/colorLink)。:root:--s-color、--s-light-color、--s-dark-color、--s-border-color、--s-bg-color;并内置工具类 .s-theme-bg、.s-theme-color、.s-theme-border、.s-theme-border-top、.s-theme-icon-bg。theme-<VITE_APP_THEME_VALUE>(如 theme-blue)。.my-box {
color: var(--s-color);
background: var(--s-bg-color);
}
新增主题:基座
VITE_APP_THEME加一套,业务VITE_APP_THEME_VALUE选它,antd 与var(--s-*)自动跟随。
packages/api:login.js(登录、getCode、verify、rsaPublicKey、getLoginConfig 等)、common.js、upload.js、workbench.js。packages/pages-components: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.* 等已内置。/login/index:账号密码登录;登录失败达 getLoginConfig 策略(enabled + codeThreshold)时出现图片验证码(/user/verify),verificationCode 原文提交 + verificationCodeId。code 时由守卫调 getCode(code) 换 token → 存 $utils.ls → 去掉 code 整页刷新(与参照项目一致)。VITE_APP_CLIENT_ID 必须等于业务在认证中心的 client;接口网关用 VITE_APP_PORTAL_SERVER_NAME。npm run dev # 基座本地开发
npm run build # lib 构建 + 复制 docs/vite-plugins/package.json 到 dist + git push
npm run lint
基座构建 不 drop console(
$utils/i18n 调试输出由运行时VITE_CONFIG_MODE控制);业务构建才 drop。
产物:入口 ./packages/index.js,vue external,输出 dist/lib,打包内容为入口依赖图(不是整个项目);package.json 的 files: ["lib","docs","vite-plugins"]。
基座默认 defaultEnv < 业务 web-config.js < .env.[mode](构建时写入 config.json) < 部署 config.json(运行时覆盖)
web-config.js:可写默认值或 import.meta.env.VITE_APP_*;.env / .env.[mode]:各环境一套(dev/test/uat/prod),由业务 vite.config.js 写入 config.json;config.json:站点根(子路径为 <base>config.json),启动时 loadRemoteConfig() 拉取并覆盖,部署后可直接改、无需重打包;.env 值为字符串,基座会把 "true"/"false" 归一为布尔。npm start)业务项目(mode)的 npm start 执行内置脚本 refresh-mode.ps1:
node_modules/.vite、node_modules/sapit-ui-plus 及锁文件(package-lock.json/yarn.lock/pnpm-lock.yaml/node_modules/.package-lock.json);npm install 拉取 sapit-ui-plus 最新发布版本;npm run dev 启动。作用:清理依赖缓存,更新业务依赖并一键启动。也可双击
refresh-mode.cmd;-NoStart仅更新不启动。 这个命令通常在基座项目有更新时才会用到。
{ "dependencies": { "sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git" } }
main.jsimport { 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 匹配。app-config.js:
export default {
components: {
login: () => import('@/views/login/index.vue'),
home: () => import('@/views/home/index.vue')
}
}
不配置则用基座默认(pages-components/login.vue、todo.vue)。
staticRoutesexport default {
staticRoutes: [
{
path: '/help',
name: 'Help',
component: () => import('@/views/help/index.vue'),
meta: { title: '帮助' } // hidden: 不进菜单;public: 免登录
}
]
}
layout: false / raw: true 时不包 BasicLayout;同 path 时业务覆盖基座内置。
后端菜单 hrefs 需匹配业务 views 路径(或组件名);页面放 src/views/** 即可被动态路由识别。侧边菜单渲染「动态菜单 + staticRoutes」,基座常量菜单不进菜单。
$l('中文','English') 或基座 key;扩展在 appConfig 传 locales(深合并)。业务自身 *-i18n.js 不会被基座聚合。VITE_APP_THEME_VALUE;样式用 var(--s-*) 或 .s-theme-*。/monitor/).env:VITE_APP_BASE_URL=/monitor/;vite.config.js:base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/';$push/$open、redirectLogin、parseAppUrl 均读该值自动带前缀;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";
}
createWebHistorybase、Vitebase、window.location跳转三者必须都是/monitor/(带尾斜杠)。
<template>
<s-list-layout :columns="columns" :loadData="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。
npm run build 推送且业务重装依赖才生效;基座 dev 立即生效。package-lock.json、yarn.lock、node_modules/.package-lock.json。VITE_APP_BASE_URL 与 Vite base 保持一致且带尾斜杠。.jsx(如 Table)需手动引入。| 调用 | 作用 |
|---|---|
$l('中文'[, key]) |
国际化 |
$push(path, query) / $open(path, query) |
跳转 / 新窗口(自动拼 base) |
$message.* / $modal.* / $notice.* |
轻提示 / 弹窗 / 通知 |
this.$utils.ls.get/set/clear |
本地存储 |
this.$utils.http(config) |
发起请求(默认 POST) |
$filter.dateFormat(v, fmt) |
日期格式化 |
v-action:code |
按钮级权限 |
var(--s-color) / .s-theme-color |
主题色(CSS 变量 / 工具类) |