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

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 依赖为底层,编写业务页面/配置
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> mode

1.2 目录结构(基座)

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 按文件名全局注册,模板直接以文件名标签使用(如 <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。

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 按钮级权限指令:<a-button v-action="'add'">添加</a-button>。

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)。

<span>{{ $l('添加') }}</span> <span>{{ $l('账户密码登录', 'account password') }}</span>

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-<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-*) 自动跟随。

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 构建与发布

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 配置来源与优先级

基座默认 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" 归一为布尔。

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 安装

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

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)
  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:

export default {
  components: {
    login: () => import('@/views/login/index.vue'),
    home: () => import('@/views/home/index.vue')
  }
}

不配置则用基座默认(pages-components/login.vue、todo.vue)。

4.4 静态页面 staticRoutes

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:
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 使用组件与权限

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


五、注意事项

  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 变量 / 工具类)