# sapit-ui 基座说明与业务使用文档
> 适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、mode(业务示例)
>
> 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。
---
## 目录
- [一、总览](#一总览)
- [二、基座提供的内容](#二基座提供的内容)
- [三、构建与配置](#三构建与配置)
- [四、业务项目接入](#四业务项目接入)
- [五、注意事项](#五注意事项)
- [六、常见全局方法速查](#六常见全局方法速查)
---
## 一、总览
### 1.1 三者关系
| 工程 | 角色 | 说明 |
| -------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
| `sapit-ui-framework` | 基座(源码) | 内置组件与常用依赖的库工程,Vite lib 模式打包 |
| `sapit-ui-plus` | 发布产物 | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) |
| `mode` | 业务使用者 | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 |
```text
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> mode
```
### 1.2 目录结构(基座)
```text
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
```
---
## 二、基座提供的内容
### 2.1 全局组件
`packages/index.js` 用 `import.meta.glob('./components/**/*.vue')` 把 `components/**/*.vue` **按文件名全局注册**,模板直接以文件名标签使用(如 ``、``)。
| 分类 | 组件 |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 布局类 | `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`。
### 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, 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 封装 |
### 2.3 布局
`packages/layouts/index.js`:`BasicLayout`(头部+侧边菜单+内容区)、`BlankLayout`、`UserLayout`(登录)、`RouteView`、`PageView`。
### 2.4 路由
**常量路由**(`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 单点)。
### 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) 原样 |
| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等 |
`v-action:xxx` 按钮级权限指令:`添加`。
### 2.7 国际化
语言包构建时聚合 `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`)。
```html
{{ $l('添加') }} {{ $l('账户密码登录', 'account password') }}
```
> `key` 为路径时需先在对应 `*-i18n.js` 定义,否则原样显示该 key。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`:`--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`。
3. **body 类**:`theme-`(如 `theme-blue`)。
```css
.my-box {
color: var(--s-color);
background: var(--s-bg-color);
}
```
> 新增主题:基座 `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-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.\* 等已内置。
### 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`。
---
## 三、构建与配置
### 3.1 构建与发布
```bash
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"]`。
### 3.2 配置来源与优先级
```text
基座默认 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`:站点根(子路径为 `config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `"true"/"false"` 归一为布尔。
### 3.3 业务项目启动(`npm start`)
业务项目(`mode`)的 `npm start` 执行内置脚本 `refresh-mode.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-mode.cmd`;`-NoStart` 仅更新不启动。
> 这个命令通常在基座项目有更新时才会用到。
## 四、业务项目接入
### 4.1 安装
```json
{ "dependencies": { "sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git" } }
```
> 地址用**单斜杠**;双斜杠会 `repository not found`。
### 4.2 入口 `main.js`
```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`:
```js
export default {
components: {
login: () => import('@/views/login/index.vue'),
home: () => import('@/views/home/index.vue')
}
}
```
不配置则用基座默认(`pages-components/login.vue`、`todo.vue`)。
### 4.4 静态页面 `staticRoutes`
```js
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 国际化 / 主题
- 国际化:继承基座语言包,直接用 `$l('中文','English')` 或基座 key;扩展在 `appConfig` 传 `locales`(深合并)。业务自身 `*-i18n.js` 不会被基座聚合。
- 主题:只改 `VITE_APP_THEME_VALUE`;样式用 `var(--s-*)` 或 `.s-theme-*`。
### 4.7 子路径部署(示例 `/monitor/`)
1. `.env`:`VITE_APP_BASE_URL=/monitor/`;
2. 业务 `vite.config.js`:`base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'`;
3. 基座路由 base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 均读该值自动带前缀;
4. nginx:
```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.8 使用组件与权限
```html
添加
```
后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。
---
## 五、注意事项
1. 依赖是预构建产物:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。
2. 锁文件会钉住旧提交:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。
3. 子路径:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。
4. 全局组件命名:按文件名注册,冲突后者覆盖;`.jsx`(如 `Table`)需手动引入。
5. 主题 / 国际化:定义在基座,业务只选主题、只写文案。
---
## 六、常见全局方法速查
| 调用 | 作用 |
| ------------------------------------------- | ---------------------------- |
| `$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 变量 / 工具类) |