# 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/ # 登录、工作台、待办、消息、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`(卡片列表,见 2.19)、`SListTableTreeLayout`、`SSuperListLayout`(高级列表,见 2.20)、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |
| 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`、`SImportModal`(批量导入,见 2.11) |
| 表单/筛选 | `SForm`、`SFormItem`(多列 + `full` 独占整行,见 3.4)、`SExtendFieldsForm`/`SExtendFieldsFormItem`(动态扩展字段)、`SFilterWrap`、`SFilterItem`(`full` 独占整行,见 3.4)、`SFilterToolbar`(查询区外壳:主区 + 更多筛选折叠 + 条件重置,见 3.4)、`STableToolbar`(表格区外壳:表体高度自动贴合内容区,与 `SFilterToolbar` 成对使用,见 3.4)、`SFilterTableToolbar`(查询区 + 表格区组合件,见 2.22)、`SCascader`、`STree`、`STreeSelect`、`SDataRangeTreeSelect`(数据权限范围树)、`SUserSelect`、`SUserSelectButton`、`SChooseUser`(带数据权限选人弹窗,见 2.14)、`SBelowChoosePosition`(选岗位弹窗,见 2.15)、`SOfficeSelect`、`SIconSelect`(图标下拉,可搜索/多选)、`SIconSelectPopover`(图标网格面板)、`SIconModal`(图标浏览弹窗) |
| 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` |
| 展示/其它 | `STab`/`STabItem`(标签栏,超出宽度自动出左右箭头,见 2.21)、`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`(卡片网格 + 三插槽,见 2.19) |
| 列表 + 左侧树 | `SListTableTreeLayout`(左侧树容器类名必须是 `.side.s-side-tree`,见 3.5) |
| 带高级搜索/高级表格的列表 | `SSuperListLayout`(列设置 + 高级筛选,见 2.20) |
| 新增/编辑/详情(路由式) | `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 | `[]` | 按钮配置数组,见下表 |
| `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/403.vue` | 接口 403 无权限、接口 301 地址变更、页面无权限 | 橙色 `#fa8c16` |
| `/404` | `pages/404.vue` | 路由没命中(通配 `/:pathMatch(.*)*`)、接口 404 | 主题色 `var(--s-color)` |
| `/500` | `pages/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/i18n.js`,命名空间 `pages`),改词条即改三页文字。
- 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 菜单配色(侧边 / 顶部)
菜单色板**由主题色推导**(`light`)或**固定 antd 黑**(`dark`),启动时 `packages/utils/menu-theme.js` 输出实色 `#rrggbb`(**不含 rgba / 透明度**),落到 `:root` 的 `--s-menu-*`,同时挂到 `window.$menuTheme`(含 antd `Menu` token 与 `isLightBg`)。改 `VITE_APP_THEME_VALUE` 换主题色,整套菜单跟着变,不再是写死的淡蓝。
| 部位 | CSS 变量 | `light`(orange 默认) | `light`(blue) | `light`(green) | `dark` |
| -------------- | ---------------------------------------------- | ---------------------- | --------------- | ---------------- | --------------------- |
| 一级菜单底 | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` |
| 子菜单展开区 | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` |
| 悬停项 | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` |
| 选中块 | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500`(主题主色) |
| 普通文字 | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` |
| 悬停文字 | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` |
| 选中文字 | `--s-menu-text-active`、`--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` |
| 分组标题文字 | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` |
| `isLightBg` | — | `true` | `true` | `true` | `false` |
> 三列 `light` 是**同一套规则**在不同主题色下的输出(`VITE_APP_MENU_BG: 'theme'`):色相取主题色、饱和度受 `_BG_SATURATION` 限制、亮度由 `_BG_LIGHTNESS` 定,文字色按对比度求解(≥ 4.6)。`dark` 的底色固定 antd 黑,不读 `VITE_APP_MENU_BG`,只有选中块跟主题色。
**跟随系统深浅色**
`VITE_APP_THEME_FOLLOW_SYSTEM`(默认 `true`)由 `packages/utils/color-scheme.js` 处理:监听 `prefers-color-scheme`,系统切深色时**立即**把菜单按 `dark` 重算、中性色令牌换成暗色版、`body` 加 `scheme-dark`,切回浅色全量还原 —— 运行时生效,不用刷新。
| 令牌 | 浅色 | 深色 |
| --------------------- | ------------------- | ----------------------- |
| `--s-text-color` | `#262626` | `#e8e8e8` |
| `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` |
| `--s-bg-color-container` | `#ffffff` | `#1f1f1f` |
| `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` |
| `--s-color-warning-bg` | `#fffbe6` | `#2b2413`(语义浅底压暗) |
> ⚠️ 暗色令牌只对**用 `var(--s-*)` 取色**的地方生效。业务页面里硬编码的 `background: #fff` 不会自动变暗,要适配深色得换成 `var(--s-bg-color-container)`;也可以直接用 `body.scheme-dark` 写自己的覆盖。
> 关掉跟随(`VITE_APP_THEME_FOLLOW_SYSTEM: false`)后深浅固定按 `VITE_APP_MENU_THEME` 走,业务本来配 `dark` 的不受影响。
**业务只能选模式,不能改颜色**
| 配置 | 默认 | 业务可否覆盖 | 说明 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------ | ------------------------------------------ |
| `VITE_APP_MENU_THEME` | `light` | ✅ | `light` 跟主题色的浅色系 / `dark` 黑色 |
| `VITE_APP_MENU_BAR` | `left` | ✅ | `left` 侧边 / `top` 顶部(布局项) |
| `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | ✅ | 是否跟随系统深浅色(`prefers-color-scheme`)|
| `VITE_APP_MENU_BG` / `_SUB_BG` / `_HOVER_BG` / `_ACTIVE_BG` / `_TEXT` / `_TEXT_HOVER` / `_TEXT_ACTIVE` / `_GROUP_TITLE` / `_BG_LIGHTNESS` / `_BG_SATURATION` / `_BG_ACTIVE_MIX` | 见 4.2 | ❌ | 11 个颜色 / 调色键,一律被基座回填 |
锁定机制:`packages/config/web-config.js` 导出 `menuColorKeys`(上表 ❌ 的 11 个键),`packages/index.js` 在 `registerGlobalConfig` 里**于 `loadRemoteConfig()` 合并之后**按清单把 `env` 中这些键强制回填成基座默认值。因此业务 `.env`、`src/config/web-config.js`、部署目录 `config.json` 三处写的菜单颜色全部无效,所有业务项目的菜单与基座 demo 完全一致。
> 想临时验证「业务传色确实无效」:在业务 `config.json` 里写 `"VITE_APP_MENU_BG": "#ff0000"`,刷新后菜单仍是按主题色推导的那套值。
**要改整套色板**(基座维护,不是单个业务能自己改的事):
1. 色值:改 `packages/config/web-config.js` 的 `VITE_APP_MENU_*` 默认值;
2. 推导规则:`light` 分支在 `packages/utils/menu-theme.js`(`dark` 分支固定黑色体系,不读 `VITE_APP_MENU_BG`);
3. CSS 兜底:同步改 `packages/style/theme.less` 的 `--s-menu-*`;
4. 重新打包基座 → 业务更新 `sapit-ui-plus`(见 4.1)。
> 注意事项
>
> 1. `light` 下把 `VITE_APP_MENU_BG` 配成 `dark` 会被忽略并告警(黑底属于 `dark` 模式),仍按浅色推导。
> 2. 单项颜色覆盖只对 `light` 生效,`dark` 保持纯黑体系,不会出现「黑底 + 淡蓝子菜单」。
> 3. 业务样式不要写死 `#001529`、`rgba(255,255,255,.1)` 这类菜单色,直接 `var(--s-menu-*)`。
> 4. 侧边菜单、顶部菜单(`VITE_APP_MENU_BAR: 'top'`)、logo 明暗、顶栏文字色共用 `window.$menuTheme.isLightBg` 判断,不看 `VITE_APP_MENU_THEME` —— 系统深色跟随会改写它,所以判断必须走这个字段。
> 5. `window.$menuTheme` 是 `reactive` 对象:深浅色切换时只改属性不换引用,`SSideMenu` 的 `computed` 读 `window.$menuTheme.token` 会自动重算,antd `Menu` token 无需手动刷新。
### 2.19 SListCardLayout 卡片列表布局
与 `SListLayout` 同一套骨架(标题条 + 查询区 + 分页),中间换成卡片网格。卡片正方形、圆角 8px,头部 / 内容 / 底部三段全部由插槽控制。
```vue
{{ item.title }}
名称:{{ item.name }}
编辑
```
| 参数 | 类型 | 默认 | 说明 |
| ----------------- | ----------------- | ----------------------------- | ------------------------------------------------------ |
| `title` | String | 必填 | 标题条文字 |
| `column` | Number / String | `5` | 每行卡片数,内部 `repeat(column, 1fr)` |
| `loadData` | Function | 必填 | `({ pageNo, pageSize }) => { list, total }` |
| `rowKey` | String / Function | `'id'` | 卡片 key;字段 / 函数取不到时退回下标 |
| `buttons` | Array | 添加 / 批量删除 / 导入 / 导出 | 与 `SListLayout` 同构(`name/key/show/type/icon/api`) |
| `showPagination` | Boolean | `true` | 是否显示分页 |
| `pSize` | Number / String | `20` | 默认每页条数 |
| `pageSizeOptions` | Array | `['10', '20', '40', '80']` | 每页条数可选项 |
| 插槽 | 作用域 | 说明 |
| ------------------------------------------------------------------------------------ | ----------------- | -------------------------------------------------------- |
| `default` | `{ item, index }` | 卡片内容区,完全自定义 |
| `cardHeader` | `{ item, index }` | 卡片头部;不传用 `item.title`,两者都空则不渲染 header |
| `cardFooter` | `{ item, index }` | 卡片底部;不传为默认「编辑 / 删除」,点击抛 `cardAction` |
| `filter` / `filterMore` / `desc` / `tabs` / `tree` / `empty` / `other` / `otherBtns` | 同 `SListLayout` | 与普通列表布局一致 |
事件:`cardAction(key, item, index)`(`key` 为 `edit` / `delete`)、`btnCallback(key, selections)`、`reset`。`ref` 上可调 `reload(forceFirst)` / `fetchList()`。
**样式约定**(都写在组件内 `scoped`,类名统一 `s-card-*` 前缀,避免误伤业务里的通用 `card-*`):
| 类名 | 说明 |
| ------------------- | ------------------------------------------------- |
| `s-card-grid` | `display:grid` + `gap:12px`,列数由 `column` 决定 |
| `s-card-item` | `aspect-ratio: 1/1` 正方形 + `border-radius: 8px` |
| `s-card-header` | 头部,单行超出省略 |
| `s-card-body` | 内容区,撑满剩余高度,超出内容在卡片内部裁切 |
| `s-card-footer` | 底部按钮区,`min-height:36px`,左右两端对齐 |
| `s-card-empty` | 空态,`grid-column: 1 / -1` 跨满整行 |
| `s-card-pagination` | 分页条,高度从卡片区里扣掉,避免双滚动条 |
**取数归一化**:`list`(或 `data`)取行、`total` / `pagination.total` / `totalCount` 取总数、`pageNo` / `pageNum` / `pagination.current` 回写当前页;接口异常只 `console.warn` 并清空,不会一直转圈。切每页条数时统一在 `change` 里判断,避免同一动作发两次请求。
### 2.20 SSuperListLayout 高级列表(列设置 + 高级筛选)
在 `SListLayout` 基础上多两个抽屉:右上角「高级表格」改列、「高级搜索」加条件。两者都是**草稿 + 确定生效**:抽屉里改的是副本,点「确定」才回写并刷新表格,点「关闭」直接丢弃,不会出现「点一下表格就跳」。
```vue
```
| 参数 | 类型 | 默认 | 说明 |
| ---------------- | ----------------- | ----------------------------- | ------------------------ |
| `title` | String | 必填 | 标题条文字 |
| `columns` | Array | `[]` | 列配置,见下方 |
| `loadData` | Function | 必填 | 取数,入参含高级筛选结果 |
| `rowKey` | String / Function | `'id'` | 行 key |
| `buttons` | Array | 添加 / 批量删除 / 导入 / 导出 | 与 `SListLayout` 同构 |
| `isSelection` | Boolean | `false` | 是否显示勾选列 |
| `showPagination` | Boolean | `true` | 是否显示分页 |
| `pSize` | Number / String | `20` | 默认每页条数 |
列配置在 `SListLayout` 基础上多两项:
| 字段 | 说明 |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `filterConfig` | 配了才会出现在「高级搜索」的可选字段里;不配则该列只能看不能筛 |
| `width` | px / 纯数字 → 直接生效,并带进「高级表格」的列宽输入框;`%` → 仅作表头宽度,高级表格里的像素框留空 |
`filterConfig` 可用键:`filterType` / `filterApi` / `filterData` / `props` / `precision` / `step` / `minValue` / `maxValue` / `length` / `startDate` / `endDate`。
`filterType`:[`INPUT` 输入框、`INT` 整数、`FLOAT` 浮点、`DATE` 日期、`DATETIME` 时间、`SINGLE_SELECT` 单选、`MULTIPLE_SELECT` 多选、`GANDER` 性别、`IS` 是否、`USER` 用户、`OFFICE` 组织机构]。下拉类的选项优先取 `filterData`,没配才用 `filterApi` 拉一次并回填。
**列设置(`SettingColumns`)**
- 显示 / 隐藏:勾选即改草稿,**确定后** `show === false` 的列不进表格(仍可被高级搜索使用);
- 冻结 / 取消冻结:记住每列最初的冻结方向,取消后再冻结还原原来的 `left` / `right`;操作列(`action`)永远 `right` 且禁用;
- 列宽:表头 `width` 是 px 或纯数字 → 四舍五入带进输入框;`20%` 这类百分比不带入;用户主动清空则恢复「自适应」;
- 「确定」→ 回写列配置并关抽屉;「重置」→ 恢复调用方传入的 `columns`;「关闭」→ 丢弃草稿。
**高级筛选(`SettingFilter`)**
- 可选字段 = 配了 `filterConfig` 的列(列被隐藏也能筛);
- 运算符按类型收窄:文本(`INPUT` 或未配类型)可 `includes` / `excludes` / `equal` / `notequal` / `null` / `notnull`;选择、数字、日期只留 `equal` / `notequal` / `null` / `notnull`;
- 换字段时运算符按新类型重置(文本默认「包含」,其余默认「等于」);
- `null` / `notnull` 不需要填值;其余没填值的条件行在提交时丢弃,不会把空条件发给后端。
提交后的取数入参:
```js
loadData({
pageNo,
pageSize,
filterMode, // 1
filterConditions: [{ dataIndex, equals, value }],
[dataIndex]: value // equal / includes 这类单值条件额外铺平一份
})
```
`equal` / `includes` 的单值条件会同时铺平成同名字段(`params[dataIndex] = value`),后端按字段名直接取用即可,不用解析 `filterConditions`。
### 2.21 STab 标签栏(超出宽度自动出左右箭头)
一行横向标签,**放得下就不出箭头**,放不下时左右各出一个 32×32 箭头:点箭头等于「选中上一个/下一个标签 + 把它滚进可视区」。
两种用法,任选其一:
```vue
任务配置
执行日志
```
**默认选中**:不传 `activeKey` 也能用 —— 传 `default-active-key` 就选中它,两者都没传则自动选中第一项(组件挂载后补默认值,并通过 `update:activeKey` 同步给父级,`@change` 不算用户操作、不会触发)。
```vue
```
| 项 | 说明 |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `v-model:activeKey` | 当前选中值,`String`/`Number`;**不传 / 传空(`''`)都会自动选中**(见下一行) |
| `defaultActiveKey` | 默认选中值:`activeKey` 没传或传空时生效;**它也没传就默认选中第一项** |
| `tabs` | `[{ label, value }]`;字段名不同用 `tabKey`(默认 `{ label: 'label', value: 'value' }`) |
| `tabKey` | 字段映射,与 `SFormLayout`/`SSkeletonLayout` 的 `tabs` 约定一致 |
| `stepRatio` | 已到首个/末个标签但仍可滚动时,一次滚多少屏,默认 `0.6` |
| `@change` | `(key, item)`;插槽模式下 `item` 为 `undefined` |
| 插槽 | 默认插槽放 `s-tab-item`;一旦使用默认插槽,`tabs` 不再参与渲染 |
| expose | `syncArrow()` / `scrollToActive()` / `scrollRef` |
**交互规则**
| 场景 | 行为 |
| ---------- | -------------------------------------------------------------- |
| 内容放得下 | 不渲染箭头,标签铺满整行 |
| 内容超出 | 左右箭头出现 |
| 点右箭头 | 选中下一个标签并滚进可视区;已是最后一个则退化为「纯滚动一屏」 |
| 箭头禁用 | 既没有上一个/下一个标签,也无法再滚动时禁用 |
| 滚轮 | 纵向滚轮转横向滚动,不会带动整页 |
| 鼠标拖动 | 按住左键左右拖动即可平移标签栏(仅溢出时生效);位移超过 5px 才算拖动,不会误触发标签切换;**悬停不显示抓手光标,按下才变抓手** |
| 触摸 | 不接管,保持系统原生横向滚动与惯性 |
| 键盘 | 标签聚焦后左右方向键切换 |
> ⚠️ 只给标签栏,不给内容区。内容请自己按 `activeKey` 渲染(切显隐用 `v-show`,不要用 `v-if`,否则隐藏页签里的组件实例会丢)。
> 典型例子:权限配置里按客户端分的多个表格,保存时要同时读到所有页签的勾选,必须全部渲染、只切显示。
**配色跟随主题**(组件内没有写死颜色,换 `VITE_APP_THEME_VALUE` 自动跟着变)
| 元素 | 取色 | 对应变量 |
| ---------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| 选中 / 悬停标签 | 主题主色 | `--s-color` |
| 未选中标签、箭头 | 主题主色 30% 混入中性灰 → 带主题倾向的灰(对比度 ≥ 4.5:1) | `color-mix(… var(--s-tab-color) 30%, #595959)` |
| 箭头到头(禁用) | 主题描边色 | `--s-border-color` |
想单独调整标签栏配色,在外层覆盖这几个变量即可,不用改组件、也不用动主题:
```less
.my-page {
--s-tab-color: #333; // 未选中 / 箭头(参与颜色调和)
--s-tab-active-color: #fa541c; // 选中 / 悬停
--s-tab-disabled-color: #ddd; // 箭头到头
}
```
> 老浏览器(不认识 `color-mix`)自动退化为中性灰 `#595959`,不会出现「文字继承不到颜色」的问题。
### 2.22 SFilterTableToolbar(查询区 + 表格区组合件)
`SFilterToolbar` + `STableToolbar` 的现成组合:上半查询区、下半表格区,**表格吃掉剩余高度并在内部滚动**。
```vue
修改
```
| 项 | 说明 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 查询区插槽 | `filter`、`filterMore`(透传给 `SFilterToolbar`) |
| 表格插槽 | 其余插槽全部透传给 `STableToolbar`(列名插槽、`bodyCell`、`expandedRowRender`…) |
| 其余属性 | `columns` / `data` / `rowKey` / `pageSize` / `size` / `scrollX` / `tableHeight`,其余通过 `$attrs` 透传给 `s-table`(如 `showPagination`) |
| `@reset` | 只抛事件,**查询参数在业务侧**,清空后自己调 `refresh()` |
| expose | `refresh(deleteFlag)` / `reload()` / `resize()` / `tableRef` |
**高度前提**:组件根节点是 `height:100%` 的 flex 列,需要外层给到确定高度才会撑满 ——
- 放进 `SFormLayout` 的 `#form` 插槽 ✅(`form-container-wrap` 已是 `flex:1`)
- 放进 `SSkeletonLayout` 默认插槽 ✅(`.skeleton-container` 已是 `flex:1`)
- 直接丢进普通 `div` ❌,高度会退化成内容高度(这是 CSS 的规矩,不是组件 bug)
## 三、布局与高度规范
> 本章是**基座内部布局组件的强制约定**。业务页面只管用 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`。列表页、表单页绝大多数场景用这个就够。
> **2026-11-06 现状**:`SSkeletonLayout`、`SListLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SNewestDataListLayout`、`SListCardLayout`、`SListBasicLayout`、`SFormLayout`、`SFormBasicLayout`、`SPanelLayout`、`SFilterTableToolbar` **已全部改为纯 CSS flex,零 JS 测量高度**。业务页面不需要再写任何高度代码。
**布局组件根节点的标准写法**(新增布局组件请照抄):
```less
.xxx-layout {
height: 100%; /* 吃满父容器,父级必须有确定高度 */
min-height: 0; /* ✅ 必须:允许被压缩 */
display: flex;
flex-direction: column;
overflow: hidden;
}
```
两个必须记住的点:
| 点 | 说明 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ 必须写 `min-height: 0` | flex item 默认 `min-height: auto` = **内容最小高度**。不写它,内容一多就会被顶开、把父级(`PageView` 的 `.page-view-common`)撑破,表现为**外层 router-view 多出一条滚动条**。 |
| ❌ 不要写 `max-height: 100%` | 父级高度不是显式值时,这个百分比会把根节点压成 0/极小,**整条 flex 链瞬间塌掉**(表格只剩表头、左侧树错位)。防塌陷靠父级显式高度,不靠 `max-height`。 |
**中间层必须一起贯通**,漏一层就断链:
- `a-spin` 夹在中间时:`.ant-spin-nested-loading`、`.ant-spin-container` 都要 `flex:1 1 auto; min-height:0; display:flex; flex-direction:column`
- 滚动包裹层(如 `.form-layout-main-scroll`)也要设成 flex 列,否则里面的 `flex:1` 拿不到高度
- 分隔条、滚动条这类固定尺寸元素写 `flex: 0 0 <尺寸>`,**不要只写 `width`** —— 否则空间一紧就被压成 0(左边树拖不动的元凶)
**现在唯一还需要 JS 的地方**:表格的 `scroll.y`。它只用于启用 antd 固定表头,值取 `.ant-table-body` 的真实 `clientHeight`,**不参与布局**(CSS 已用 `max-height: none !important` 覆盖 antd 写入的内联 `max-height`)。
**需要 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;
}
```
**多列与独占整行(`full`)**
`SForm` 的 `a-form` 与 `SCollapsesItem` 的内容区都是 `display:grid; grid-template-columns: repeat(column, 1fr)`。多列时想让某一项独占整行,给子项加 `full` 即可(内部落成 `grid-column: 1 / -1`):
```vue
```
**筛选区独占整行(`SFilterItem` 的 `full`)**
`SFilterWrap` 是 `display:flex; flex-wrap:wrap; gap:10px` 容器,子项宽度默认由 `width`(px,默认 280)决定。加 `full` 后该项宽度拉满 `100%`(`flex: 1 1 100%`),自然独占一行,后面的项自动换到下一行:
```vue
```
- `full` 优先于 `width`:同时传时忽略 `width`。
- `label` 仍按 `labelWidth`(默认 70)渲染,剩余宽度全部给内容区,`a-select` 会自动撑满。
- 只有 `SFilterItem` 有这个属性;`SFilterWrap` 本身不需要配列数。
| 参数 | 类型 | 默认 | 归属 |
| ------ | ------- | ------- | -------------------------------------------- |
| `full` | Boolean | `false` | `SFormItem`、`SCollapsesItem`、`SFilterItem` |
- 单列时 `1 / -1` 等价于一整行,没有副作用,所以同一个表单项在 1 列 / N 列之间切换不用改代码。
- `column` 是 **`SCollapsesItem`** 的 prop,不是 `SCollapses` 的;写在 `` 上不生效。
- `SFormItem` 的 `full` 已声明为 prop,不会透传到内部 `a-form-item` 上触发 antd 警告;`SFilterItem` 同理,不会落到内层节点。
- 实现方式不同:`SFormItem` / `SCollapsesItem` 落在 `grid-column: 1 / -1`,`SFilterItem` 落在 `flex-basis: 100%`,用法一致。
**查询区外壳(`SFilterToolbar`)**
只想要查询区(不带表格、不带布局外壳)时用 `SFilterToolbar`:主查询区常显 + 「更多 / 收起」折叠 + 条件重置。功能与 `SListLayout` / `SListBasicLayout` 的 `filter` / `filterMore` 插槽一致,但**内部已包 `SFilterWrap`**,业务只写 `SFilterItem`。
```vue
```
| 插槽 | 说明 |
| ------------ | --------------------------------------- |
| `filter` | 主查询区,常显 |
| `filterMore` | 折叠区,`v-show` 控制;不传则按钮不渲染 |
| 事件 | 参数 | 说明 |
| -------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `reset` | — | 点「条件重置」,父级清空查询参数后自行 `reload` |
| `toggle` | `isMoreFilter` | 折叠状态变化;表格区用 `STableToolbar` 时**无需处理**(它自己观察容器尺寸),自建表格才需要重算 |
- 「更多 / 收起」按钮**紧跟查询内容右侧**(居左),重置按钮推到最右,与 `SListLayout` 的 `.filter-more-btn` / `.reset-wrap` 完全同款。
- 查询区高度随折叠变化。表格区**优先用 `STableToolbar`**,它内部 `ResizeObserver` 观察自身容器,折叠后自动重算表体高度,父级零配置。
- `defineExpose`:`isMoreFilter`、`toggleFilter()`、`filterReset()`、`collapse()`(切 tab 时主动收起)。
**表格区外壳(`STableToolbar`)**
`SFilterToolbar` 的固定搭档:封装 `STable` + 分页 + **表体高度自适应**,替业务承担「内容区 − 查询区 − 表头 − 分页」这套算法,保证不出页面级滚动条。
```vue
```
```less
.page {
height: 100%;
min-height: 0;
display: flex;
flex-direction: column;
}
```
| prop | 默认值 | 说明 |
| ------------------ | ---------- | ------------------------------------------------------------- |
| `columns` / `data` | — | 同 `STable`,`data` 必填 |
| `rowKey` | `'id'` | 同 `STable` |
| `pageSize` | `10` | 同 `STable` |
| `size` | `'middle'` | 同 `STable` |
| `scrollX` | `'100%'` | 横向滚动;表体 `y` 由组件自己算,**父级传 `scroll` 会被忽略** |
| `tableHeight` | `300` | `scroll.y` 的初值;真实高度由布局 flex 决定,父级一般不用传 |
- 属性除上表外原样透传给 `STable`。
- **单元格插槽与 `SListLayout` 完全一致:列 `dataIndex` 就是插槽名**,参数 `{ text, record, index, column }`,没有同名插槽的列按原值渲染。`#headerCell` / `#expandedRowRender` / `#emptyText` 这类非列插槽仍原样透传。
- **不要再写 `#bodyCell`**:组件内部已经占用了它做列分发,业务再写会被忽略,该列整列空白(操作列"消失"就是踩的这个坑)。
- 高度:**纯 flex 撑满,不做算术**。根节点 → `.table-wrapper` → `.ant-table-wrapper` → `.ant-spin-container` → `.ant-table` → `.ant-table-container` 逐层 `flex:1 1 auto;min-height:0`,表头/分页 `flex:0 0 auto`,表体 `flex:1 1 auto;max-height:none!important`。容器 `overflow: hidden`,所以**永远不会顶出页面级滚动条**。
- 布局可视内容区变化(`filterMore` 展开、tab 切换、窗口缩放、侧栏收起)由布局自动跟随,父级不用写 `onFilterToggle`。
- `defineExpose`:`resize()`(手动重算)、`refresh(deleteFlag)`(转发 `STable.refresh` 并在刷新后补算分页高度)、`reload()`、`tableRef`、`scrollY`。
- 父级根节点必须给「有高度 + `flex` 纵向」的排布(`height:100%; display:flex; flex-direction:column`),组件靠 `flex: 1 1 0%` 接手剩余空间。
### 3.5 左侧树容器高度统一(`.s-side-tree`)
`SListLayout` / `SListTableTreeLayout` / `SListCardLayout` 的 `.side` 都是 `padding: 10px`(四边),树容器高度必须等于「`.side` 盒高 − 上下 padding(20px)」,否则双滚动条或树被截断。
规则写在**全局** `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` | `var(--s-color-bg)` | 悬浮整行底色,**跟随主题主色**(主色混白 90%;暗色下自动换主色深底) |
| `--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 地址:**只写协议+主机+端口,不要带 `/apig/` 等路径**;为空或 `/` 时走同源;本地占位地址在非本机环境下自动跳过 |
| `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` | `light` | 菜单配色模式:`light` 跟主题色的浅色系 / `dark` 黑色(业务可选) |
| `VITE_APP_THEME_FOLLOW_SYSTEM`| `true` | 是否跟随系统深浅色(`prefers-color-scheme`):系统切深色时菜单换黑 + 中性色令牌换暗色版,运行时即时生效(业务可选) |
| `VITE_APP_MENU_BG` | `theme` | 基座锁定:`light` 一级底;`theme` 跟随主题色(默认)/ `#RRGGBB` 固定 |
| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 基座锁定:一级底亮度 0-100 |
| `VITE_APP_MENU_BG_SATURATION` | `66` | 基座锁定:饱和度上限 0-100 |
| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 基座锁定:选中块里主题色的占比 0-100 |
| `VITE_APP_MENU_SUB_BG` | 空 | 基座锁定:子菜单展开区底色;空 = 按主题色相推导 |
| `VITE_APP_MENU_HOVER_BG` | 空 | 基座锁定:悬停项底色;空 = 按主题色相推导 |
| `VITE_APP_MENU_ACTIVE_BG` | 空 | 基座锁定:选中块底色;空 = 主题色兑白(占比见 `_BG_ACTIVE_MIX`) |
| `VITE_APP_MENU_TEXT` | 空 | 基座锁定:普通文字色;空 = 按主题色相推导 |
| `VITE_APP_MENU_TEXT_HOVER` | 空 | 基座锁定:悬停文字色 |
| `VITE_APP_MENU_TEXT_ACTIVE` | 空 | 基座锁定:选中文字色 |
| `VITE_APP_MENU_GROUP_TITLE` | 空 | 基座锁定:分组标题文字色 |
> 标「基座锁定」的 11 项即使写进业务 `.env`、`src/config/web-config.js` 或部署目录 `config.json`,也会被基座强制回填成上表默认值;业务能决定的只有 `VITE_APP_MENU_THEME`(选哪套)、`VITE_APP_MENU_BAR`(侧边 / 顶部)与 `VITE_APP_THEME_FOLLOW_SYSTEM`(是否跟随系统深浅色)。机制与色板推导见 [2.18](#docs-218菜单配色侧边顶部)。
socket 是**整站一条连接**(`packages/utils/socket.js`,单例,与源项目 `VueSocketIO` 只注册一次一致),消息与扫码登录共用同一个地址、同一个 `path`,只靠事件名区分:
| 业务 | 上报事件 | 接收事件 | 模块 |
| --- | --- | --- | --- |
| 右上角消息铃铛 | `sendUserId`(userId) | `wsEvent` | `packages/utils/message-socket.js` |
| 扫码登录 | `QRCodeKey`(qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` |
数量逻辑:进入系统先调 `message/center/counts` 取 `totalCount`,之后由 socket 推送的 `wsEvent` 触发重新拉取。业务侧无需注册任何东西,只要把 `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` 配到网关即可。
> `VITE_APP_SOCKET_URL` 里写了路径会踩坑:socket.io 把 URL 的 path 当 **namespace**(`io('http://h:50001/apig/')` → namespace `/apig/`),服务端回 `Invalid namespace`,握手成功但永远不 connect,也不报 `connect_error`。基座虽已在 `resolveSocketUrl` 里剥掉 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/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' }`,命名空间 = `views` 之后的第一段目录名。
- 页面里不用写 `useI18n`:`$l('中文')` 自动按页面所在目录命中;跨目录强制指定用 `this.useI18n('<模块>')`(Options API)或 `window.useI18n('<模块>')`(`