sapit-ui-基座说明与业务使用.md 25 KB

sapit-ui 基座说明与业务使用文档

适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、mode(业务示例)

本文档同时是基座内置文档页 /docs 的数据源(packages/pages-components/docs.vue 在构建时用 ?raw 内联本文件并渲染成 HTML)。


目录


一、总览

1.1 三者关系

工程 角色 说明
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 安装依赖

1.2 目录结构(基座)

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

二、基座提供的内容

2.1 全局组件

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。

2.2 全局属性 / 方法

在 $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 图标集合

2.3 布局

packages/layouts/index.js 导出:BasicLayout(含头部/侧边菜单/内容区)、BlankLayout、UserLayout(登录,渲染 <router-view/>)、RouteView(二级内容区)、PageView(面包屑 + 内容区)。

2.4 路由

常量路由(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/权限;
  • 每次导航实时读取 token,避免快照失效;
  • 未登录仅放行登录页,其余跳登录;
  • 已登录访问登录页/根路径跳默认首页;
  • 拉取用户信息失败时清理并回登录页,避免守卫 pending 卡死;
  • 常量路由支持业务覆盖登录页/首页(见 4.5)。

2.5 状态管理(pinia)

packages/store/user.js(useUserStore):

  • state:user、menus、permissions、clients、dynamicRouter、menuOpenKeys
  • getters:dynamics(= dynamicRouter)、openKeys
  • actions:Info()(拉取用户信息/菜单/权限并写入 localStorage)、setDynamicRouter()、setMenuOpenKeys()
  • 开启持久化(localStorage)

2.6 工具类($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>

2.7 国际化

  • 语言包聚合:构建时扫描并合并
    • /packages/pages-components/*-i18n.js
    • /packages/components/*-i18n.js
    • /packages/layouts/*-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)
  • 基座已完成常用文案的兜底字典,业务 无需处理 即可切换英文。
  • antd 组件自身的国际化由 a-config-provider 的 locale 控制(BasicLayout/App.vue)。
<span>{{ $l('添加') }}</span>
<!-- 中文:添加 / 英文:Add -->
<span>{{ $l('账户密码登录', 'account password') }}</span>

提示:第二个参数若是 key 路径(如 page-components.xxx),必须先在对应 *-i18n.js 里定义;否则会原样显示该 key 字符串。直接写英文字面量则无需定义。

2.8 主题

主题分为两套并用,颜色定义只由基座维护:

  • 定义(基座):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 会被忽略。

生效方式:

  1. antd 组件:由 a-config-provider 的 token(colorPrimary/colorLink)驱动,来源为选中主题的 color。
  2. CSS 变量 + class:启动时自动把选中主题写入 :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); }
  1. body 主题类: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。

2.9 API(packages/api)

文件 内容
login.js login、info、getCode、verify、rsaPublicKey、验证码/短信/登录配置等
common.js 组织树、字典分页、用户/岗位按 id 查询、文件预览地址等
upload.js 上传/下载/在线预览
workbench.js 工作台示例分页/导出/导入等

2.10 页面组件(packages/pages-components)

login.vue、login-common/LoginForm.vue、workbench.vue、todo.vue、message.vue、403.vue、404.vue、500.vue、docs.vue。

2.11 内置文档(HTML)

基座内置了一个文档页,数据源就是本文件 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。

2.12 其它

  • 静态资源: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。
  • 第三方依赖(基座内置,业务无需重复安装):ant-design-vue、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.* 等。

三、构建与发布

3.1 构建

npm run dev      # 本地开发(基座自身调试壳)
npm run build    # 生产构建 + 复制产物 + 推送 git
npm run lint     # eslint

基座构建 不 drop console,因为 $utils、i18n 等调试输出由运行时 VITE_CONFIG_MODE 控制;若构建期 drop,会把业务 dev 需要的输出一起删掉。业务侧构建才 drop console。

3.2 构建产物(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"]。

3.3 config.json(运行时配置)

  • 业务构建时由 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" 被当成真值。

3.4 发布

npm run build 会依次执行:vite build → 复制 package.json/docs/vite-plugins 到 dist/ → 在 dist/ 内 git init/add/commit → git push -f 到 sapit-ui-plus 仓库。业务方通过 git 依赖安装。

3.5 一键更新脚本

工程根目录提供:

  • 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 装回旧包。


四、业务项目接入

4.1 安装

{
  "dependencies": {
    "sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git"
  }
}

地址用单斜杠(...:6010/sapit/...);双斜杠会报 repository not found。

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)
  // 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 匹配组件。

4.3 配置来源与优先级

基座默认 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。

4.4 运行时配置 config.json

应用启动时自动请求 ${VITE_APP_BASE_URL}config.json(3 秒超时,失败静默回退),命中后覆盖前述配置。适合运维按环境调整且无需重新打包。请求失败不影响启动。

4.5 自定义登录页 / 首页

在 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);
  • 配置了就用自己的,不配置则用基座默认。

4.6 静态页面 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 时,业务的配置覆盖基座内置。

4.7 业务页面与菜单(动态路由)

  • 后端菜单的 hrefs 需能匹配到业务 views 的路径(或组件名),匹配到即用业务页面渲染,匹配不到回退 404;
  • 页面组件放在 src/views/**,通过 pages 传入即可被动态路由识别;
  • 侧边菜单渲染「后端菜单生成的动态路由 + staticRoutes」;基座常量菜单(工作台/待办/消息)默认不进入侧边菜单。

4.8 国际化

  • 继承:基座语言包随依赖提供,业务可直接用基座 key,例如 $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 传入。

4.9 主题

  • 业务 只需选主题:.env 里 VITE_APP_THEME_VALUE=blue|green|orange;
  • 自定义样式用 var(--s-color)、var(--s-bg-color) 等,或直接用 .s-theme-bg 等工具类;
  • 主题定义(VITE_APP_THEME)只在基座改;业务/config.json 传入的会被忽略。

4.10 子路径部署(示例 /monitor/)

  1. .env(及对应环境文件):

    VITE_APP_BASE_URL=/monitor/
    
    1. 业务 vite.config.js 的资源前缀自动取该值: js base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'
  2. 基座路由 history base、$push/$open、redirectLogin、parseAppUrl 都会读取 VITE_APP_BASE_URL,自动带上 /monitor/;

  3. 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";
    }
    
    1. 访问 http://<服务器>:<port>/monitor/;前端路由(如 /monitor/docs)刷新靠 try_files 回退。

    要点:createWebHistory 的 base、Vite 的 base、window.location 跳转三者必须都用 /monitor/,否则资源或跳转 404。

    4.11 使用基座组件与全局方法

    <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
  }
}

4.12 权限

后端下发 permissions 后,基座写入 permission,模板用 v-action:xxx 控制按钮级权限。


五、注意事项

以下为高频踩坑点,务必注意。

  1. 依赖是预构建产物:业务使用的是 sapit-ui-plus 的 lib,基座改动必须 npm run build 推送并在业务重新安装依赖后才生效;基座自身 npm run dev 立即生效。
  2. 锁文件会钉住旧提交:更新依赖前删掉 package-lock.json、yarn.lock、node_modules/.package-lock.json,否则 npm install 装回旧包。
  3. git 依赖地址用单斜杠:...:6010/sapit/sapit-ui-plus.git。
  4. 路由刷新:通配路由不使用 redirect,守卫在注册动态路由后重新导航,保证刷新动态地址不掉 404。
  5. 子路径部署:VITE_APP_BASE_URL 与 Vite base 必须一致(如 /monitor/),且带尾斜杠。
  6. 运行时 config.json:来源是 web-config + .env*;部署后改它可覆盖;.env 值为字符串,布尔已在基座归一。
  7. 全局组件命名:按文件名注册,命名冲突时后者覆盖;.jsx 组件(如 Table)需手动引入。
  8. 国际化:基座已内置中文→英文兜底字典,常规文案无需业务处理;新增文案建议用 $l('中文','English') 或业务 locales。
  9. 主题:只改 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 当前静态页面路由