# sapit-ui 基座说明与业务使用文档 > 适用工程:sapit-ui-framework(基座/源码)、sapit-ui-plus(发布产物)、sapit-base-template(业务示例) > > 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。 --- ## 目录 - [一、总览](#docs-一总览) - [二、基座提供的内容](#docs-二基座提供的内容) - [三、布局与高度规范](#docs-三布局与高度规范) - [四、构建与配置](#docs-四构建与配置) - [五、业务项目接入](#docs-五业务项目接入) - [六、注意事项](#docs-六注意事项) - [七、常见全局方法速查](#docs-七常见全局方法速查) - [八、在线文档入口](#docs-八在线文档入口) --- ## 一、总览 ### 1.1 五者关系 | 工程 | 角色 | 说明 | | --------------------- | ----------------------------------------------- | ----------------------------------------------------------------- | | `sapit-ui-framework` | 基座(源码) | 内置组件与常用依赖的库工程,Vite lib 模式打包 | | `sapit-ui-plus` | 发布产物 | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) | | `sapit-base-template` | 业务使用者 | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 | ```text sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template ``` ### 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` **按文件名全局注册**,模板直接以文件名标签使用(如 ``、``)。 | 分类 | 组件 | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 布局类 | `SSkeletonLayout`(骨架布局:标题 + 按钮组 + 内容区,见 2.16)、`SListLayout`、`SListCardLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` | | 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`、`SImportModal`(批量导入,见 2.11) | | 表单/筛选 | `SForm`、`SFormItem`、`SExtendFieldsForm`/`SExtendFieldsFormItem`(动态扩展字段)、`SFilterWrap`、`SFilterItem`、`SCascader`、`STree`、`STreeSelect`、`SDataRangeTreeSelect`(数据权限范围树)、`SUserSelect`、`SUserSelectButton`、`SChooseUser`(带数据权限选人弹窗,见 2.14)、`SBelowChoosePosition`(选岗位弹窗,见 2.15)、`SOfficeSelect`、`SIconSelect`(图标选择) | | 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` | | 展示/其它 | `SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SColorPicker`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、`SSideMenu`/`STopMenu` | > 组件用法见内置组件页 **`/components`**(含「s组件」「工具/配置」两个标签页;「工具/配置」列出 web-config 全部配置项与 `$utils` 全部方法)。 > > 注册规则:`components/**/*.vue` 按**文件名**全局注册(`SForm.vue` → ``,**不是 kebab-case**),冲突后者覆盖。 > `Table/index.jsx` 是 `.jsx`、`import.meta.glob` 匹配不到,基座在`packages/index.js` 里**单独注册为全局 `STable`**(`` 可直接用,无需 import)。 > `@ant-design/icons-vue` 图标全部全局注册并挂到 `$icons`。 > 另有内部辅助组件不对外使用:`ModalHeader`(SModal)、`CropperModal`(SCopperUpload)、`CustomInput`/`SettingColumns`/`SettingFilter`(SSuperListLayout)。 ### 2.1.1 布局组件选择 | 场景 | 用哪个 | | ------------------------- | -------------------------------------------------------------------------------------------- | | 标题 + 按钮 + 自定义内容(无表格/分页/表单) | `SSkeletonLayout`(见 2.16,自带标题条与权限按钮) | | 普通列表页 | `SListLayout` | | 卡片列表 | `SListCardLayout` | | 列表 + 左侧树 | `SListTableTreeLayout`(左侧树容器类名必须是 `.side.s-side-tree`,见 3.5) | | 带高级搜索/高级表格的列表 | `SSuperListLayout` | | 新增/编辑/详情(路由式) | `SFormLayout`(`#form` 插槽放 `SForm`,`#footer-callback` 收 `save`/`cancel`/`prev`/`next`) | | 表单作为弹窗内容 | `SModal`(不要套 `SFormLayout`) | | 后端下发字段的动态表单 | `SExtendFieldsForm`(`data` + `defaultValue`,ref 调 `validate/clearValidate/getModel`) | | 数据权限范围选择 | `SDataRangeTreeSelect`(`autoSysConfig` 托管系统 `dataScope` 配置) | ### 2.2 全局属性 / 方法 `$registerGlobalConfig` 执行后可用(`this.$xxx` / 模板 `$xxx` / `window.$xxx`): | 名称 | 说明 | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `$registerGlobalConfig(config, pages)` | 初始化入口(见 5.2) | | `$utils` | 工具类集合:`$utils.env` / `$utils.ls` / `$utils.http` 及通用方法 | | `env` | 合并后的环境配置(= `$utils.env`) | | `$i18n` / `$l(name, key)` | 国际化(见 2.7)。挂在 `globalProperties` 上:**模板里直接用** `$l('xx')`;` ``` | props | 类型 | 默认值 | 说明 | | ------------ | --------------- | ---------------- | ----------------------------------------------------------- | | `value` | Boolean | `false` | 显隐(`v-model:value`) | | `title` | String | `'批量导入'` | 弹窗标题 | | `width` | String / Number | `1000` | 弹窗宽度 | | `uploadUrl` | String | `''` | 上传地址(完整网关地址,如 `/monitor/DeviceInfo/Uploader`) | | `columns` | Array | `[]` | 预览/结果表格列 `[{ title, dataIndex, width }]` | | `apis` | Object | `{}` | 四个导入接口(见下) | | `typeSelect` | Object | `null` | `{ options, placeholder, loading }`,不需要业务参数时不传 | | `extraKey` | String | `'deviceTypeId'` | `typeSelect` 选中值提交时的字段名 | | events | 说明 | | -------------- | --------------------------- | | `update:value` | 显隐变化(`v-model`) | | `reload` | 导入成功/关闭后需要刷新列表 | | methods(ref 调用) | 说明 | | ------------------- | ------------------ | | `show()` | 打开弹窗并重置状态 | 接口约定(均返回 Promise,组件内部兼容 `{ code, data }` 与直接返回数据两种格式): | 接口 | 入参 | 返回 | | --------------------- | ------------------------------ | ---------------------------------------------------- | | `templateDownload` | `{ ...extraParams }` | `{ url }`(组件用 `url` 触发下载) | | `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` | | `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` | | `exportExceptionData` | `{ list, ...extra }` | `{ url }` | | 上传(内部) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }`(后续接口回传 fileName) | > ⚠️ `SImportModal` 是**三步式**(上传 → 预览编辑 → 结果/异常导出)。 > 业务项目里如果存在「选文件即导入」的**单步式**导入组件(如 hy-monitor 的 `views/people/components/ImportModal.vue`、`views/basicData/components/ImportModal.vue`), > 两者在布局、API、事件、调用页契约上都不同,**不能当同一个组件替换**,仍按各自实现保留。 ### 2.12 SDataRangeTreeSelect 数据权限范围树 数据权限(组织/校区/单位)范围选择,内部走 `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`。 ```vue ``` 常用 props:`value`(id 数组) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup`(`'1'`组织 `'2'`校区 `'3'`单位,可传数组)/ `showOnlyOrganization` / `treeSelectData`(传数组则不请求接口)/ `isDataScopeFilter` / `autoSysConfig` / `defaultValue`。 events:`update:value`、`change`(均输出 **id 数组**)。 > ⚠️ 模板写死了 `label-in-value` + `tree-check-strictly`,antd 要求内部 `value` 必须是 `{ label, value }` 对象数组。 > 因此**回显必须先 `getOfficeByIds(ids)` 转成节点对象**再赋值,直接赋裸 id 字符串会触发 `Invalid prop value` 警告且输入框显示成裸数字 ID。 ### 2.13 SExtendFieldsForm 动态扩展字段表单 后端下发字段配置(`fillModeConfig` 为 JSON 串,含 `showType` / `config`),前端按配置渲染。 ```vue ``` | props | 类型 | 默认值 | 说明 | | -------------- | ------ | ------- | ---------------------------------------------------- | | `data` | Array | `[]` | 扩展字段定义(`fieldCode/fieldName/fillModeConfig`) | | `type` | String | `'add'` | `add` / `edit` / `view`(`view` 不校验) | | `defaultValue` | Array | `[]` | 编辑态回显值 `[ { fieldCode, value } ]` | | `cols` | Number | `2` | 每行列数(非整行字段按 `100/cols%` 宽) | | `labelWidth` | String | `auto'` | label 宽度 | 自动占满整行的 `showType`:`textarea`、`upload`、`select` 且 `config.multiple`。默认值按 `showType` 转类型:`datePicker` → dayjs 对象、`number` → Number、`select` 多选 → 逗号切数组。 ### 2.14 SChooseUser 选择人员弹窗(带数据权限) 弹窗式人员选择:左侧组织树 + 右侧人员列表(头像/姓名/工号 + 单位),搜索区内置**人员类型过滤**(全部/教职工/学生/校外人员),支持单选/多选、滚动分页加载、全选/反选、多选时右侧已选清单。确认后**自动关闭弹窗**。 与 `SUserSelect` 的差异(选型依据): | 对比项 | `SUserSelect` | `SChooseUser` | | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | 形态 | 只读输入框 + 弹窗一体 | 纯弹窗,显隐由业务控制 | | 数据权限 | 组织树/列表接口不带数据权限 | 走 `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`,**按登录人权限过滤** | | 人员类型 | 无过滤 | 内置教职工/学生/校外人员过滤 | | 取值契约 | `v-model:value` 直接绑 id(单选字符串/多选数组) | `v-model:value` 控显隐;`v-model:selectedIds`/`selectedId` 绑已选 id;`@callback` 回抛**选中对象列表** | ```vue ``` | props | 类型 | 默认值 | 说明 | | ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- | | `value` | Boolean | `false` | 弹窗显隐(`v-model:value`) | | `title` | String | `'选择人员'` | 弹窗标题 | | `multiple` | Boolean | `false` | 多选(右侧出现已选清单) | | `searchPlaceholder` | String | `'按姓名、工号/学号、手机号搜索'` | 搜索框占位 | | `required` | Boolean | `false` | 确认时未选则提示且不关闭 | | `selectedIds` | Array | `[]` | 多选回显 id 数组(`v-model:selectedIds`),内部 `getBUseryIds` 拉对象渲染已选 | | `selectedId` | String | `''` | 单选回显 id(`v-model:selectedId`),内部 `getUserById` 拉对象 | | events | 说明 | | -------------------- | ----------------------------------------------------- | | `update:value` | 关闭弹窗(确认/取消均自动置 `false`,业务无需手动关) | | `update:selectedIds` | 已选 id 数组双向绑定 | | `update:selectedId` | 单选 id | | `callback` | 确认回抛选中对象**数组**;关闭时无参 | > ⚠️ 接口全部内置在基座 `packages/api/common.js`(`findUsersWithAuth` = `/user/users/authorized` 等),业务无需传接口;无后端的预览环境树/列表为空属正常。列表中 `userid` 展示的是 `loginName`(工号/学号)。 ### 2.15 SBelowChoosePosition 选择岗位弹窗 弹窗式**岗位**选择(源自业务项目 `/components/BelowChoosePosition`,已收编进基座):左侧树用 `getBelowUnit` 一次性拉「根节点及其以下所有单位」的完整树(范围由 `rootId` 决定),右侧列表查岗位(`findJobs`),支持单选/多选。 与基座其它选择器的差异:`SOfficeSelect`/`SUserSelect` 查组织/人员且左树递归懒加载;本组件查**岗位**、左树一次性全量。**确认后不自动关闭弹窗**,业务需在 `callback` 中手动关闭(与源项目行为一致)。 ```vue ``` props 与 `SChooseUser` 相同(`title` 默认 `'选择岗位'`、`searchPlaceholder` 默认 `'按岗位名称、岗位编号搜索'`),另有一个专有 prop: | props | 类型 | 默认值 | 说明 | | -------- | ------ | ------ | --------------------------------------------------------------------- | | `rootId` | String | `''` | 左树根节点 id,决定树的数据范围;变化时自动重载左树,未传按 `'-1'` 查 | | methods(ref 调用) | 说明 | | ---------------------- | ------------------ | | `initLeftTreeData(id)` | 手动重载左侧组织树 | | events | 说明 | | -------------------- | ------------------------------------------------------------------- | | `update:value` | 仅取消时置 `false`;**确认不关窗**,业务手动关 | | `update:selectedIds` | 已选岗位 id 数组双向绑定(回显走 `getPositionByIds`) | | `update:selectedId` | 单选 id(回显走 `getPositionById`) | | `callback` | 确认回抛 `{ selectedList }` / `{ selected }` 对象;关闭回抛 `false` | > ⚠️ `callback` 载荷形态与 `SChooseUser` **不同**(对象 `{ selectedList }` vs 数组),且确认后关窗行为相反,两个组件的 callback 写法不可混用。 --- ### 2.16 SSkeletonLayout 骨架布局(标题 + 按钮组 + 内容区) > 2026-10-28 新增。用于页面级「标题条 + 操作按钮 + 内容区」的骨架外观,与 `SListLayout` / `SFormLayout` 同级但更轻:**不带表格、不带表单、不带分页**,内容区完全由插槽决定。 ```vue
...
``` | props | 类型 | 默认 | 说明 | | --------- | ------ | ---- | ------------------------------------------------------------- | | `title` | String | — | **必填**,标题条文本 | | `buttons` | Array | `[]` | 按钮配置数组,见下表 | | `bgColor` | String | `''` | 根节点背景色 | `buttons` 每项字段: | 字段 | 类型 | 说明 | | ---------- | ------------------ | ---------------------------------------------------------------------------------------- | | `key` | String | 唯一键,点击时回抛该值;`'add'` 时按钮自动为 `primary` | | `name` | String | 按钮文案(内部走 `$l`,可直接写源中文) | | `icon` | String \| Boolean | 字符串 = 图标组件名(如 `'PlusOutlined'`);`true` = 按 `key` 查内置 iconMap;缺省不出图标 | | `action` | String | `v-action` 权限码,缺省用 `key`(会真正做权限过滤,无权限时按钮被移除) | | `show` | Boolean | 默认 `true`;`false` 时 `v-show` 隐藏(仍占位、仍注册权限) | | `disabled` | Boolean | 置灰 | | `type` | String | 覆盖 `a-button` 的 `type` | | slots | 说明 | | ----------- | -------------------------------- | | 默认 | 内容区(`.skeleton-layout-main`) | | `otherBtns` | 按钮组右侧追加内容 | | `other` | 底部区域 | | events | 说明 | | ------------- | --------------------------- | | `btnCallback` | 回抛被点击按钮的 `key` | | methods(ref 调用) | 说明 | | ------------------- | ------------------------------------------------------------- | | — | **无**。高度由 flex 自动分配,不需要业务调任何方法(见下) | 内置 iconMap 的 key:`add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`。 > **高度实现(2026-10-28 修订)**:根节点 `height:100%; display:flex; flex-direction:column`,标题条 `flex:0 0 60px`,内容区 `flex:1 1 auto; min-height:0; overflow:hidden auto`,底部槽 `flex:0 0 auto`。**零 JS、零 resize 监听**,窗口缩放 / 侧栏折叠自动跟随。 > > 前提:父容器要有确定高度。基座 `BasicLayout` 的 `router-view` 已带 `:style="{ height: contentHeight + 'px' }"`,会透传到页面根组件,通常无需额外处理;若页面外层是自己写的 `height:auto` 容器,需给该容器一个确定高度。 > > 旧版本的 `initLayoutHeight()` 方法**已移除**,`layoutHeight` 也不再暴露(原实现是 `parentNode.offsetHeight - 76` 且只在 `mounted` 算一次)。 ### 2.17 错误页(301 / 403 / 404 / 500) 基座内置三张错误页,**同一张页面承接「页面本身出错」和「接口报错」两种来源**,靠 URL 上的 `?api=` 区分文案。 | 路径 | 组件 | 状态码来源 | 主色 | | --- | --- | --- | --- | | `/403` | `pages-components/403.vue` | 接口 403 无权限、接口 301 地址变更、页面无权限 | 橙色 `#fa8c16` | | `/404` | `pages-components/404.vue` | 路由没命中(通配 `/:pathMatch(.*)*`)、接口 404 | 主题色 `var(--s-color)` | | `/500` | `pages-components/500.vue` | 仅可直接访问;**接口 5xx 不跳转**,仍走通知 | 红色 `#f5222d` | **渲染位置**:`buildErrorRoute()` 把三页统一包在 `BasicLayout` 下,作为 `children: [{ path: '' }]` 的嵌套子路由——跳转时**只替换内容区 `router-view`**,侧边菜单、顶栏、页脚保持原样。页面 404(通配)与接口 404 共用同一套结构,表现完全一致。 **免登录**:`/403`、`/404`、`/500` 带 `meta.public`(接口报错时 token 可能已失效,不能让它再卡在登录守卫里);通配 `/:pathMatch(.*)*` **不带** `public`,未登录访问不存在的地址仍回登录页。 **接口报错的映射**(`packages/utils/request.js`): | HTTP 状态 | 行为 | 目标 URL | | --- | --- | --- | | 301 | 跳 403 页,文案「接口地址已变更」 | `/403?api=<接口>&status=301&from=<出错页>` | | 403 | 跳 403 页,文案「接口无权限」 | `/403?api=<接口>&status=403&from=<出错页>` | | 404 | 跳 404 页,文案「接口不存在」 | `/404?api=<接口>&status=404&from=<出错页>` | | 其它(含 5xx) | **不跳**,照旧弹通知 | — | **URL 参数**: | 参数 | 含义 | | --- | --- | | `api` | 报错接口地址。**有它即切「接口口径」文案**;页面自身出错时不带 | | `status` | 原始状态码;`301` 单独走「接口地址已变更」这一档文案 | | `from` | 出错来源页面地址(已剥掉 `VITE_APP_BASE_URL`),页面显示为「出错地址」 | 文案口径: | 来源 | 403 页 | 404 页 | | --- | --- | --- | | 页面(无 `api`) | 页面权限不足 | 页面走丢了 | | 接口(有 `api`) | 接口无权限 | 接口不存在 | | 接口 301 | 接口地址已变更 | — | 两个按钮:「返回首页」走 `VITE_APP_DEFAULT_PATH`(默认 `/workplace/index`);「返回上一页」用 `router.back()`,没有历史记录时自动退回首页,避免点了没反应。 **跳过跳转**(后台轮询、辅助接口等非主流程请求,避免一条辅助接口失败把整页顶掉): ```js // 第三个参数支持 { skipErrorPage: true }(也可写在请求 meta 里) window.$utils.http.post(url, data, { skipErrorPage: true }) ``` **并发与兜底**:错误页跳转是**串行排队、后到优先**,同时来 403 和 404 不会互相取消;导航结束后回读 `currentRoute` 校验是否真的到达(兼容目标被 redirect 改写路径),没到达重试 2 次,仍失败才 `location.replace` 整页兜底,保证用户一定看到错误页。已经在错误页且已带 `api` 时不再覆盖,防止错误页自身挂的辅助接口把真实原因顶掉。 **改颜色 / 改文案**: - 文案全部走 i18n 词条(`packages/pages-components/i18n.js`,命名空间 `pages-components`),改词条即改三页文字。 - 403 / 500 各自在根节点定义了 `--e-color`(主色)、`--e-light-color`(浅色)、`--e-border-color`(虚线边框),业务侧用同名变量覆盖即可换色;404 用主题色 `--s-color`,跟随 `VITE_APP_THEME_VALUE`。 - 三页根节点都是 `height:100%; overflow:hidden`,装饰光斑包在 `__deco` 里自裁,超出部分只在卡片内部滚动,不会撑出页面滚动条。 > 错误页挂在 `BasicLayout` 下,布局层会带发 `getSystemIcon` 与消息计数两个请求。这两个接口若是本身会失败的辅助接口,建议加 `skipErrorPage: true`,否则可能从 403 再跳到 404。 ### 2.18 菜单配色(侧边 / 顶部) 菜单颜色**不在样式里写死**:启动时由 `packages/utils/menu-theme.js` 按当前主题色算出整套色板,全部输出实色 `#rrggbb`(**不含 rgba / 透明度**),写入 `:root` 的 CSS 变量,同时挂到 `window.$menuTheme`。改主题色或改参数,四处底色一起变。 | 部位 | CSS 变量 | 计算方式 | | --- | --- | --- | | 一级菜单底 | `--s-menu-bg` | 主题色相 + 饱和度上限 + 指定亮度 | | 子菜单展开区 | `--s-menu-sub-bg` | 同色相,比一级底亮一档 | | 悬停项 | `--s-menu-hover-bg` | 同色相,比一级底暗 6 个亮度 | | 选中项 | `--s-menu-active-bg` | 主题色兑白,占比由 `VITE_APP_MENU_BG_ACTIVE_MIX` 控制 | | 普通文字 | `--s-menu-text` | 按底色反解,保证对比度 ≥ 4.6 | | 悬停 / 选中文字 | `--s-menu-text-hover`、`--s-menu-text-active` | 同上 | 配置项(默认值见 `packages/config/web-config.js`,业务 `.env` 或部署目录 `config.json` 可覆盖): | 配置 | 默认 | 说明 | | --- | --- | --- | | `VITE_APP_MENU_BG` | `theme` | `theme` 跟随主题色 / `dark` 用 antd `#001529` / `#RRGGBB` 直接用该色 | | `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 一级底亮度 0-100:越大越白,越小越深;**低于 50 自动切深色底 + 浅色文字** | | `VITE_APP_MENU_BG_SATURATION` | `30` | 饱和度上限 0-100:越小越接近灰白,`0` 得纯灰 | | `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 选中块里主题色的占比 0-100:越大越显眼 | | `VITE_APP_MENU_THEME` | `dark` | 菜单外观模式;文字色实际按**底色明暗**自动切换,不只依赖这个值 | | `VITE_APP_MENU_BAR` | `left` | `left` 侧边 / `top` 顶部,两者共用同一套色板 | **单项颜色覆盖**(不想让部分颜色继续推导时用;留空即按主题色推导,与 `VITE_APP_MENU_BG` 取什么值无关,`theme` / `dark` / 自定义色三种来源都生效): | 配置 | 默认 | 覆盖的部位 | 对应 CSS 变量 | | --- | --- | --- | --- | | `VITE_APP_MENU_SUB_BG` | 空 | 子菜单展开区底色 | `--s-menu-sub-bg` | | `VITE_APP_MENU_HOVER_BG` | 空 | 悬停项底色 | `--s-menu-hover-bg` | | `VITE_APP_MENU_ACTIVE_BG` | 空 | 选中块底色 | `--s-menu-active-bg` | | `VITE_APP_MENU_TEXT` | 空 | 普通文字 | `--s-menu-text` | | `VITE_APP_MENU_TEXT_HOVER` | 空 | 悬停文字 | `--s-menu-text-hover` | | `VITE_APP_MENU_TEXT_ACTIVE` | 空 | 选中文字 | `--s-menu-text-active`、`--s-menu-active-text` | | `VITE_APP_MENU_GROUP_TITLE` | 空 | 分组标题文字 | 返回结果 `groupTitle` | - 取值支持 `#RGB` / `#RRGGBB` / `rgb()` / `rgba()`,内部统一归一成实色 `#rrggbb`(传 `rgba` 会**丢掉透明度**,保持整套配色无 alpha)。 - 非法值打一条 `[menu] VITE_APP_MENU_XXX ...` 告警后忽略该项,其余项照常生效,不会因为一个手滑的颜色把整套菜单弄崩。 - 覆盖项在 token / CSS 变量生成**之前**生效,所以 antd `Menu` token、`:root` 变量、组件里读到的值全部是覆盖后的最终值。 各主题默认色(亮度 93 / 饱和 30 / 选中 16,均为实测值): | 主题 | 一级底 | 子菜单底 | 悬停 | 选中块 | 普通文字 | | --- | --- | --- | --- | --- | --- | | blue | `#e8ecf3` | `#f5f7fa` | `#d4dce8` | `#dae9ff` | `#344051` | | green | `#ebf3e8` | `#f7faf5` | `#dbe8d4` | `#e3f6da` | `#3d5134` | | orange | `#f3ede8` | `#faf7f5` | `#e8ded4` | `#feedda` | `#514334` | | red | `#f3e8e8` | `#faf5f5` | `#e8d4d5` | `#fddcdd` | `#513435` | | purple | `#ece8f3` | `#f7f5fa` | `#dcd4e8` | `#e8def8` | `#403451` | | cyan | `#e8f3f3` | `#f5fafa` | `#d4e8e8` | `#d9f5f5` | `#345151` | 常用调法: ```js // 业务 web-config.js / 部署目录 config.json VITE_APP_MENU_BG_LIGHTNESS: 97, // 1) 想更白(100 接近纯白) VITE_APP_MENU_BG_SATURATION: 0, // 2) 去掉色调,走纯灰白 VITE_APP_MENU_BG_ACTIVE_MIX: 30, // 3) 选中块更明显 VITE_APP_MENU_BG: 'dark', // 4) 回到 antd 经典深蓝黑 #001529 VITE_APP_MENU_BG: '#213045' // 5) 固定一个自定义色,不再跟随主题 // 6) 自定义底色 + 全套自定义配色:不想推导的项直接给色值 VITE_APP_MENU_BG: '#213045', VITE_APP_MENU_SUB_BG: '#1b2637', VITE_APP_MENU_HOVER_BG: '#2a3b52', VITE_APP_MENU_ACTIVE_BG: '#2b6cd4', VITE_APP_MENU_TEXT: '#c9d4e2', VITE_APP_MENU_TEXT_HOVER: '#ffffff', VITE_APP_MENU_TEXT_ACTIVE: '#ffffff', VITE_APP_MENU_GROUP_TITLE: '#8fa3bd' ``` > 只给其中一两项也行(例如只改 `VITE_APP_MENU_TEXT`,其余继续推导);留空串 / 不写 / 写非法值都视为「不覆盖」。 > 注意事项 > > 1. `VITE_APP_MENU_BG` 传 `#RRGGBB` 时,子菜单底 / 悬停 / 选中 / 文字仍在该色基础上推导,不会出现「主底换了、文字看不清」;不满意推导结果就用上面 7 个 `VITE_APP_MENU_XXX` 单项覆盖,覆盖项优先级最高。 > 2. 底色亮度 < 50 进入深色体系:文字转浅、logo 自动换浅色版、顶栏文字转白。判据是 `window.$menuTheme.isLightBg`,不是 `VITE_APP_MENU_THEME`。 > 3. 业务样式不要写死 `#001529`、`rgba(255,255,255,.1)` 这类菜单色,直接用 `var(--s-menu-*)`,否则换主题会割裂。 > 4. `.menu-wrap .ant-menu.ant-menu-dark` 已用上述变量兜住一级项、子菜单、hover、选中四类节点(antd 4.2.6 的 Menu token 覆盖不到的部分)。 ## 三、布局与高度规范 > 本章是**基座内部布局组件的强制约定**。业务页面只管用 layout,不要自己写高度;如果要新增布局组件,必须先满足本章规则。 ### 3.1 高度:优先 CSS flex 撑满;需要动态计算时按三条约束做 > **2026-10-28 修订**:旧标题「禁止 JS 减法算高度」已作废。业务内容区需要出滚动条时,**高度就该动态计算**,只是必须按下面的约束写,不能每页抄魔数。 **错误做法**(早期 `SListLayout` / `SFormLayout` 都犯过): ```js // ❌ 用 offsetHeight 减法算子区域高度 this.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16 ``` 为什么必错:`offsetHeight` 读的是**当前渲染结果**,而这个结果又取决于你即将写入的 `height` —— 循环依赖。表现是: - 数据不满页时分页浮在中间,底部空 15~588px; - 表格/表单区溢出容器 1~N px,页面多出一条滚动条; - 改一个固定魔数(如 `tpH = 103`)其它页面全歪。 **首选做法(零 JS)**:父容器 `height:100%` + `display:flex; flex-direction:column`,主体区 `flex:1 1 auto; min-height:0; overflow:auto`,底部条 `flex:0 0 auto`。列表页、表单页绝大多数场景用这个就够。 **需要 JS 动态计算的情形**(内容区要出滚动条、容器高度随窗口或兄弟节点变化):**允许并推荐动态计算**,但必须满足三条: 1. **收敛到一处**:同一种布局只留一个 `calcXxxHeight()`,不要每页一份魔数 2. **跟着容器走**:用 `ResizeObserver` 观察父容器重算,别只监听 `window.resize` 3. **不读 `$parent.$el`**:父级 DOM 结构一变就错,用 `ref` 取自己的容器 **仍然禁止的错法**:拿「自己即将写入 height 的那个祖先」的 `offsetHeight` 做减法 —— 循环依赖。要读就读**不依赖自身高度**的量(`window.innerHeight`、上级固定头/脚节点的高度)。 ### 3.2 表格区撑满链路(列表页分页贴底的关键) `STable` 的 body 要靠 flex 拿到剩余高度,链路上**任何一层漏掉都会导致撑不开**: ```less .table-content { flex: 1; display: flex; flex-direction: column; min-height: 0; } .tabs-wrap { flex: 0 0 auto; } .table-container { flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; } .table-wrapper { flex: 1 1 auto; ...; } /* STable 组件根节点,漏它整条链断 */ .ant-table-wrapper { flex: 1 1 auto; ...; } .ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container { margin-left: 10px; } /* 表格缩进走 margin,不走 padding */ .ant-table-header { flex: 0 0 auto; } .ant-table-body { flex: 1 1 auto; min-height: 0; max-height: none !important; } .ant-table-pagination { margin-bottom: 0; flex: 0 0 auto; } /* 差一个 margin 就是 15~16px 空隙 */ ``` 要点: 1. **`.table-wrapper` 不能漏** —— 它是 `STable` 组件根节点,实测漏掉它 body 就撑不开; 2. `scroll.y` 写入的 `max-height` 必须 `none !important` 覆盖掉,否则和 flex 打架; 3. 分页 `margin-bottom: 0`,否则分页与容器底边恒差一个 margin; 4. 表格缩进用 `:deep(.ant-table-container){margin-left:10px}`,**不要**用 `padding-left`(会挤压 body 宽度计算)。 ### 3.3 `.tools` 头部条统一 60px 所有布局的 `.tools`(标题 + 按钮条)统一: ```less .tools { height: 60px; display: flex; justify-content: space-between; align-items: center; padding: 0 16px; box-sizing: border-box; border-bottom: 1px solid #f0f2f5; } .list-filter-wrap { padding: 10px 16px; box-sizing: border-box; } ``` > ⚠️ 若某天调整了 `.tools` 高度,所有布局里 `initTable()` 的减数(如 `- 76`)必须同步改,否则全站列表页一起歪。 ### 3.4 表单布局 SFormLayout `.form-layout` 用同一套 flex 撑满,`initStyle()` 里**只算 footer 宽度**(collapses + anchor 场景要避开右侧锚点),不再算高度: ```less .form-layout { height: 100%; overflow: hidden; :deep(.ant-spin-nested-loading), :deep(.ant-spin-container) { /* a-spin 包裹层必须逐层撑满,否则 form-layout 高度取不到 */ height: 100%; display: flex; flex-direction: column; min-height: 0; } } .tools, .step-wrap, .tabs-wrap, .modal, .form-fixed-footer { flex: 0 0 auto; } .form-layout-main { flex: 1 1 auto; min-height: 0; overflow: hidden auto; } .form-fixed-footer { height: 60px; } ``` ### 3.5 左侧树容器高度统一(`.s-side-tree`) `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` 的 `.side` 都带 `padding: 10px 0`,树容器高度必须等于「`.side` 盒高 − 上下 padding」,否则双滚动条或树被截断。 规则写在**全局** `packages/style/tree.less` 的 `.s-side-tree`(`.side` 的唯一化追加类,避免通用名被业务覆盖),业务页面 scoped 里**禁止再写副本**。覆盖两种树来源: - ① 标准 ``:根节点即 `.s-tree-common`,`height:100%`; - ② 原生 ``:逐层撑高 `.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder`,由 `.ant-tree-list-holder` 承担 `overflow-y:auto`。 > ⚠️ ② 的分支必须用 `>` 从 `.s-side-tree` 直接起算,**不能写成后代选择器** —— `STree` 内部同样是 `.ant-tree`,后代写法会误伤 ①。 ### 3.6 STree 自适应与横向省略 `STree` 的 `height` prop 默认值必须是 `undefined`(**不能写死 300**): ```js height: { type: Number, default: undefined } ``` 原因:antd 的 `Tree` 会把 `height` 转成虚拟列表 holder 的行内 `max-height:300px`,导致树被截断且自身产生内层滚动条。 横向文字不换行、超出省略、宽度随父容器拉伸 —— 这套结构规则已统一写在全局 `packages/style/tree.less`(`.s-tree-common` / `.ant-tree*` / `.node-title`),**组件和业务页面都不要再用 scoped 副本**: ```less /* packages/style/tree.less(节选,实际见文件) */ .s-tree-common { height: 100%; width: 100%; overflow-x: hidden; overflow-y: auto; } .ant-tree, .ant-tree-list, .ant-tree-list-holder, .ant-tree-list-holder-inner { width: 100%; min-width: 0; } .ant-tree-node-content-wrapper { min-width: 0; overflow: hidden; } .ant-tree-title, .ant-tree-title > .node-title { display: block; width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } ``` > `.node-title` 是通用类名,全局规则统一写成 `.ant-tree-title > .node-title`(限树标题层内),避免污染业务同名类。 ### 3.7 树样式统一文件与主题变量(`packages/style/tree.less`) 所有树的样式只在这一个文件里,`common.less` 末尾 `@import './tree.less'` 引入。原先散落在 `STree.vue`(scoped)、`SBelowChoosePosition.vue`(scoped 副本)、`common.less`(全局)三处的规则已全部收编。 覆盖的树类型: | 类型 | 选择器根 | 用到的组件 | | ----------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- | | 目录树 / 普通树(`a-directory-tree` / `a-tree`) | `.s-tree-common`、`.ant-tree*` | `STree`、`SBelowChoosePosition`、业务原生 `` | | 树下拉弹层(`a-tree-select`) | `.s-tree-select-popup` | `STreeSelect`、`SDataRangeTreeSelect`(`popup-class-name` 挂类) | | 侧栏树容器高度 | `.s-side-tree` | `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` | 颜色与尺寸全部走 `--s-tree-*` 变量,**默认值等于改造前的硬编码值,视觉零变化**: | 变量 | 默认值 | 说明 | | --------------------------------- | ------------------------- | ------------------------------------------------ | | `--s-tree-node-height` | `30px` | 节点内容行高(弹层同用) | | `--s-tree-node-line-height` | `32px` | 树本体标题行高 | | `--s-tree-node-padding-x` | `4px` | 弹层节点左右内边距 | | `--s-tree-row-gap` | `4px` | 行间距(整行底色留缝) | | `--s-tree-node-radius` | `8px` | 整行圆角(悬浮 + 选中,画在 `::before` 上) | | `--s-tree-switcher-color` | `#000000a6` | 展开箭头色 | | `--s-tree-hover-bg` | `rgba(0,0,0,.04)` | 悬浮整行底色 | | `--s-tree-selected-bg` | `var(--s-color, #1677ff)` | 选中整行底色,**已跟随主题主色** | | `--s-tree-selected-text` | `#fff` | 选中整行文字/箭头色 | | `--s-tree-directory-selected-bg` | `#bae7ff` | 目录树选中浅色底(antd blue-2) | | `--s-tree-directory-selected-text`| `#000000a6` | 目录树选中文字色 | | `--s-tree-icon-color` | `#fff` | 节点类型图标文字色 | | `--s-tree-icon-bg` | `transparent` | 节点图标默认底色 | | `--s-tree-icon-bg-g` / `-c` / `-d`| `#a9a9f5` / `#d3b403` / `#f09191` | 节点图标 G/C/D 类型底色 | 换主题色时按需覆盖即可,不用改组件: ```css /* 纯 CSS 主题:body 上已由基座挂 theme-xxx 类(见 §2.8) */ body.theme-green { --s-tree-selected-bg: #00b96b; --s-tree-directory-selected-bg: #d9f7e9; --s-tree-directory-selected-text: #1f1f1f; } /* 全局微调尺寸 */ :root { --s-tree-node-height: 32px; --s-tree-row-gap: 6px; } ``` 注意两点: 1. `--s-tree-selected-bg` 默认是 `var(--s-color, #1677ff)`,切主题色会自动跟随;浅色档 `--s-tree-directory-selected-bg` 默认仍是 antd blue-2,要跟随就显式覆盖。 2. 变量只放「颜色/长度」本身,不要往里塞整条声明(如 `--x: background:red`)。 ### 3.8 排查渲染问题的铁律 **页面渲染/高度问题必须用 puppeteer 登录后量真实 `offsetHeight`/`offsetLeft`/盒模型,禁止静态读代码猜根因。** ```js // 量:容器高、主体高、底部条位置差、文档溢出 const r = await page.evaluate(() => { const q = (s) => document.querySelector(s) const box = (s) => { const el = q(s) if (!el) return null const b = el.getBoundingClientRect() return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) } } return { container: box('.list-layout-main'), tableContent: box('.table-content'), pagination: box('.ant-table-pagination'), docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight } }) ``` 验收标准(全部为 0 才算过): | 指标 | 通过条件 | | ---------------------------- | --------------------------- | | `documentOverflowY` | `0`(页面不出现滚动条) | | `pagination.bottom` 减容器底 | `0`(分页刚好卡在视口底部) | | 表格主体溢出容器 | `0` | 多视口抽查(建议 1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440)全过才算改完。 --- ## 四、构建与配置 ### 4.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_sapit-base-template` 控制);业务构建才 drop。 产物:入口 `./packages/index.js`,`vue` external,输出 `dist/lib`,打包内容为**入口依赖图**(不是整个项目);`package.json` 的 `files: ["lib","docs","vite-plugins"]`。 ### 4.2 配置来源与优先级 ```text 基座默认 defaultEnv < 业务 web-config.js < .env.[sapit-base-template](构建时写入 config.json) < 部署 config.json(运行时覆盖) ``` - `web-config.js`:可写默认值或 `import.meta.env.VITE_APP_*`; - `.env` / `.env.[sapit-base-template]`:各环境一套(dev/test/uat/prod),由业务 `vite.config.js` 写入 `config.json`; - `config.json`:站点根(子路径为 `config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `"true"/"false"` 归一为布尔。 常用开关(业务可按需覆盖;判断统一用 `!== false`,即未配置时取基座默认值): | 配置项 | 默认值 | 说明 | | -------------------------- | ------------------------------- | ----------------------------------------------------------------------------- | | `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 | | `VITE_APP_MESSAGE_VISIBLE` | `true` | 是否显示右上角消息铃铛(设 `false` 隐藏) | | `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | 消息推送 socket 地址;为空或 `/` 时走同源;本地占位地址在非本机环境下自动跳过 | | `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io 握手路径,需与后端一致 | | `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化 | | `VITE_APP_MENU_BAR` | `left` | 菜单布局:`left` / `top` | | `VITE_APP_MENU_THEME` | `dark` | 菜单主题:`dark` / `light` | | `VITE_APP_MENU_BG` | `theme` | 菜单底色:`theme` 跟随主题色 / `dark` 用 `#001529` / `#RRGGBB` 自定义 | | `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 菜单底亮度 0-100:越大越白 | | `VITE_APP_MENU_BG_SATURATION` | `30` | 菜单配色饱和度上限 0-100 | | `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 选中块里主题色的占比 0-100 | | `VITE_APP_MENU_SUB_BG` | 空 | 子菜单展开区底色;留空按主题色推导(见 2.18) | | `VITE_APP_MENU_HOVER_BG` | 空 | 悬停项底色;留空按主题色推导 | | `VITE_APP_MENU_ACTIVE_BG` | 空 | 选中块底色;留空按主题色推导 | | `VITE_APP_MENU_TEXT` | 空 | 普通文字色;留空按底色推导 | | `VITE_APP_MENU_TEXT_HOVER` | 空 | 悬停文字色;留空按底色推导 | | `VITE_APP_MENU_TEXT_ACTIVE` | 空 | 选中文字色;留空按底色推导 | | `VITE_APP_MENU_GROUP_TITLE` | 空 | 分组标题文字色;留空按底色推导 | 右上角消息铃铛的数量逻辑:进入系统先调 `message/center/counts` 取 `totalCount`,之后由 socket 推送的 `wsEvent` 触发重新拉取。socket 连接为单例(`packages/utils/message-socket.js`),连上后 `emit('sendUserId', userId)`,后端按用户推送。业务侧无需额外注册,只要 `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` 配到消息服务即可。 ### 4.3 业务项目启动(`npm start`) 业务项目(`sapit-base-template`)的 `npm start` 执行内置脚本 `refresh-sapit-base-template.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-sapit-base-template.cmd`;`-NoStart` 仅更新不启动。 > 这个命令通常在基座项目有更新时才会用到。 ## 五、业务项目接入 ### 5.1 安装 ```json { "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } } ``` ### 5.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` 匹配。 ### 5.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`)。 ### 5.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` 时业务覆盖基座内置。 ### 5.5 业务页面与菜单 后端菜单 `hrefs` 需匹配业务 `views` 路径(或组件名);页面放 `src/views/**` 即可被动态路由识别。侧边菜单渲染「动态菜单 + `staticRoutes`」,基座常量菜单不进菜单。 ### 5.6 国际化 / 主题 - 国际化:各模块放 `views/<模块>/i18n.js`(扁平 `{ '中文': 'English' }`),页面**不用写** `useI18n`,`$l('中文')` 自动按页面所在目录命中;要跨目录强制指定时再 `this.useI18n('<模块>')`。业务自己的 `i18n.js` 在业务 `main.js` 里 glob 一次传给 `$registerGlobalConfig({ locales })`,即与基座合并(同名业务优先)。 - 主题:只改 `VITE_APP_THEME_VALUE`;样式用 `var(--s-*)` 或 `.s-theme-*`。 ### 5.7 子路径部署(示例 `/monitor/`) 1. `.env`:`VITE_APP_BASE_URL=/monitor/`; 2. 业务 `vite.config.js`:`base: getViteEnv(res.sapit-base-template, '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/`(带尾斜杠)。 ### 5.8 使用组件与权限 ```html ``` 后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。 --- ### 5.9 内置依赖(业务开箱即用) `sapit-ui-plus` 的 `dependencies` 会随基座一起装进业务 `node_modules`,业务**无需再装即可直接 import**(业务 `package.json` 里通常只见 `sapit-ui-plus` 一项)。 | 依赖 | 版本 | 用途 | | ------------------------------------------------ | ----------------- | ----------------------------------------------------- | | `dayjs` | ^1.11.12 | 日期格式化(推荐,`$utils` 内也用) | | `axios` | ^1.7.3 | 请求(已封装为 `window.$utils.http`,一般不用直接用) | | `qs` | ^6.13.0 | 参数序列化(`stringify`) | | `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | 安全取值 / 深拷贝 | | `crypto-js` | ^4.2.0 | 加解密 | | `js-base64` | ^3.7.2 | Base64 编解码 | | `jsencrypt` | ^3.3.2 | RSA 加密 | | `moment` | ^2.30.1 | 日期(老代码兼容,新代码用 dayjs) | | `html2canvas` | ^1.4.1 | 页面截图 | | `nprogress` | ^0.2.0 | 顶部加载进度条 | | `@vueuse/core` | ^11.0.3 | 组合式工具函数 | | `vue-cropper` | ^1.1.4 | 图片裁剪(SCopperUpload 用它) | | `vuedraggable` | ^4.1.0 | 拖拽排序 | | `v-clipboard` | ^3.0.0-next.1 | 复制到剪贴板(`v-clipboard` 指令) | | `vue-ls` | ^4.2.0 | localStorage 封装(已包成 `$utils.ls`) | | `jodit` | 3.24.7 | 富文本编辑器(SEditor) | | `less` / `less-loader` | ^4.2.0 / ^12.2.0 | 样式编译 | | `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | 构建插件(生成 config.json 等) | | `@ant-design/icons-vue` | 随 ant-design-vue | 图标,**全部已全局注册为组件** | **单例依赖:基座不做打包,业务必须自己安装**(`vite.config.js` 的 `external`),否则会出现两个模块实例(路由注入不上、pinia 对不上、主题/消息上下文丢失): | 依赖 | 版本 | | ---------------- | ------- | | `vue` | ^3.4.29 | | `vue-router` | ^4.3.3 | | `pinia` | ^2.1.7 | | `vue-i18n` | ^9.14.0 | | `ant-design-vue` | 4.x | > 用法:`import dayjs from 'dayjs'` 直接可用;但**不要**在业务里再装一份与基座不同大版本的 `vue`/`ant-design-vue`/`pinia`,版本以基座为准。 ### 5.10 全局注入(无需 import) | 名称 | 说明 | | ------------------------------------------ | ------------------------------------------------------------------------------ | | `$utils` | 工具类:`$utils.http`(请求)、`$utils.ls`(本地存储)、`$utils.env`(配置)等 | | `$message` / `$modal` / `$notice` | ant-design-vue 的 message / Modal / notification | | `$push` / `$open` | 站内跳转 / 新窗口打开(自动拼接部署 base) | | `$l` | 国际化取词(`$l('中文')`) | | `$theme` | 当前主题变量;CSS 变量 `--s-color` 等 | | `$icons` | 全部 antd 图标组件 | | `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / 过滤器 / 用户 store / i18n 实例 | | `env` | 同 `$utils.env` | | `$staticRoutes` | 静态页面路由(含业务自定义) | --- ## 六、注意事项 ### 6.1 业务侧 1. 依赖是预构建产物:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。 2. 锁文件会钉住旧提交:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。 3. 子路径:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。 4. 全局组件命名:按文件名注册(`SForm.vue` → ``,不是 kebab-case);冲突后者覆盖。 5. 主题 / 国际化:定义在基座,业务只选主题、只写文案。 6. 不能深路径 import 基座内部模块:lib 产物只有 `lib/js/index.js` 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性(`$utils` / `$modal` 那样)。 7. 功能去留:源码(老 Vue2 项目)有的我们就有,源码没有的不要"顺手补齐"。新增功能前先确认参照实现。 ### 6.2 开发 / 构建 8. **不要并发跑两个 `vite build`**:会报 `Rollup failed to resolve import "sapit-ui-plus"`,是缓存冲突的假报错,串行重跑即恢复。若串行仍报错,检查 `node_modules/sapit-ui-plus` 是否被清空(npm 重装常清掉)——恢复方式: ```bash # 基座 dist 就是 npm 包内容(build 脚本把 package.json + docs + vite-plugins 拷进 dist) cp -r <基座>/dist/lib <基座>/dist/docs <基座>/dist/vite-plugins <基座>/dist/package.json <业务>/node_modules/sapit-ui-plus/ cp -r <基座>/packages/sso <基座>/packages/static <业务>/node_modules/sapit-ui-plus/ ``` 9. **`vite build --emptyOutDir false`**:清空 `dist` 会被批量删除守卫拦截;只验证编译时用这个参数,**不要**为了验证去执行会 `git push` 内网仓库的 `npm run build`(对外发布动作,须先确认)。 10. **不要并发跑两个基座构建 / 业务安装**,避免缓存互相污染。 11. **`vite build` 不检查未定义变量**:模板/脚本里引用不存在的变量照样通过。改完大段代码必须 `git diff` 复核增删行,配合未使用 import 扫描发现误删。 12. **npm 国内网络**:`registry.npmjs.org` 基本不通,装 `sapit-ui-plus` 会卡在大包上(最重的是 `ant-design-vue` 解压 78MB、`jodit` 23MB)。装包指定国内源: ```bash npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com ``` 若 npm 进程内的 `git ls-remote` 返回 403(沙箱/网络拦截,手工 `git ls-remote` 却通),只能临时摘掉该 git 依赖装其余包,再按第 8 条从基座本地 `dist` 恢复。 13. **npm 包必须含根级 `static/`**:lib 构建不重写 `new URL('../../static/...', import.meta.url)`,运行时从 `lib/js/*.js` 解析到包根 `static/`。缺它业务 dev 登录页图片全 404,而基座自身 dev 正常、生产正常,**极具迷惑性**。 14. **lib 构建图片**:Vite 对 `build.lib` 强制内联所有资产 → 产物可能出现 MB 级 base64 data URI(超 Chrome URL 上限)。`vite-plugins/sso-plugin` 的 `closeBundle` 会把 >100KB 的 data URI 抽为 `lib/img/` 真实文件;源码资产引用一律改 `import`。 ### 6.3 业务字典 / 表单约定(hy-monitor) 15. **下拉 value / 文案一律取字典项的 `value`(字典值),绝不用 `id`(主键)**。字典调`mapByDictTypes('a','b')` 一次性取多个,按**下划线转驼峰**取返回值(`recycle_status` → `res.recycleStatus`),项为 `{label, value, id}`。 16. **`a-select` 的 placeholder 只在值为 `undefined`/`null` 时显示**,空字符串 `''` 会被视为已有值。所有下拉类字段(搜索参数、表单字段)初始值一律 `undefined`,**禁用 `''`**(多选绑定 `[]` 正常)。 17. **时间范围参数统一传毫秒时间戳**(`dayjs(x).valueOf()`),不是 unix 秒。依据:源码 `DateRange` 的 onChange 输出 `date.map(o => dayjs(o).valueOf())`,`useFormValues.fieldMapToTime` 默认 `format=''` 原样透传。 18. **接口请求不写 `catch`**(错误由全局拦截器统一提示)。但三类 catch 必须保留:① 表单校验链 `.catch(() => {})`;② `try { await validate() } catch { return }`;③ `JSON.parse` 解析容错。 19. **接口报错会跳内置错误页**:HTTP 403(含 301)→ `/403`、404 → `/404`,**在内容区 `router-view` 内切换**(保留侧边菜单与顶栏,不整页顶掉外壳),且不再叠加通知。跳转 URL 带 `?api=<接口地址>&status=<原始状态码>`,错误页据此切换成接口口径文案(403「接口无权限」、301「接口地址已变更」、404「接口不存在」)并显示接口地址;不带 `?api=` 时仍是页面口径(页面无权限 / 页面不存在)。**5xx 不跳错误页**,仍走原来的通知提示(`/500` 页面保留,可直接访问)。后台轮询等非主流程请求若要保住当前页面,可传 `{ skipErrorPage: true }` 跳过跳转: ```js this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true }) ``` --- ## 七、常见全局方法速查 | 调用 | 作用 | | --------------------------------------------------------- | ----------------------------- | | `$l('中文'[, key])` | 国际化 | | `$push(path, query)` / `$open(path, query)` | 跳转 / 新窗口(自动拼 base) | | `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | 轻提示 / 弹窗 / 通知 / 确认框 | | `this.$utils.ls.get/set/clear` | 本地存储 | | `this.$utils.http(config)` | 发起请求(默认 POST) | | `$filter.dateFormat(v, fmt)` | 日期格式化 | | `v-action:code` | 按钮级权限(按 `button_code` 全等匹配) | | `$utils.hasAction(code)` | 按钮级权限(函数式,可做「或 / 且」) | | `$utils.iconOf('info-circle')` | antd v1 `type` 写法换图标组件 | | `$utils.messageFormat(str, values)` | `{0}` / `{name}` 占位符替换 | | `$utils.filterSelectOption(iv, opt)` | antd4 版下拉过滤 | | `$utils.randomDrawerPlacement()` | 随机抽屉方向 | | `var(--s-color)` / `.s-theme-color` | 主题色(CSS 变量 / 工具类) | --- ## 八、在线文档入口 | 地址 | 内容 | | ------------------- | ------------------------------------------- | | `/docs` | 说明文档(本文) | | `/components` | s组件(基座内置组件:左菜单 + 预览 + 源码) |