适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、mode(业务示例)
本文档同时是基座内置文档页
/docs的数据源(packages/pages-components/docs.vue在构建时用?raw内联本文件并渲染成 HTML)。
| 工程 | 角色 | 说明 |
|---|---|---|
sapit-ui-framework |
基座(源码) | 内置组件与常用依赖的库工程,Vite lib 模式打包 |
sapit-ui-plus |
发布产物 | 基座 dist 推送后的 git 仓库(含 lib/、docs/、vite-plugins/、package.json) |
mode |
业务使用者 | 以 sapit-ui-plus git 依赖为底层,编写业务页面/配置 |
数据流:
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git)
|
mode: npm install 安装依赖
sapit-ui-framework/
├─ packages/ # 打包入口依赖图(发布内容来源)
│ ├─ index.js # 库入口,导出 registerGlobalConfig
│ ├─ components/ # 内置组件 S*(*.vue 全局注册)
│ ├─ layouts/ # 布局(BasicLayout/BlankLayout/UserLayout/RouteView/PageView)
│ ├─ router/ # 常量路由 + 动态路由生成 + 静态路由 + 全局守卫
│ ├─ store/ # pinia(user)
│ ├─ api/ # login/common/upload/workbench 接口
│ ├─ utils/ # http/ls/filter/socket/rsa/action/markdown 等
│ ├─ locales/ # 国际化聚合与中文->英文兜底字典
│ ├─ pages-components/ # 登录、工作台、待办、消息、404/403/500、docs 文档页
│ ├─ static/ # 图片/svg 资源
│ └─ style/ # common.less / theme.less / nprogress.less
├─ docs/ # 说明文档(同时供内置 /docs 页面渲染)
├─ vite-plugins/ # docs-viewer 插件(独立 HTML 预览 + 控制台提示)
├─ src/ # 基座自身的调试壳(不全部打包,见 3.2)
├─ vite.config.js # lib 构建配置
└─ package.json # name: sapit-ui-plus
packages/index.js 通过 import.meta.glob('./components/**/*.vue') 将 components 下所有 .vue 组件 按文件名全局注册(异步组件),可直接以文件名作为标签使用(如 <s-modal>、<s-user-select>、<s-file-upload>)。
| 分类 | 组件 |
|---|---|
| 布局类 | 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/Table/index.jsx是.jsx,不在全局注册范围内,需按需import。
同时,@ant-design/icons-vue 的所有图标会被全局注册,并挂到 $icons。
在 $registerGlobalConfig 执行后,组件内可 this.$xxx,模板内可 $xxx,也可通过 window.$xxx 使用:
| 名称 | 说明 |
|---|---|
$registerGlobalConfig(config, pages) |
初始化入口(见第四节) |
$utils |
工具类集合,含 $utils.env、$utils.ls、$utils.http 及大量通用方法 |
env |
合并后的环境配置(等同 $utils.env) |
$pinia |
用户 store 实例 |
$socket |
websocket 封装 |
$filter |
日期格式化:dayJsFormat / dayFormat / dateFormatDay / dateFormat |
$i18n |
vue-i18n 实例 |
$l(name, key) |
国际化方法(见 2.7) |
$theme |
当前主题配置对象(见 2.8;组件内已改用 CSS 变量,一般不直接使用) |
$staticRoutes |
当前注册的静态页面路由列表 |
$modal / $message / $notice |
对应 ant-design-vue 的 Modal / message / notification |
$push(path, query) |
站内跳转(自动拼接 VITE_APP_BASE_URL) |
$open(path, query) |
新窗口打开(自动拼接 base) |
$icons |
全部 antd 图标集合 |
packages/layouts/index.js 导出:BasicLayout(含头部/侧边菜单/内容区)、BlankLayout、UserLayout(登录,渲染 <router-view/>)、RouteView(二级内容区)、PageView(面包屑 + 内容区)。
常量路由(packages/router/index.js):
| 路径 | 说明 |
|---|---|
/login/index |
登录页(默认基座登录页,可被业务覆盖,见 4.5) |
/workplace/index |
默认首页(VITE_APP_DEFAULT_PATH;默认基座首页,可被业务覆盖) |
/workbench/index |
工作台 |
/message/index |
消息 |
/docs |
内置文档页(免登录、不进菜单,见 2.11) |
/404、/403、/500 |
错误页 |
/:pathMatch(.*)* |
通配,渲染 404 组件(不用 redirect,保证刷新动态路由时守卫能拿到真实地址) |
静态路由(staticRoutes,不依赖后端菜单):见 4.6。基座内置静态页 builtinStaticRoutes 已包含 /docs。
动态路由(packages/router/generator-routers.js):
menus 生成路由树,根节点用 BasicLayout;parent.id、是否有 children)决定 PageView/RouteView;叶子节点用 item.hrefs 去匹配业务传入的 pages(import.meta.glob('@/views/**/*.vue') 的 key),匹配不到则回退 404 组件;全局守卫能力:
meta.public,如 /docs)直接放行,不校验 token/权限;packages/store/user.js(useUserStore):
user、menus、permissions、clients、dynamicRouter、menuOpenKeysdynamics(= dynamicRouter)、openKeysInfo()(拉取用户信息/菜单/权限并写入 localStorage)、setDynamicRouter()、setMenuOpenKeys()$utils)| 模块 | 说明 |
|---|---|
$utils.env |
环境配置对象 |
$utils.ls |
本地存储(命名空间为 VITE_APP_SYS_SERVER_NAME),含 get/set/clear 等 |
$utils.http |
axios 实例(已封装:token 注入、响应结构解包、401/status:-1 登录超时处理、文件下载) |
parseAppUrl(url) |
站内地址拼接 base(支持子路径部署),外部 http(s) 原样返回 |
innerRedirect / innerReplace / innerOpen |
基于 parseAppUrl 的站内跳转 |
| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额/千分位、手机号校验等(见 packages/utils/utils.js) |
另提供:v-action:xxx 权限指令(packages/utils/action.js),无权限时移除元素。用法:
<a-button v-action="'add'">添加</a-button>
<a v-action:edit>修改</a>
/packages/pages-components/*-i18n.js/packages/components/*-i18n.js/packages/layouts/*-i18n.js/src/views/**/*-i18n.jslayouts.add、components.upload。$l(name, key) 规则:中文模式 / 未开启国际化 -> 返回 name(中文)
英文模式 + 传了 key -> 先取 lang.en[key],取不到则把 key 当英文返回
英文模式 + 未传 key -> 走中文->英文兜底字典(packages/locales/lang/dict.js)
a-config-provider 的 locale 控制(BasicLayout/App.vue)。<span>{{ $l('添加') }}</span>
<!-- 中文:添加 / 英文:Add -->
<span>{{ $l('账户密码登录', 'account password') }}</span>
提示:第二个参数若是 key 路径(如
page-components.xxx),必须先在对应*-i18n.js里定义;否则会原样显示该 key 字符串。直接写英文字面量则无需定义。
主题分为两套并用,颜色定义只由基座维护:
packages/config/web-config.js 的 VITE_APP_THEME(每套含 color/lightColor/darkColor/borderColor/bgColor)。VITE_APP_THEME_VALUE(如 blue/green/orange)。基座会强制以自身 VITE_APP_THEME 为准,业务/config.json 传入的 VITE_APP_THEME 会被忽略。生效方式:
a-config-provider 的 token(colorPrimary/colorLink)驱动,来源为选中主题的 color。:root 变量:--s-color 主题主色
--s-light-color 浅色
--s-dark-color 深色
--s-border-color 边框色
--s-bg-color 背景色
并提供现成工具类(packages/style/theme.less):
.s-theme-bg { background-color: var(--s-bg-color); }
.s-theme-color { color: var(--s-color); }
.s-theme-border { border-color: var(--s-bg-color); }
.s-theme-border-top { border-top-color: var(--s-color); }
.s-theme-icon-bg { background-color: var(--s-border-color); }
body 会加上 theme-<VITE_APP_THEME_VALUE>(如 theme-blue),供自定义 CSS 使用。业务自定义样式直接使用变量即可:
.my-box {
color: var(--s-color);
background: var(--s-bg-color);
border: 1px solid var(--s-border-color);
}
新增主题:在基座
VITE_APP_THEME里加一套(如purple),业务把VITE_APP_THEME_VALUE设为purple,antd 与var(--s-*)会自动跟随,无需改 less。
packages/api)| 文件 | 内容 |
|---|---|
login.js |
login、info、getCode、verify、rsaPublicKey、验证码/短信/登录配置等 |
common.js |
组织树、字典分页、用户/岗位按 id 查询、文件预览地址等 |
upload.js |
上传/下载/在线预览 |
workbench.js |
工作台示例分页/导出/导入等 |
packages/pages-components)login.vue、login-common/LoginForm.vue、workbench.vue、todo.vue、message.vue、403.vue、404.vue、500.vue、docs.vue。
基座内置了一个文档页,数据源就是本文件 docs/*.md:
应用内页面:路由 /docs,packages/pages-components/docs.vue 用 ?raw 内联 md 并渲染。该路由 meta: { public: true, hidden: true } 且 layout: false:
公开页面地址: <origin>/docs,且会拼接 VITE_APP_BASE_URL)。独立 HTML 预览(开发/预览服务):vite-plugins/docs-viewer.js 在 /docs-preview 提供整页 HTML 预览(方便直接浏览器打开)。
业务同样可用:/docs 是基座内置静态页,随依赖提供,业务重装依赖后自动拥有,访问地址为 <业务base>/docs。
packages/static/img、packages/static/svg(SVG 通过 vite-plugin-svg-icons 以 icon-[name] 注入)。packages/style/common.less、theme.less、nprogress.less;构建时全局注入 src/assets/main.less。npm run dev # 本地开发(基座自身调试壳)
npm run build # 生产构建 + 复制产物 + 推送 git
npm run lint # eslint
基座构建 不 drop console,因为
$utils、i18n 等调试输出由运行时VITE_CONFIG_MODE控制;若构建期 drop,会把业务 dev 需要的输出一起删掉。业务侧构建才 drop console。
vite.config.js,lib 模式)./packages/index.js;vue 为 external;dist/lib;packages/ 被引用部分 + src/assets/main.less + public 静态文件),不是整个项目;src/ 其余演示代码、index.html、vite.config.js 不打包;dist/
├─ lib/
│ ├─ js/ # 入口与异步 chunk(index.js、docs.js、SEditor.js 等)
│ ├─ css/style.css # 含主题工具类 .s-theme-* 与 --s-* 兜底
│ ├─ config.json # 构建时生成(默认环境)
│ └─ favicon.ico
├─ docs/ # 说明文档
├─ vite-plugins/ # docs-viewer 插件
└─ package.json
package.json 的 files: ["lib", "docs", "vite-plugins"]。
vite-plugin-generate-file 生成:{ _hash, ...web-config字段, ...loadEnv(.env*), VITE_CONFIG_MODE };<base>config.json);loadRemoteConfig() 会 fetch 它并覆盖 web-config(见 4.4),部署后可直接修改而 无需重新打包;.env 的值都是字符串,基座启动时会把 "true"/"false" 自动归一为布尔,避免 "false" 被当成真值。npm run build 会依次执行:vite build → 复制 package.json/docs/vite-plugins 到 dist/ → 在 dist/ 内 git init/add/commit → git push -f 到 sapit-ui-plus 仓库。业务方通过 git 依赖安装。
工程根目录提供:
update-and-start.ps1 / update-and-start.cmd(Win)node_modules/.vite、node_modules/sapit-ui-plus 及各种锁文件(package-lock.json/yarn.lock/pnpm-lock.yaml/node_modules/.package-lock.json);③ npm install。npm run dev。-SkipBuild(跳过构建)、-CleanCache(额外清 npm 缓存)。注意:锁文件会把 git 依赖钉在旧 commit,脚本每次都会删除;手动更新时也要删,否则
npm install装回旧包。
{
"dependencies": {
"sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git"
}
}
地址用单斜杠(
...:6010/sapit/...);双斜杠会报repository not found。
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)
// app-config 为构建期配置(含组件/函数),与 web-config 合并后交给基座
await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)
app.mount('#app')
}
init()
config:环境配置(见 4.3);appConfig:登录/首页覆盖、静态路由、语言包(见 4.5/4.6/4.8),不进入 config.json;pages:业务所有页面,用于动态路由按 hrefs 匹配组件。基座默认 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;VITE_APP_THEME(主题定义)只由基座提供,业务只写 VITE_APP_THEME_VALUE。应用启动时自动请求 ${VITE_APP_BASE_URL}config.json(3 秒超时,失败静默回退),命中后覆盖前述配置。适合运维按环境调整且无需重新打包。请求失败不影响启动。
在 src/config/app-config.js:
export default {
components: {
login: () => import('@/views/login/index.vue'),
home: () => import('@/views/home/index.vue')
}
}
pages-components/login.vue)与基座首页(pages-components/todo.vue);staticRoutes不依赖后端菜单的前端页面,在 app-config.js 配置:
export default {
staticRoutes: [
{
path: '/help',
name: 'Help',
component: () => import('@/views/help/index.vue'),
meta: { title: '帮助' } // hidden: true 不在菜单显示;public: true 免登录
}
]
}
可选字段:
meta.title:菜单名(不填用 name);meta.hidden:不在侧边菜单显示;meta.public:免登录、无权限(守卫直接放行);layout: false 或 raw: true:不包 BasicLayout(页面自带布局时用,如 /docs);path 时,业务的配置覆盖基座内置。hrefs 需能匹配到业务 views 的路径(或组件名),匹配到即用业务页面渲染,匹配不到回退 404;src/views/**,通过 pages 传入即可被动态路由识别;staticRoutes」;基座常量菜单(工作台/待办/消息)默认不进入侧边菜单。$l('添加', 'layouts.add')、$l('点击上传', 'components.upload');this.$l(...)、全局 $l(...)、this.$i18n.global.t(...) 均可;app-config.js 传 locales(深合并),用法 $l('标题','custom.title');*-i18n.js 不会被基座聚合(聚合发生在基座构建时),如需模块化聚合,业务可在入口自行 import.meta.glob 后作为 locales 传入。.env 里 VITE_APP_THEME_VALUE=blue|green|orange;var(--s-color)、var(--s-bg-color) 等,或直接用 .s-theme-bg 等工具类;VITE_APP_THEME)只在基座改;业务/config.json 传入的会被忽略。/monitor/).env(及对应环境文件):
VITE_APP_BASE_URL=/monitor/
vite.config.js 的资源前缀自动取该值:
js
base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'
基座路由 history base、$push/$open、redirectLogin、parseAppUrl 都会读取 VITE_APP_BASE_URL,自动带上 /monitor/;
nginx(站点目录示例 /home/project/tmp/dist):
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";
}
http://<服务器>:<port>/monitor/;前端路由(如 /monitor/docs)刷新靠 try_files 回退。要点:
createWebHistory的 base、Vite 的base、window.location跳转三者必须都用/monitor/,否则资源或跳转 404。
<template>
<s-list-layout :columns="columns" :loadData="page" title="示例" />
<s-user-select v-model:value="ids" />
<a-button v-action="'add'">添加</a-button>
<span class="s-theme-color">{{ $l('添加') }}</span>
</template>
export default {
mounted() {
this.$message.success('ok')
this.$utils.http({ url: '/xxx' })
this.$filter.dateFormat(Date.now())
this.$push('/detail', { id: 1 }) // 自动拼接 base
}
}
后端下发 permissions 后,基座写入 permission,模板用 v-action:xxx 控制按钮级权限。
以下为高频踩坑点,务必注意。
sapit-ui-plus 的 lib,基座改动必须 npm run build 推送并在业务重新安装依赖后才生效;基座自身 npm run dev 立即生效。package-lock.json、yarn.lock、node_modules/.package-lock.json,否则 npm install 装回旧包。...:6010/sapit/sapit-ui-plus.git。VITE_APP_BASE_URL 与 Vite base 必须一致(如 /monitor/),且带尾斜杠。web-config + .env*;部署后改它可覆盖;.env 值为字符串,布尔已在基座归一。.jsx 组件(如 Table)需手动引入。$l('中文','English') 或业务 locales。VITE_APP_THEME_VALUE;定义在基座。组件取色用 var(--s-*)/.s-theme-*,antd 由 a-config-provider token 驱动。| 调用 | 作用 |
|---|---|
$l('中文'[, key]) |
国际化 |
$push(path, query) / $open(path, query) |
跳转 / 新窗口(自动拼 base) |
$message.* / $modal.* / $notice.* |
轻提示 / 弹窗 / 通知 |
this.$utils.ls.get/set/clear |
本地存储 |
this.$utils.http(config) |
发起请求 |
$filter.dateFormat(v, fmt) |
日期格式化 |
v-action:code |
按钮级权限 |
var(--s-color) / .s-theme-color |
主题色(CSS 变量 / 工具类) |
$staticRoutes |
当前静态页面路由 |