# 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" } } ``` ### 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 变量 / 工具类) |