| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145 |
- import { resolveComponent as k, openBlock as x, createElementBlock as _, createElementVNode as u, createTextVNode as m, toDisplayString as g, createVNode as y, withCtx as v } from "vue";
- import { n as E } from "./index2.js";
- const f = (t = "") => String(t).replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">"), P = (t = "") => String(t).replace(/[^\w\u4e00-\u9fa5-]/g, ""), c = (t = "") => {
- const n = [], r = [];
- let e = String(t);
- return e = e.replace(/`([^`]+)`/g, (o, a) => (n.push(`<code>${f(a)}</code>`), `\0C${n.length - 1}\0`)), e = e.replace(/<\/?span[^>]*>/g, (o) => (r.push(o), `\0S${r.length - 1}\0`)), e = f(e), e = e.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>'), e = e.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>"), e = e.replace(/\u0000C(\d+)\u0000/g, (o, a) => n[+a]), e = e.replace(/\u0000S(\d+)\u0000/g, (o, a) => r[+a]), e;
- }, w = (t = "") => t.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((n) => n.trim()), I = (t = "") => /^\s*\|?[\s:|-]+\|?\s*$/.test(t) && t.includes("-"), S = (t = "") => {
- const n = String(t).replace(/\r\n/g, `
- `).split(`
- `), r = n.length;
- let e = 0, o = "", a = null;
- const s = () => {
- a && (o += `</${a}>
- `, a = null);
- };
- for (; e < r; ) {
- const i = n[e], b = i.match(/^```(\w*)\s*$/);
- if (b) {
- s();
- const l = b[1];
- e++;
- const d = [];
- for (; e < r && !/^```\s*$/.test(n[e]); )
- d.push(n[e]), e++;
- e++, o += `<pre class="docs-code" data-lang="${l}"><code>${f(d.join(`
- `))}</code></pre>
- `;
- continue;
- }
- if (/^\s*$/.test(i)) {
- s(), e++;
- continue;
- }
- if (/^-{3,}\s*$/.test(i)) {
- s(), o += `<hr/>
- `, e++;
- continue;
- }
- const p = i.match(/^(#{1,6})\s+(.*)$/);
- if (p) {
- s();
- const l = p[1].length, d = p[2].trim();
- o += `<h${l} id="docs-${P(d)}">${c(d)}</h${l}>
- `, e++;
- continue;
- }
- if (/^>\s?/.test(i)) {
- s();
- const l = [];
- for (; e < r && /^>\s?/.test(n[e]); )
- l.push(n[e].replace(/^>\s?/, "")), e++;
- o += `<blockquote>${S(l.join(`
- `))}</blockquote>
- `;
- continue;
- }
- if (/^\s*\|/.test(i) && e + 1 < r && I(n[e + 1])) {
- s();
- const l = w(i);
- e += 2;
- const d = [];
- for (; e < r && /^\s*\|/.test(n[e]); )
- d.push(w(n[e])), e++;
- o += "<table><thead><tr>" + l.map((h) => `<th>${c(h)}</th>`).join("") + "</tr></thead><tbody>" + d.map((h) => "<tr>" + h.map((T) => `<td>${c(T)}</td>`).join("") + "</tr>").join("") + `</tbody></table>
- `;
- continue;
- }
- if (/^\s*[-*]\s+/.test(i)) {
- a !== "ul" && (s(), o += `<ul>
- `, a = "ul"), o += `<li>${c(i.replace(/^\s*[-*]\s+/, ""))}</li>
- `, e++;
- continue;
- }
- if (/^\s*\d+\.\s+/.test(i)) {
- a !== "ol" && (s(), o += `<ol>
- `, a = "ol"), o += `<li>${c(i.replace(/^\s*\d+\.\s+/, ""))}</li>
- `, e++;
- continue;
- }
- s(), o += `<p>${c(i.trim())}</p>
- `, e++;
- }
- return s(), o;
- }, A = '# sapit-ui 基座说明与业务使用文档\n\n> 适用工程:<span style="color:#1677ff;font-weight:700">sapit-ui-framework</span>(基座/源码)、<span style="color:#1677ff;font-weight:700">sapit-ui-plus</span>(发布产物)、<span style="color:#1677ff;font-weight:700">sapit-base-template</span>(业务示例)\n>\n> 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。\n\n---\n\n## 目录\n\n- [一、总览](#docs-一总览)\n- [二、基座提供的内容](#docs-二基座提供的内容)\n- [三、布局与高度规范](#docs-三布局与高度规范)\n- [四、构建与配置](#docs-四构建与配置)\n- [五、业务项目接入](#docs-五业务项目接入)\n- [六、注意事项](#docs-六注意事项)\n- [七、常见全局方法速查](#docs-七常见全局方法速查)\n- [八、在线文档入口](#docs-八在线文档入口)\n\n---\n\n## 一、总览\n\n### 1.1 五者关系\n\n| 工程 | 角色 | 说明 |\n| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |\n| `sapit-ui-framework` | <span style="color:#d4380d">基座(源码)</span> | 内置组件与常用依赖的库工程,Vite lib 模式打包 |\n| `sapit-ui-plus` | <span style="color:#d46b08">发布产物</span> | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) |\n| `sapit-base-template` | <span style="color:#389e0d">业务使用者</span> | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 |\n\n```text\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\n```\n\n### 1.2 目录结构(基座)\n\n```text\nsapit-ui-framework/\n├─ packages/ # 发布内容来源(入口依赖图)\n│ ├─ index.js # 库入口,导出 registerGlobalConfig\n│ ├─ components/ # 内置组件 S*\n│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView\n│ ├─ router/ # 常量路由 + 动态路由 + 静态路由 + 守卫\n│ ├─ store/ api/ utils/ locales/ static/ style/\n│ └─ pages/ # 登录、工作台、待办、消息、404/403/500、docs 文档页\n├─ docs/ # 本文档(供内置 /docs 渲染)\n├─ vite-plugins/ # docs-viewer 插件\n├─ src/ # 基座自身调试壳\n└─ vite.config.js / package.json\n```\n\n---\n\n## 二、基座提供的内容\n\n### 2.1 全局组件\n\n`packages/index.js` 用 `import.meta.glob(\'./components/**/*.vue\')` 把 `components/**/*.vue` **按文件名全局注册**,模板直接以文件名标签使用(如 `<s-modal>`、`<s-user-select>`)。\n\n| 分类 | 组件 |\n| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 布局类 | `SSkeletonLayout`(骨架布局:标题 + 按钮组 + 内容区,见 2.16)、`SListLayout`、`SListCardLayout`(卡片列表,见 2.19)、`SListTableTreeLayout`、`SSuperListLayout`(高级列表,见 2.20)、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |\n| 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`、`SImportModal`(批量导入,见 2.11) |\n| 表单/筛选 | `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`(图标浏览弹窗) |\n| 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` |\n| 展示/其它 | `STab`/`STabItem`(标签栏,超出宽度自动出左右箭头,见 2.21)、`SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SColorPicker`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、`SSideMenu`/`STopMenu` |\n\n> 组件用法见内置组件页 **`/components`**(含「s组件」「工具/配置」两个标签页;「工具/配置」列出 web-config 全部配置项与 `$utils` 全部方法)。\n>\n> 注册规则:`components/**/*.vue` 按**文件名**全局注册(`SForm.vue` → `<SForm>`,**不是 kebab-case**),冲突后者覆盖。\n> `Table/index.jsx` 是 `.jsx`、`import.meta.glob` 匹配不到,基座在`packages/index.js` 里**单独注册为全局 `STable`**(`<s-table>` 可直接用,无需 import)。\n> `@ant-design/icons-vue` 图标全部全局注册并挂到 `$icons`。\n> 另有内部辅助组件不对外使用:`ModalHeader`(SModal)、`CropperModal`(SCopperUpload)、`CustomInput`/`SettingColumns`/`SettingFilter`(SSuperListLayout)。\n\n### 2.1.1 布局组件选择\n\n| 场景 | 用哪个 |\n| -------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| 标题 + 按钮 + 自定义内容(无表格/分页/表单) | `SSkeletonLayout`(见 2.16,自带标题条与权限按钮) |\n| 普通列表页 | `SListLayout` |\n| 卡片列表 | `SListCardLayout`(卡片网格 + 三插槽,见 2.19) |\n| 列表 + 左侧树 | `SListTableTreeLayout`(左侧树容器类名必须是 `.side.s-side-tree`,见 3.5) |\n| 带高级搜索/高级表格的列表 | `SSuperListLayout`(列设置 + 高级筛选,见 2.20) |\n| 新增/编辑/详情(路由式) | `SFormLayout`(`#form` 插槽放 `SForm`,`#footer-callback` 收 `save`/`cancel`/`prev`/`next`) |\n| 表单作为弹窗内容 | `SModal`(不要套 `SFormLayout`) |\n| 后端下发字段的动态表单 | `SExtendFieldsForm`(`data` + `defaultValue`,ref 调 `validate/clearValidate/getModel`) |\n| 数据权限范围选择 | `SDataRangeTreeSelect`(`autoSysConfig` 托管系统 `dataScope` 配置) |\n\n### 2.2 全局属性 / 方法\n\n`$registerGlobalConfig` 执行后可用(`this.$xxx` / 模板 `$xxx` / `window.$xxx`):\n\n| 名称 | 说明 |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$registerGlobalConfig(config, pages)` | 初始化入口(见 5.2) |\n| `$utils` | 工具类集合:`$utils.env` / `$utils.ls` / `$utils.http` 及通用方法 |\n| `env` | 合并后的环境配置(= `$utils.env`) |\n| `$i18n` / `$l(name, key)` | 国际化(见 2.7)。挂在 `globalProperties` 上:**模板里直接用** `$l(\'xx\')`;`<script setup>` **脚本内**必须写 `window.$l(\'xx\')`(setup 作用域没有 `this`) |\n| `$theme` / `$staticRoutes` / `$pinia` | 主题对象 / 静态路由列表 / 用户 store 实例 |\n| `$modal` / `$message` / `$notice` / `$confirm` | antd 的 `Modal` / `message` / `notification` / `Modal.confirm`(列表组件按钮 api 分支会调 `this.$confirm`) |\n| `$push(path, query)` / `$open(...)` | 站内跳转 / 新窗口(自动拼 `VITE_APP_BASE_URL`) |\n| `$filter` / `$icons` / `$socket` | 日期格式化 / 图标集合 / websocket 封装。`$icons` 是 `@ant-design/icons-vue` 全量按 **Pascal 名**注册的映射(`InfoCircleOutlined`),**同时挂在 `window.$icons`**(供 `$utils.iconOf` 在非组件上下文取用)。`<a-icon type="info-circle">` 这类 antd v1 写法用 `$utils.iconOf(\'info-circle\')` 换算;`SIcon` 的 `name` 只吃 Pascal 名 |\n| `$getPdf({ el, title })` | 页面导出 PDF(老项目 `Vue.prototype.getPdf` 的 Vue3 版)。截图容器与文件名显式传:`<a-button @click="$getPdf({ el: \'#pdfDom\', title: htmlTitle })">导出</a-button>`。内部**动态 import** `html2canvas` + `jsPDF`,不点按钮不加载;A4 自动分页,返回 `Promise<boolean>`。可选 `fileName` / `scale` / `backgroundColor` / `beforeCapture` / `afterCapture` / `onError`。同时挂了无 `$` 的 `getPdf` 兼容老写法(默认容器 `#pdfDom`、标题取 `document.title`) |\n\n### 2.3 布局\n\n`packages/layouts/index.js`:`BasicLayout`(头部+侧边菜单+内容区)、`BlankLayout`、`UserLayout`(登录)、`RouteView`、`PageView`。\n\n`BasicLayout` 的高度链路(**业务布局组件必须与它对齐**,详见第三章):\n\n```text\n.basic-layout-common (100vh)\n→ .ant-layout\n→ .main-content\n→ .container (height = mainHeight = clientHeight - headerHeight)\n └─ 有页脚时再减 footerHeight(56)\n → router-view (height = contentHeight, overflow: hidden auto)\n → 业务布局组件(.list-layout / .form-layout,flex:1)\n```\n\n> `mainHeight` / `contentHeight` 用**真实 `header.offsetHeight`**(不是写死 58)计算,避免与实际渲染不一致产生溢出滚动条。\n\n### 2.4 路由\n\n**常量路由**(`packages/router/index.js`):\n\n| 路径 | 说明 |\n| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/login/index` | 登录页(默认基座,可被业务覆盖,见 5.3) |\n| `/login/:officeCode` | 同上,带单位编码进入(登录页把编码写进 `$utils.ls` 的 `officeCode`,后续登录沿用) |\n| `/user/qrCode`、`/user/forgotPassword`、`/user/activate` | 扫码登录 / 找回密码 / 账号激活三张独立页,父级 `/user` 带 `meta.public`,**登录前可达**;`/user/login` 重定向到 `VITE_APP_LOGIN_PATH`(见 2.10) |\n| `/workplace/index` | 默认首页(`VITE_APP_DEFAULT_PATH`,可被覆盖) |\n| `/workbench/index`、`/message/index` | 工作台 / 消息 |\n| `/docs`、`/components` | 内置文档 / 组件页(`public` 免登录、`hidden` 不进菜单) |\n| `/404`、`/403`、`/500`、`/:pathMatch(.*)*` | 错误页;通配渲染 404(**不用 redirect**,保证刷新动态路由不掉 404)。四者都挂在 `BasicLayout` 下,**只在内容区 `router-view` 内切换**,侧边菜单与顶栏保持不变 |\n\n> 错误页的触发规则、URL 参数、文案口径与改色方法见 [2.17 错误页](#docs-217错误页301403404500)。\n\n**静态路由**(`staticRoutes`,不依赖后端菜单):见 5.4。基座内置 `/docs`、`/components`。\n\n**动态路由**(`packages/router/generator-routers.js`):登录后按后端 `menus` 生成树,根节点 `BasicLayout`;叶子节点用 `item.hrefs` 匹配业务 `pages`(`import.meta.glob(\'@/views/**/*.vue\')` 的 key),匹配不到回退 404。注册在守卫中完成(内存标记,刷新重注册)。\n\n**守卫**:公开页(`meta.public`)直接放行;实时读 token;未登录跳登录;已登录访问登录页/根跳默认首页;取用户信息失败清理并回登录页(避免 pending)。URL 带 `code` 时在守卫里换取 token(见 5.8 权限与 6.1)。\n\n### 2.5 状态管理(pinia)\n\n`packages/store/user.js`(`useUserStore`):state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`;actions `Info()`(拉取并写 localStorage)、`setDynamicRouter()`、`setMenuOpenKeys()`;localStorage 持久化。\n\n### 2.6 工具类(`$utils`)\n\n| 模块 | 说明 |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$utils.env` | 环境配置对象 |\n| `$utils.ls` | 本地存储(命名空间 `VITE_APP_SYS_SERVER_NAME`) |\n| `$utils.http` | axios 实例(token/`client-id` 注入、响应解包、登录超时、文件下载) |\n| `parseAppUrl` / `innerRedirect` 等 | 站内地址拼 base(支持子路径),外部 http(s) 原样 |\n| `messageFormat(str, values)` | `{0}` / `{name}` 占位符替换,用于确认弹窗等文案 |\n| `filterSelectOption(iv, opt)` | antd4 版 `:filterOption`(读 `option.label` / `option.value`) |\n| `randomDrawerPlacement()` | 随机返回 `left` / `right` / `top` / `bottom`(源项目交互保留) |\n| `getTableHeight({ selector, offset })` | 列表页表格高度 = 窗口高 − 搜索区高 − 偏移(默认 `.table-page-search-wrapper` / `320`,不传参即老项目原行为)。**老项目固定高度撑表才用**,基座 `SListLayout` 走 flex 自适应 |\n| `iconOf(type)` | antd v1 `<a-icon type="info-circle">` 遗留写法的换算:kebab / snake / Pascal 入参 → 图标组件。用法 `<component :is="$utils.iconOf(\'info-circle\')" />` |\n| `hasAction(name)` | 按钮级权限**函数式**判断,与 `v-action` 同源;用于 `v-if` 里的「或 / 且」、算 `disabled` |\n| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等 |\n\n> ⚠️ **类型判断 ≠ 格式校验**:`$utils.isNumber` / `isInt` / `isDate` 是 `Object.prototype.toString` 类型判断(`$utils.isNumber(\'123\')` 恒 `false`),**不是**字符串格式校验。业务侧的正则版同名方法(如 `isNumber(str)` 用 `/^(?:-?\\d+|...)/`)**不可**按名字替换过来。\n>\n> 同理 `$utils.uuid(len)` 是纯随机串,与「时间戳 + 随机数」型 `getUUID()` 产出格式不同,涉后端主键时不可换。\n\n`v-action:xxx` 按钮级权限指令:`<a-button v-action="\'add\'">添加</a-button>`。\n\n- 内部直接调用 `$utils.hasAction(actionName)`,**指令与函数只有一套判定逻辑**\n- 数据源优先级:`permission`(**单数**,`router/index.js` 守卫写入的「当前路由按钮数组」)→ 取不到再回退 `permissions`(**复数**,`store/user.js` 写入的全量「路由 → 按钮」map)+ `CURRENT_ROUTER_KEY`\n- 匹配规则:`String(button_code) === String(actionName)`,**整体相等**(`add` 不会命中 `batchAdd`)\n- 函数式用法:`<a-button v-if="$utils.hasAction(\'add\') || $utils.hasAction(\'edit\')">`\n\n### 2.7 国际化\n\n语言包文件名统一为 `i18n.js`,放在模块的**一级文件夹**下,不带任何前缀,结构是扁平字典:\n\n```js\n// src/views/user/i18n.js -> 命名空间 user\nexport default {\n 取消: \'Cancel\'\n}\n```\n\n命名空间取 `views/` 或 `packages/` 之后的第一段目录名(`views/user/i18n.js` → `user`,`packages/components/i18n.js` → `components`)。构建期由 `import.meta.glob` 统一聚合,新增文件、新增目录都不用改任何代码。\n\n页面里**不用注册**也能翻译:`$l(\'中文\')` 会自动找该页面**所在目录**的 `i18n.js`(路由加载组件时按源文件路径打标 `__i18nNs`,取不到再用路由 path 首段)。需要强制指定别的命名空间时才显式注册:\n\n```js\nexport default {\n created() {\n this.useI18n(\'user\') // Options API,显式指定,优先级最高\n }\n}\n```\n\n```js\n// <script setup>:可显式传,也可不传(不传就按当前目录自动推断)\nconst { $l } = useI18n() // 自动\nconst { $l } = useI18n(\'user\') // 显式\n```\n\n`$l(name)` 查找顺序:**当前命名空间(显式注册 > 同目录 i18n > 路由首段)→ `components` 通用词 → 全局兜底字典(`packages/locales/lang/dict.js`)→ 原样返回 + `console.warn`(同一个词只提示一次)**。命名空间不存在时 `useI18n` 也会 `console.warn`,不阻断渲染。\n\n| 调用位置 | 写法 | 是否带命名空间 |\n| --------------------------------- | ------------------- | -------------------------------------- |\n| 模板 / 组件内 `this.$l(...)` | `{{ $l(\'取消\') }}` | 带,自动按上述优先级解析 |\n| 组件内 `const { $l } = useI18n()` | `$l(\'取消\')` | 带,同上 |\n| 组件外 JS(api / utils) | `window.$l(\'取消\')` | **不带**,只查 `components` + 全局字典 |\n\n排查用:控制台执行 `$i18nDebug()`,会打印已加载的全部命名空间、当前组件解析到的命名空间及其词条数;`$i18nNamespaces` 是命名空间全量对象。\n\n中文模式直接返回原文;英文模式查不到译文时原样返回中文并告警。antd 自身语言由 `a-config-provider` 的 `locale` 控制。\n\n### 2.8 主题\n\n定义只由基座维护:`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` 会被忽略。\n\n生效方式:\n\n1. **antd**:`a-config-provider` token(`colorPrimary`/`colorLink`)。\n2. **CSS 变量**:启动时把选中主题算成整套令牌写入 `:root`(主题色系 10 个 + 语义色 11 个 + 中性色 11 个),并内置工具类 `.s-theme-bg`、`.s-theme-color`、`.s-theme-border`、`.s-theme-border-top`、`.s-theme-icon-bg`。\n3. **body 类**:`theme-<VITE_APP_THEME_VALUE>`(如 `theme-blue`)。\n4. **菜单配色**:启动时按主题色推导(`light`)或固定 antd 黑(`dark`),**全部输出实色 `#rrggbb`,不含透明度**,写入 `:root` 的 `--s-menu-bg`、`--s-menu-sub-bg`、`--s-menu-text`、`--s-menu-text-hover`、`--s-menu-text-active`、`--s-menu-hover-bg`、`--s-menu-active-bg`、`--s-menu-active-text`,同时写入 `window.$menuTheme`(`reactive`,含 antd `Menu` token,`isLightBg` 标记实际明暗)。\n\n菜单默认 `light`(按主题色相推导浅色底:orange `#f9f1e1` / blue `#e1ebf9` / green `#e1f9ef`)。**具体色值只由基座控制**:业务只能通过 `VITE_APP_MENU_THEME` 选浅 / 深,色值写在业务 `.env` / `config.json` 里会被基座强制回填掉。**色板推导、系统深浅色跟随与锁定机制见 [2.18 菜单配色](#docs-218菜单配色侧边顶部)**。\n\n> `light` 下底色、悬停、选中、文字**全部**按主题色推导,切 `VITE_APP_THEME_VALUE` 整套跟着变,文字对比度按底求解仍 ≥ 4.6。默认还跟随系统深浅色(`VITE_APP_THEME_FOLLOW_SYSTEM`),系统切深色时菜单自动换黑。侧边菜单、顶部菜单(`VITE_APP_MENU_BAR: \'top\'`)、logo 明暗、顶栏文字色共用 `window.$menuTheme.isLightBg` 这一套判断。\n\n```css\n.my-box {\n color: var(--s-color);\n background: var(--s-bg-color);\n}\n```\n\n**完整令牌清单**(由 `packages/utils/theme-vars.js` 启动时写入 `:root`,组件与业务只用 `var(--s-*)`,不写字面色值):\n\n| 分组 | 令牌 | 默认值(blue) | 说明 |\n| -------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |\n| 主题色系 | `--s-color` | `#1677ff` | 主色,取 `VITE_APP_THEME` |\n| | `--s-light-color`、`--s-dark-color`、`--s-border-color`、`--s-bg-color` | `#6495ed`、`#00008b`、`#b0c4de`、`#f0f2f5` | 取主题定义 |\n| | `--s-color-hover` / `--s-color-active` | `#4592ff` / `#146be6` | 悬停(混白 20%)/ 按下(混黑 10%) |\n| | `--s-color-bg` / `--s-color-bg-hover` / `--s-color-border` | `#e8f1ff` / `#d5e7ff` / `#adcfff` | 选中浅底 / 悬停浅底 / 浅边框 |\n| 语义色 | `--s-color-success`、`--s-color-warning`、`--s-color-error`、`--s-color-info` | `#52c41a`、`#faad14`、`#ff4d4f`、`#1677ff` | 状态语义,不随主题变 |\n| | `--s-color-success-bg`、`--s-color-warning-bg`、`--s-color-error-bg` | `#f6ffed`、`#fffbe6`、`#fff1f0` | 状态浅底 |\n| | `--s-color-warning-light` / `--s-color-error-light` | `#ffc069` / `#ff7875` | 状态浅色变体(错误页插图) |\n| | `--s-color-warning-border` / `--s-color-error-border` | `rgba(250,140,22,.42)` / `rgba(245,34,45,.42)` | 状态半透明描边 |\n| 中性色 | `--s-text-color` | `#262626` | 主要文字 |\n| | `--s-text-color-regular` | `#595959` | 常规文字 |\n| | `--s-text-color-secondary`、`--s-text-color-disabled`、`--s-text-color-inverse` | `#8c8c8c`、`#bfbfbf`、`#ffffff` | 次要 / 禁用 / 反白 |\n| | `--s-border-color-base`、`--s-border-color-light`、`--s-border-color-split` | `#d9d9d9`、`#e8e8e8`、`#f0f0f0` | 边框三级 |\n| | `--s-bg-color-container` / `--s-bg-color-hover` | `#ffffff` / `#f5f5f5` | 容器底 / 悬停底 |\n| | `--s-mask-color` | `rgba(0,0,0,.45)` | 遮罩 |\n\n> 组件里已不再出现字面色值:主色相关走主题令牌,灰阶走中性令牌,状态走语义令牌。新增组件沿用同一套,不要再写 `#1677ff` / `#e8e8e8` / `rgba(0,0,0,.65)`。\n\n> 新增主题:基座 `VITE_APP_THEME` 加一套,业务 `VITE_APP_THEME_VALUE` 选它,antd 与 `var(--s-*)` 自动跟随。\n\n### 2.9 API / 页面组件 / 其它\n\n- `packages/api`:`login.js`(登录、`getCode`、`verify`、`rsaPublicKey`、`getLoginConfig` 等)、`common.js`、`upload.js`、`workbench.js`。\n- `packages/pages`:`login.vue`、`login-common/LoginForm.vue`、`workbench.vue`、`todo.vue`、`message.vue`、`403/404/500.vue`、`docs.vue`、`components-doc.vue`。\n- 静态资源 `packages/static/*`;样式 `packages/style/*`;antd 图标、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.\\* 等已内置。\n\n### 2.10 登录 / 单点\n\n- 登录页 `/login/index`:账号密码登录;登录失败达 `getLoginConfig` 策略(`enabled` + `codeThreshold`)时出现**图片验证码**(`/user/verify`),`verificationCode` 原文提交 + `verificationCodeId`。\n- 单点回调:URL 带 `code` 时由**守卫**调 `getCode(code)` 换 token → 存 `$utils.ls` → 去掉 code 整页刷新(与参照项目一致)。\n- 关联配置:`VITE_APP_CLIENT_ID` 必须等于业务在认证中心的 client;接口网关用 `VITE_APP_PORTAL_SERVER_NAME`。\n\n**四套登录主题**(`VITE_APP_LOGIN_PATH_THEME`,取值 `1`~`4`,未配置或非法值回落 `1`):\n\n`packages/pages/login/index.vue` 只负责取主题编号、透传 `logo`/`sysName`、渲染语言切换,具体版式在 `login-themes/` 下的页面级组件里,**互不影响、可单独改**。\n\n| 编号 | 组件 | 版式 |\n| ---- | --------------------------- | ------------------------------------------------------------------------ |\n| 1 | `LoginTheme1.vue` | 左右分栏:左侧 `login-cover.png` + logo + 系统名,右侧表单 |\n| 2 | `LoginTheme2.vue` | 整屏 `login-cover-right.png`,表单靠左(`padding-left: 336px`) |\n| 3 | `LoginTheme3.vue` | 整屏 `login-cover-center.png`,表单居中(**web-config 默认值**) |\n| 4 | `LoginTheme4.vue` | 左深蓝品牌区 + 右白卡片,门户运营端同款(完整版,见下) |\n\n**主题 4 能力清单**(`login-themes/LoginTheme4.vue`):\n\n- 账号密码登录 + 记住我(存 `LOGIN_ACCOUNT`,只存账号不存密码)。\n- 图形验证码:登录失败达 `getLoginConfig` 阈值后出现,点击图片刷新。\n- 账号锁定倒计时:后端返回 `lockUser`(`lockEndTime`/`nowTime`)后按钮进入 `a-statistic-countdown`,结束前禁用登录。\n- 「激活账号」入口:由 `getSysAccountConfig` 的 `defaultActivateAccount` 控制显隐。\n- 「忘记密码」「扫码登录」:跳基座内置的 `/user/forgotPassword`、`/user/qrCode`。\n- 单位编码:`/login/:officeCode` 进入时写入 `$utils.ls` 的 `officeCode`。\n- 登录成功后:写 `token` / `USER-TOKEN`;带 `redirect_client_id` 时按客户端列表跳 `sso.html` 做客户端授权,否则回 `VITE_APP_DEFAULT_PATH`。\n- 右侧表单区用 **flex 弹性居中**(`align-items: safe center` + `justify-content: center`)。不用 `overflow-y: auto`:父级 `.login-page` 是 `overflow: hidden`,靠滚动救不了;`safe center` 让视口装不下时退化成顶部对齐,卡片顶部不会被顶出可视区。\n\n**登录辅助页**(`packages/pages/login/`,均为 `meta.public`,登录前可达):\n\n| 路由 | 组件 | 说明 |\n| ---------------------- | -------------------- | ---------------------------------------------------------------------------------------- |\n| `/user/qrCode` | `qr-code.vue` | 扫码登录:`qrLogin/generate` 取 key,`a-qrcode` 渲染,有效期倒计时,过期遮罩 + 刷新 |\n| `/user/forgotPassword` | `forgot-password.vue` | 找回密码四步:选择方式 → 填账号 → 验证码校验(拿临时 token)→ 设新密码;密码策略取 `sysPwdConfig` |\n| `/user/activate` | `activate.vue` | 账号激活四步:身份核验(+图形验证码)→ 短信/邮箱验证码 → 设密码(强度条)→ 完成信息卡 |\n| `/user/login` | — | 重定向到 `VITE_APP_LOGIN_PATH`,供三张页面里的「返回登录」统一跳转 |\n\n**账号类接口**统一在 `packages/api/account.js`(登录前白名单链路,走 `VITE_APP_PORTAL_SERVER_NAME`):\n\n| 方法 | 说明 |\n| --- | --- |\n| `getSysAccountConfig` | 激活入口开关(`sysAccountConfig/listByActivate`) |\n| `getPwdConfig` | 密码策略(`sysPwdConfig/getFirstData`) |\n| `getLoginQrCodeKey` | 扫码登录 key(`qrLogin/generate`) |\n| `getValidationCodeWithoutToken` | 找回密码发送验证码 |\n| `checkValidationCodeWithoutToken` | 找回密码校验验证码 → 临时 `access_token` |\n| `updatePasswordWithoutToken` | 用临时 token 重置密码(账号/密码需 Base64,token 走 `user-token` 头) |\n| `checkUseInfo` | 激活身份核验 |\n| `getActivateValidationCode` | 激活发送验证码 |\n| `checkActivateValidationCode` | 激活校验验证码 |\n| `activateUpdatePassword` | 激活设置新密码 |\n\n**SSO 静态资源已收编进基座**:源在 `packages/sso/`(`sso.js` / `sso.html`),随 npm 包分发(`files` 加 `sso`,build 拷 `dist/sso`)。业务项目**不再维护 `public/` 下的 sso 文件**,只需在 `vite.config.js` 里:\n\n```js\nimport ssoPlugin from \'sapit-ui-plus/vite-plugins/sso-plugin.js\'\nssoPlugin()\n```\n\ndev 由插件中间件提供(注册在内部中间件前,用包内版本遮蔽 `public`)。`sso.html` 换token 读的是**同源 localStorage**(vue-ls 包装),跨 origin 的平台 sso 不能直接用。\n\n> `redirect_uri` 三种处理(`sso.js`):\n>\n> 1. 含 `{token}` → 用本地 token 直接替换回跳,不换 code。\n> 2. **跳回当前应用自身**(`client_id` = 本应用自己的 client,`redirect_uri` 同源、且无 `{code}` 占位符)→ 账密登录场景,本地已有登录态,**不调用单点**(不校验授权、不换 code),直接回跳。\n> 3. **第三方跳转**(功能模块弹窗跳别的 client / 系统)→ 走完整授权码流程:`authorizationCodeValidate` 校验 + `oauth2/code` 换码;有 `{code}` 就替换,无占位符则自动追加 `?code=xxx`。\n>\n> 「当前应用自己的 client」用本应用 base 定位 namespace(`loginHref` 为锚点)精确读取,不走 key 后缀模糊匹配 —— 同 origin 多应用共用 localStorage 时才不会取到别的应用的 `clientId`。\n\n### 2.11 SImportModal 通用批量导入弹窗\n\n三步式导入:**上传文件 → 数据预览(可编辑/删除行)→ 导入结果(含异常数据导出)**。文件限制:`.xls/.xlsx`、≤ 500KB。\n\n```vue\n<s-import-modal\n ref="importModalRef"\n :upload-url="IMPORT_UPLOAD_URL"\n :columns="importColumns"\n :apis="importApis"\n :type-select="importTypeSelect"\n @reload="handChange"\n/>\n\n<script setup>\nimportModalRef.value.show() // 打开(内部会重置状态)\n\nconst importApis = { templateDownload, importPreview, importData, exportExceptionData }\nconst importColumns = [{ title: \'设备SN码\', dataIndex: \'sn\', width: 150 }]\n// 可选:导入时附带的业务参数下拉,选中值以 extraKey 随各接口一起提交\nconst importTypeSelect = computed(() => ({\n options: [{ label: \'摄像头\', value: \'1\' }],\n placeholder: \'选择设备分类\'\n}))\n<\/script>\n```\n\n| props | 类型 | 默认值 | 说明 |\n| ------------ | --------------- | ---------------- | ----------------------------------------------------------- |\n| `value` | Boolean | `false` | 显隐(`v-model:value`) |\n| `title` | String | `\'批量导入\'` | 弹窗标题 |\n| `width` | String / Number | `1000` | 弹窗宽度 |\n| `uploadUrl` | String | `\'\'` | 上传地址(完整网关地址,如 `/monitor/DeviceInfo/Uploader`) |\n| `columns` | Array | `[]` | 预览/结果表格列 `[{ title, dataIndex, width }]` |\n| `apis` | Object | `{}` | 四个导入接口(见下) |\n| `typeSelect` | Object | `null` | `{ options, placeholder, loading }`,不需要业务参数时不传 |\n| `extraKey` | String | `\'deviceTypeId\'` | `typeSelect` 选中值提交时的字段名 |\n\n| events | 说明 |\n| -------------- | --------------------------- |\n| `update:value` | 显隐变化(`v-model`) |\n| `reload` | 导入成功/关闭后需要刷新列表 |\n\n| methods(ref 调用) | 说明 |\n| ------------------- | ------------------ |\n| `show()` | 打开弹窗并重置状态 |\n\n接口约定(均返回 Promise,组件内部兼容 `{ code, data }` 与直接返回数据两种格式):\n\n| 接口 | 入参 | 返回 |\n| --------------------- | ------------------------------ | ---------------------------------------------------- |\n| `templateDownload` | `{ ...extraParams }` | `{ url }`(组件用 `url` 触发下载) |\n| `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` |\n| `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` |\n| `exportExceptionData` | `{ list, ...extra }` | `{ url }` |\n| 上传(内部) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }`(后续接口回传 fileName) |\n\n> ⚠️ `SImportModal` 是**三步式**(上传 → 预览编辑 → 结果/异常导出)。\n> 业务项目里如果存在「选文件即导入」的**单步式**导入组件(如 hy-monitor 的 `views/people/components/ImportModal.vue`、`views/basicData/components/ImportModal.vue`),\n> 两者在布局、API、事件、调用页契约上都不同,**不能当同一个组件替换**,仍按各自实现保留。\n\n### 2.12 SDataRangeTreeSelect 数据权限范围树\n\n数据权限(组织/校区/单位)范围选择,内部走 `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode(\'dataScope\')`。\n\n```vue\n<s-data-range-tree-select v-model:value="ids" :auto-sys-config="true" />\n```\n\n常用 props:`value`(id 数组) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup`(`\'1\'`组织 `\'2\'`校区 `\'3\'`单位,可传数组)/ `showOnlyOrganization` / `treeSelectData`(传数组则不请求接口)/ `isDataScopeFilter` / `autoSysConfig` / `defaultValue`。\nevents:`update:value`、`change`(均输出 **id 数组**)。\n\n> ⚠️ 模板写死了 `label-in-value` + `tree-check-strictly`,antd 要求内部 `value` 必须是 `{ label, value }` 对象数组。\n> 因此**回显必须先 `getOfficeByIds(ids)` 转成节点对象**再赋值,直接赋裸 id 字符串会触发 `Invalid prop value` 警告且输入框显示成裸数字 ID。\n\n### 2.13 SExtendFieldsForm 动态扩展字段表单\n\n后端下发字段配置(`fillModeConfig` 为 JSON 串,含 `showType` / `config`),前端按配置渲染。\n\n```vue\n<s-extend-fields-form ref="extRef" :data="fields" :default-value="values" type="edit" :cols="2" />\n<script setup>\n// ref 暴露三个方法\nextRef.value.validate() // Promise<boolean>\nextRef.value.clearValidate()\nextRef.value.getModel() // [{ fieldCode, value }](对象值已 JSON.stringify)\n<\/script>\n```\n\n| props | 类型 | 默认值 | 说明 |\n| -------------- | ------ | ------- | ---------------------------------------------------- |\n| `data` | Array | `[]` | 扩展字段定义(`fieldCode/fieldName/fillModeConfig`) |\n| `type` | String | `\'add\'` | `add` / `edit` / `view`(`view` 不校验) |\n| `defaultValue` | Array | `[]` | 编辑态回显值 `[ { fieldCode, value } ]` |\n| `cols` | Number | `2` | 每行列数(非整行字段按 `100/cols%` 宽) |\n| `labelWidth` | String | `auto\'` | label 宽度 |\n\n自动占满整行的 `showType`:`textarea`、`upload`、`select` 且 `config.multiple`。默认值按 `showType` 转类型:`datePicker` → dayjs 对象、`number` → Number、`select` 多选 → 逗号切数组。\n\n### 2.14 SChooseUser 选择人员弹窗(带数据权限)\n\n弹窗式人员选择:左侧组织树 + 右侧人员列表(头像/姓名/工号 + 单位),搜索区内置**人员类型过滤**(全部/教职工/学生/校外人员),支持单选/多选、滚动分页加载、全选/反选、多选时右侧已选清单。确认后**自动关闭弹窗**。\n\n与 `SUserSelect` 的差异(选型依据):\n\n| 对比项 | `SUserSelect` | `SChooseUser` |\n| -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |\n| 形态 | 只读输入框 + 弹窗一体 | 纯弹窗,显隐由业务控制 |\n| 数据权限 | 组织树/列表接口不带数据权限 | 走 `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`,**按登录人权限过滤** |\n| 人员类型 | 无过滤 | 内置教职工/学生/校外人员过滤 |\n| 取值契约 | `v-model:value` 直接绑 id(单选字符串/多选数组) | `v-model:value` 控显隐;`v-model:selectedIds`/`selectedId` 绑已选 id;`@callback` 回抛**选中对象列表** |\n\n```vue\n<s-choose-user\n v-model:value="userScopeVisible"\n v-model:selectedIds="userScopeIds"\n :multiple="true"\n @callback="userScopeCallback"\n/>\n<script setup>\n// 确认(单选/多选): payload = [{ id, name, cover, userid, company, department }](单选也是单元素数组)\n// 取消/关闭: payload = undefined\nconst userScopeCallback = (payload) => {\n if (payload) userNames.value = payload.map((u) => u.name).join(\',\')\n userScopeVisible.value = false\n}\n<\/script>\n```\n\n| props | 类型 | 默认值 | 说明 |\n| ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- |\n| `value` | Boolean | `false` | 弹窗显隐(`v-model:value`) |\n| `title` | String | `\'选择人员\'` | 弹窗标题 |\n| `multiple` | Boolean | `false` | 多选(右侧出现已选清单) |\n| `searchPlaceholder` | String | `\'按姓名、工号/学号、手机号搜索\'` | 搜索框占位 |\n| `required` | Boolean | `false` | 确认时未选则提示且不关闭 |\n| `selectedIds` | Array | `[]` | 多选回显 id 数组(`v-model:selectedIds`),内部 `getBUseryIds` 拉对象渲染已选 |\n| `selectedId` | String | `\'\'` | 单选回显 id(`v-model:selectedId`),内部 `getUserById` 拉对象 |\n\n| events | 说明 |\n| -------------------- | ----------------------------------------------------- |\n| `update:value` | 关闭弹窗(确认/取消均自动置 `false`,业务无需手动关) |\n| `update:selectedIds` | 已选 id 数组双向绑定 |\n| `update:selectedId` | 单选 id |\n| `callback` | 确认回抛选中对象**数组**;关闭时无参 |\n\n> ⚠️ 接口全部内置在基座 `packages/api/common.js`(`findUsersWithAuth` = `/user/users/authorized` 等),业务无需传接口;无后端的预览环境树/列表为空属正常。列表中 `userid` 展示的是 `loginName`(工号/学号)。\n\n### 2.15 SBelowChoosePosition 选择岗位弹窗\n\n弹窗式**岗位**选择(源自业务项目 `/components/BelowChoosePosition`,已收编进基座):左侧树用 `getBelowUnit` 一次性拉「根节点及其以下所有单位」的完整树(范围由 `rootId` 决定),右侧列表查岗位(`findJobs`),支持单选/多选。\n\n与基座其它选择器的差异:`SOfficeSelect`/`SUserSelect` 查组织/人员且左树递归懒加载;本组件查**岗位**、左树一次性全量。**确认后不自动关闭弹窗**,业务需在 `callback` 中手动关闭(与源项目行为一致)。\n\n```vue\n<s-below-choose-position\n v-model:value="visible"\n v-model:selectedIds="positionIds"\n multiple\n :root-id="campusId"\n @callback="onCallback"\n/>\n<script setup>\n// 确认(多选): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }\n// 确认(单选): payload = { selected: { id, name, ... } }\n// 取消/关闭: payload = false\nconst onCallback = (payload) => {\n if (payload && payload.selectedList) {\n names.value = payload.selectedList.map((i) => i.name).join(\',\')\n }\n visible.value = false // 确认后组件不自动关闭,必须手动关\n}\n<\/script>\n```\n\nprops 与 `SChooseUser` 相同(`title` 默认 `\'选择岗位\'`、`searchPlaceholder` 默认 `\'按岗位名称、岗位编号搜索\'`),另有一个专有 prop:\n\n| props | 类型 | 默认值 | 说明 |\n| -------- | ------ | ------ | --------------------------------------------------------------------- |\n| `rootId` | String | `\'\'` | 左树根节点 id,决定树的数据范围;变化时自动重载左树,未传按 `\'-1\'` 查 |\n\n| methods(ref 调用) | 说明 |\n| ---------------------- | ------------------ |\n| `initLeftTreeData(id)` | 手动重载左侧组织树 |\n\n| events | 说明 |\n| -------------------- | ------------------------------------------------------------------- |\n| `update:value` | 仅取消时置 `false`;**确认不关窗**,业务手动关 |\n| `update:selectedIds` | 已选岗位 id 数组双向绑定(回显走 `getPositionByIds`) |\n| `update:selectedId` | 单选 id(回显走 `getPositionById`) |\n| `callback` | 确认回抛 `{ selectedList }` / `{ selected }` 对象;关闭回抛 `false` |\n\n> ⚠️ `callback` 载荷形态与 `SChooseUser` **不同**(对象 `{ selectedList }` vs 数组),且确认后关窗行为相反,两个组件的 callback 写法不可混用。\n\n---\n\n### 2.16 SSkeletonLayout 骨架布局(标题 + 按钮组 + 内容区)\n\n> 2026-10-28 新增。用于页面级「标题条 + 操作按钮 + 内容区」的骨架外观,与 `SListLayout` / `SFormLayout` 同级但更轻:**不带表格、不带表单、不带分页**,内容区完全由插槽决定。\n\n```vue\n<s-skeleton-layout\n :title="$l(\'采集任务\')"\n :buttons="[\n { key: \'add\', name: \'新增\', icon: true },\n { key: \'remove\', name: \'删除\', disabled: true },\n { key: \'export\', name: \'导出\', icon: \'DownloadOutlined\' }\n ]"\n bg-color="#fff"\n @btnCallback="onBtnClick"\n>\n <div class="my-content">...</div>\n <template #otherBtns><a-button>自定义</a-button></template>\n <template #other>底部内容</template>\n</s-skeleton-layout>\n```\n\n| props | 类型 | 默认 | 说明 |\n| -------------------- | ------ | ---- | -------------------- |\n| `title` | String | — | **必填**,标题条文本 |\n| `buttons` | Array | `[]` | 按钮配置数组,见下表 |\n| `buttons` 每项字段: |\n\n| 字段 | 类型 | 说明 |\n| ---------- | ----------------- | ------------------------------------------------------------------------------------------ |\n| `key` | String | 唯一键,点击时回抛该值;`\'add\'` 时按钮自动为 `primary` |\n| `name` | String | 按钮文案(内部走 `$l`,可直接写源中文) |\n| `icon` | String \\| Boolean | 字符串 = 图标组件名(如 `\'PlusOutlined\'`);`true` = 按 `key` 查内置 iconMap;缺省不出图标 |\n| `action` | String | `v-action` 权限码,缺省用 `key`(会真正做权限过滤,无权限时按钮被移除) |\n| `show` | Boolean | 默认 `true`;`false` 时 `v-show` 隐藏(仍占位、仍注册权限) |\n| `disabled` | Boolean | 置灰 |\n| `type` | String | 覆盖 `a-button` 的 `type` |\n\n| slots | 说明 |\n| ----------- | --------------------------------- |\n| 默认 | 内容区(`.skeleton-layout-main`) |\n| `otherBtns` | 按钮组右侧追加内容 |\n| `other` | 底部区域 |\n\n| events | 说明 |\n| ------------- | ---------------------- |\n| `btnCallback` | 回抛被点击按钮的 `key` |\n\n| methods(ref 调用) | 说明 |\n| ------------------- | ---------------------------------------------------------- |\n| — | **无**。高度由 flex 自动分配,不需要业务调任何方法(见下) |\n\n内置 iconMap 的 key:`add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`。\n\n> **高度实现(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 监听**,窗口缩放 / 侧栏折叠自动跟随。\n>\n> 前提:父容器要有确定高度。基座 `BasicLayout` 的 `router-view` 已带 `:style="{ height: contentHeight + \'px\' }"`,会透传到页面根组件,通常无需额外处理;若页面外层是自己写的 `height:auto` 容器,需给该容器一个确定高度。\n>\n> 旧版本的 `initLayoutHeight()` 方法**已移除**,`layoutHeight` 也不再暴露(原实现是 `parentNode.offsetHeight - 76` 且只在 `mounted` 算一次)。\n\n### 2.17 错误页(301 / 403 / 404 / 500)\n\n基座内置三张错误页,**同一张页面承接「页面本身出错」和「接口报错」两种来源**,靠 URL 上的 `?api=` 区分文案。\n\n| 路径 | 组件 | 状态码来源 | 主色 |\n| ------ | --------------- | ----------------------------------------------- | ----------------------- |\n| `/403` | `pages/403.vue` | 接口 403 无权限、接口 301 地址变更、页面无权限 | 橙色 `#fa8c16` |\n| `/404` | `pages/404.vue` | 路由没命中(通配 `/:pathMatch(.*)*`)、接口 404 | 主题色 `var(--s-color)` |\n| `/500` | `pages/500.vue` | 仅可直接访问;**接口 5xx 不跳转**,仍走通知 | 红色 `#f5222d` |\n\n**渲染位置**:`buildErrorRoute()` 把三页统一包在 `BasicLayout` 下,作为 `children: [{ path: \'\' }]` 的嵌套子路由——跳转时**只替换内容区 `router-view`**,侧边菜单、顶栏、页脚保持原样。页面 404(通配)与接口 404 共用同一套结构,表现完全一致。\n\n**免登录**:`/403`、`/404`、`/500` 带 `meta.public`(接口报错时 token 可能已失效,不能让它再卡在登录守卫里);通配 `/:pathMatch(.*)*` **不带** `public`,未登录访问不存在的地址仍回登录页。\n\n**接口报错的映射**(`packages/utils/request.js`):\n\n| HTTP 状态 | 行为 | 目标 URL |\n| -------------- | --------------------------------- | ------------------------------------------ |\n| 301 | 跳 403 页,文案「接口地址已变更」 | `/403?api=<接口>&status=301&from=<出错页>` |\n| 403 | 跳 403 页,文案「接口无权限」 | `/403?api=<接口>&status=403&from=<出错页>` |\n| 404 | 跳 404 页,文案「接口不存在」 | `/404?api=<接口>&status=404&from=<出错页>` |\n| 其它(含 5xx) | **不跳**,照旧弹通知 | — |\n\n**URL 参数**:\n\n| 参数 | 含义 |\n| -------- | ---------------------------------------------------------------------- |\n| `api` | 报错接口地址。**有它即切「接口口径」文案**;页面自身出错时不带 |\n| `status` | 原始状态码;`301` 单独走「接口地址已变更」这一档文案 |\n| `from` | 出错来源页面地址(已剥掉 `VITE_APP_BASE_URL`),页面显示为「出错地址」 |\n\n文案口径:\n\n| 来源 | 403 页 | 404 页 |\n| ---------------- | -------------- | ---------- |\n| 页面(无 `api`) | 页面权限不足 | 页面走丢了 |\n| 接口(有 `api`) | 接口无权限 | 接口不存在 |\n| 接口 301 | 接口地址已变更 | — |\n\n两个按钮:「返回首页」走 `VITE_APP_DEFAULT_PATH`(默认 `/workplace/index`);「返回上一页」用 `router.back()`,没有历史记录时自动退回首页,避免点了没反应。\n\n**跳过跳转**(后台轮询、辅助接口等非主流程请求,避免一条辅助接口失败把整页顶掉):\n\n```js\n// 第三个参数支持 { skipErrorPage: true }(也可写在请求 meta 里)\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\n```\n\n**并发与兜底**:错误页跳转是**串行排队、后到优先**,同时来 403 和 404 不会互相取消;导航结束后回读 `currentRoute` 校验是否真的到达(兼容目标被 redirect 改写路径),没到达重试 2 次,仍失败才 `location.replace` 整页兜底,保证用户一定看到错误页。已经在错误页且已带 `api` 时不再覆盖,防止错误页自身挂的辅助接口把真实原因顶掉。\n\n**改颜色 / 改文案**:\n\n- 文案全部走 i18n 词条(`packages/pages/i18n.js`,命名空间 `pages`),改词条即改三页文字。\n- 403 / 500 各自在根节点定义了 `--e-color`(主色)、`--e-light-color`(浅色)、`--e-border-color`(虚线边框),业务侧用同名变量覆盖即可换色;404 用主题色 `--s-color`,跟随 `VITE_APP_THEME_VALUE`。\n- 三页根节点都是 `height:100%; overflow:hidden`,装饰光斑包在 `__deco` 里自裁,超出部分只在卡片内部滚动,不会撑出页面滚动条。\n\n> 错误页挂在 `BasicLayout` 下,布局层会带发 `getSystemIcon` 与消息计数两个请求。这两个接口若是本身会失败的辅助接口,建议加 `skipErrorPage: true`,否则可能从 403 再跳到 404。\n\n### 2.18 菜单配色(侧边 / 顶部)\n\n菜单色板**由主题色推导**(`light`)或**固定 antd 黑**(`dark`),启动时 `packages/utils/menu-theme.js` 输出实色 `#rrggbb`(**不含 rgba / 透明度**),落到 `:root` 的 `--s-menu-*`,同时挂到 `window.$menuTheme`(含 antd `Menu` token 与 `isLightBg`)。改 `VITE_APP_THEME_VALUE` 换主题色,整套菜单跟着变,不再是写死的淡蓝。\n\n| 部位 | CSS 变量 | `light`(orange 默认) | `light`(blue) | `light`(green) | `dark` |\n| -------------- | ---------------------------------------------- | ---------------------- | --------------- | ---------------- | --------------------- |\n| 一级菜单底 | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` |\n| 子菜单展开区 | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` |\n| 悬停项 | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` |\n| 选中块 | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500`(主题主色) |\n| 普通文字 | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` |\n| 悬停文字 | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` |\n| 选中文字 | `--s-menu-text-active`、`--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` |\n| 分组标题文字 | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` |\n| `isLightBg` | — | `true` | `true` | `true` | `false` |\n\n> 三列 `light` 是**同一套规则**在不同主题色下的输出(`VITE_APP_MENU_BG: \'theme\'`):色相取主题色、饱和度受 `_BG_SATURATION` 限制、亮度由 `_BG_LIGHTNESS` 定,文字色按对比度求解(≥ 4.6)。`dark` 的底色固定 antd 黑,不读 `VITE_APP_MENU_BG`,只有选中块跟主题色。\n\n**跟随系统深浅色**\n\n`VITE_APP_THEME_FOLLOW_SYSTEM`(默认 `true`)由 `packages/utils/color-scheme.js` 处理:监听 `prefers-color-scheme`,系统切深色时**立即**把菜单按 `dark` 重算、中性色令牌换成暗色版、`body` 加 `scheme-dark`,切回浅色全量还原 —— 运行时生效,不用刷新。\n\n| 令牌 | 浅色 | 深色 |\n| --------------------- | ------------------- | ----------------------- |\n| `--s-text-color` | `#262626` | `#e8e8e8` |\n| `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` |\n| `--s-bg-color-container` | `#ffffff` | `#1f1f1f` |\n| `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` |\n| `--s-color-warning-bg` | `#fffbe6` | `#2b2413`(语义浅底压暗) |\n\n> ⚠️ 暗色令牌只对**用 `var(--s-*)` 取色**的地方生效。业务页面里硬编码的 `background: #fff` 不会自动变暗,要适配深色得换成 `var(--s-bg-color-container)`;也可以直接用 `body.scheme-dark` 写自己的覆盖。\n> 关掉跟随(`VITE_APP_THEME_FOLLOW_SYSTEM: false`)后深浅固定按 `VITE_APP_MENU_THEME` 走,业务本来配 `dark` 的不受影响。\n\n**业务只能选模式,不能改颜色**\n\n| 配置 | 默认 | 业务可否覆盖 | 说明 |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------ | ------------------------------------------ |\n| `VITE_APP_MENU_THEME` | `light` | ✅ | `light` 跟主题色的浅色系 / `dark` 黑色 |\n| `VITE_APP_MENU_BAR` | `left` | ✅ | `left` 侧边 / `top` 顶部(布局项) |\n| `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | ✅ | 是否跟随系统深浅色(`prefers-color-scheme`)|\n| `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 个颜色 / 调色键,一律被基座回填 |\n\n锁定机制:`packages/config/web-config.js` 导出 `menuColorKeys`(上表 ❌ 的 11 个键),`packages/index.js` 在 `registerGlobalConfig` 里**于 `loadRemoteConfig()` 合并之后**按清单把 `env` 中这些键强制回填成基座默认值。因此业务 `.env`、`src/config/web-config.js`、部署目录 `config.json` 三处写的菜单颜色全部无效,所有业务项目的菜单与基座 demo 完全一致。\n\n> 想临时验证「业务传色确实无效」:在业务 `config.json` 里写 `"VITE_APP_MENU_BG": "#ff0000"`,刷新后菜单仍是按主题色推导的那套值。\n\n**要改整套色板**(基座维护,不是单个业务能自己改的事):\n\n1. 色值:改 `packages/config/web-config.js` 的 `VITE_APP_MENU_*` 默认值;\n2. 推导规则:`light` 分支在 `packages/utils/menu-theme.js`(`dark` 分支固定黑色体系,不读 `VITE_APP_MENU_BG`);\n3. CSS 兜底:同步改 `packages/style/theme.less` 的 `--s-menu-*`;\n4. 重新打包基座 → 业务更新 `sapit-ui-plus`(见 4.1)。\n\n> 注意事项\n>\n> 1. `light` 下把 `VITE_APP_MENU_BG` 配成 `dark` 会被忽略并告警(黑底属于 `dark` 模式),仍按浅色推导。\n> 2. 单项颜色覆盖只对 `light` 生效,`dark` 保持纯黑体系,不会出现「黑底 + 淡蓝子菜单」。\n> 3. 业务样式不要写死 `#001529`、`rgba(255,255,255,.1)` 这类菜单色,直接 `var(--s-menu-*)`。\n> 4. 侧边菜单、顶部菜单(`VITE_APP_MENU_BAR: \'top\'`)、logo 明暗、顶栏文字色共用 `window.$menuTheme.isLightBg` 判断,不看 `VITE_APP_MENU_THEME` —— 系统深色跟随会改写它,所以判断必须走这个字段。\n> 5. `window.$menuTheme` 是 `reactive` 对象:深浅色切换时只改属性不换引用,`SSideMenu` 的 `computed` 读 `window.$menuTheme.token` 会自动重算,antd `Menu` token 无需手动刷新。\n\n### 2.19 SListCardLayout 卡片列表布局\n\n与 `SListLayout` 同一套骨架(标题条 + 查询区 + 分页),中间换成卡片网格。卡片正方形、圆角 8px,头部 / 内容 / 底部三段全部由插槽控制。\n\n```vue\n<s-list-card-layout title="卡片列表" :column="5" :load-data="loadData" @card-action="onCardAction">\n <!-- 头部:不传则取数据项 title,title 也为空则不渲染 header -->\n <template #cardHeader="{ item }">{{ item.title }}</template>\n\n <!-- 内容区:完全自定义,作用域含 item / index -->\n <template #default="{ item, index }">\n <div>名称:{{ item.name }}</div>\n </template>\n\n <!-- 底部:不传则为默认按钮区(编辑 / 删除),传了则完全替换 -->\n <template #cardFooter="{ item }">\n <a-button type="link" size="small" @click="edit(item)">编辑</a-button>\n </template>\n</s-list-card-layout>\n```\n\n| 参数 | 类型 | 默认 | 说明 |\n| ----------------- | ----------------- | ----------------------------- | ------------------------------------------------------ |\n| `title` | String | 必填 | 标题条文字 |\n| `column` | Number / String | `5` | 每行卡片数,内部 `repeat(column, 1fr)` |\n| `loadData` | Function | 必填 | `({ pageNo, pageSize }) => { list, total }` |\n| `rowKey` | String / Function | `\'id\'` | 卡片 key;字段 / 函数取不到时退回下标 |\n| `buttons` | Array | 添加 / 批量删除 / 导入 / 导出 | 与 `SListLayout` 同构(`name/key/show/type/icon/api`) |\n| `showPagination` | Boolean | `true` | 是否显示分页 |\n| `pSize` | Number / String | `20` | 默认每页条数 |\n| `pageSizeOptions` | Array | `[\'10\', \'20\', \'40\', \'80\']` | 每页条数可选项 |\n\n| 插槽 | 作用域 | 说明 |\n| ------------------------------------------------------------------------------------ | ----------------- | -------------------------------------------------------- |\n| `default` | `{ item, index }` | 卡片内容区,完全自定义 |\n| `cardHeader` | `{ item, index }` | 卡片头部;不传用 `item.title`,两者都空则不渲染 header |\n| `cardFooter` | `{ item, index }` | 卡片底部;不传为默认「编辑 / 删除」,点击抛 `cardAction` |\n| `filter` / `filterMore` / `desc` / `tabs` / `tree` / `empty` / `other` / `otherBtns` | 同 `SListLayout` | 与普通列表布局一致 |\n\n事件:`cardAction(key, item, index)`(`key` 为 `edit` / `delete`)、`btnCallback(key, selections)`、`reset`。`ref` 上可调 `reload(forceFirst)` / `fetchList()`。\n\n**样式约定**(都写在组件内 `scoped`,类名统一 `s-card-*` 前缀,避免误伤业务里的通用 `card-*`):\n\n| 类名 | 说明 |\n| ------------------- | ------------------------------------------------- |\n| `s-card-grid` | `display:grid` + `gap:12px`,列数由 `column` 决定 |\n| `s-card-item` | `aspect-ratio: 1/1` 正方形 + `border-radius: 8px` |\n| `s-card-header` | 头部,单行超出省略 |\n| `s-card-body` | 内容区,撑满剩余高度,超出内容在卡片内部裁切 |\n| `s-card-footer` | 底部按钮区,`min-height:36px`,左右两端对齐 |\n| `s-card-empty` | 空态,`grid-column: 1 / -1` 跨满整行 |\n| `s-card-pagination` | 分页条,高度从卡片区里扣掉,避免双滚动条 |\n\n**取数归一化**:`list`(或 `data`)取行、`total` / `pagination.total` / `totalCount` 取总数、`pageNo` / `pageNum` / `pagination.current` 回写当前页;接口异常只 `console.warn` 并清空,不会一直转圈。切每页条数时统一在 `change` 里判断,避免同一动作发两次请求。\n\n### 2.20 SSuperListLayout 高级列表(列设置 + 高级筛选)\n\n在 `SListLayout` 基础上多两个抽屉:右上角「高级表格」改列、「高级搜索」加条件。两者都是**草稿 + 确定生效**:抽屉里改的是副本,点「确定」才回写并刷新表格,点「关闭」直接丢弃,不会出现「点一下表格就跳」。\n\n```vue\n<s-super-list-layout title="高级列表" :columns="columns" :load-data="loadData" />\n```\n\n| 参数 | 类型 | 默认 | 说明 |\n| ---------------- | ----------------- | ----------------------------- | ------------------------ |\n| `title` | String | 必填 | 标题条文字 |\n| `columns` | Array | `[]` | 列配置,见下方 |\n| `loadData` | Function | 必填 | 取数,入参含高级筛选结果 |\n| `rowKey` | String / Function | `\'id\'` | 行 key |\n| `buttons` | Array | 添加 / 批量删除 / 导入 / 导出 | 与 `SListLayout` 同构 |\n| `isSelection` | Boolean | `false` | 是否显示勾选列 |\n| `showPagination` | Boolean | `true` | 是否显示分页 |\n| `pSize` | Number / String | `20` | 默认每页条数 |\n\n列配置在 `SListLayout` 基础上多两项:\n\n| 字段 | 说明 |\n| -------------- | -------------------------------------------------------------------------------------------------- |\n| `filterConfig` | 配了才会出现在「高级搜索」的可选字段里;不配则该列只能看不能筛 |\n| `width` | px / 纯数字 → 直接生效,并带进「高级表格」的列宽输入框;`%` → 仅作表头宽度,高级表格里的像素框留空 |\n\n`filterConfig` 可用键:`filterType` / `filterApi` / `filterData` / `props` / `precision` / `step` / `minValue` / `maxValue` / `length` / `startDate` / `endDate`。\n`filterType`:[`INPUT` 输入框、`INT` 整数、`FLOAT` 浮点、`DATE` 日期、`DATETIME` 时间、`SINGLE_SELECT` 单选、`MULTIPLE_SELECT` 多选、`GANDER` 性别、`IS` 是否、`USER` 用户、`OFFICE` 组织机构]。下拉类的选项优先取 `filterData`,没配才用 `filterApi` 拉一次并回填。\n\n**列设置(`SettingColumns`)**\n\n- 显示 / 隐藏:勾选即改草稿,**确定后** `show === false` 的列不进表格(仍可被高级搜索使用);\n- 冻结 / 取消冻结:记住每列最初的冻结方向,取消后再冻结还原原来的 `left` / `right`;操作列(`action`)永远 `right` 且禁用;\n- 列宽:表头 `width` 是 px 或纯数字 → 四舍五入带进输入框;`20%` 这类百分比不带入;用户主动清空则恢复「自适应」;\n- 「确定」→ 回写列配置并关抽屉;「重置」→ 恢复调用方传入的 `columns`;「关闭」→ 丢弃草稿。\n\n**高级筛选(`SettingFilter`)**\n\n- 可选字段 = 配了 `filterConfig` 的列(列被隐藏也能筛);\n- 运算符按类型收窄:文本(`INPUT` 或未配类型)可 `includes` / `excludes` / `equal` / `notequal` / `null` / `notnull`;选择、数字、日期只留 `equal` / `notequal` / `null` / `notnull`;\n- 换字段时运算符按新类型重置(文本默认「包含」,其余默认「等于」);\n- `null` / `notnull` 不需要填值;其余没填值的条件行在提交时丢弃,不会把空条件发给后端。\n\n提交后的取数入参:\n\n```js\nloadData({\n pageNo,\n pageSize,\n filterMode, // 1\n filterConditions: [{ dataIndex, equals, value }],\n [dataIndex]: value // equal / includes 这类单值条件额外铺平一份\n})\n```\n\n`equal` / `includes` 的单值条件会同时铺平成同名字段(`params[dataIndex] = value`),后端按字段名直接取用即可,不用解析 `filterConditions`。\n\n### 2.21 STab 标签栏(超出宽度自动出左右箭头)\n\n一行横向标签,**放得下就不出箭头**,放不下时左右各出一个 32×32 箭头:点箭头等于「选中上一个/下一个标签 + 把它滚进可视区」。\n\n两种用法,任选其一:\n\n```vue\n<!-- 用法一:传数组,组件自己渲染 -->\n<s-tab v-model:activeKey="active" :tabs="tabs" @change="onChange" />\n\n<script setup>\nconst tabs = [\n { label: \'任务配置\', value: \'1\' },\n { label: \'执行日志\', value: \'2\' }\n]\nconst active = ref(\'1\')\nconst onChange = (key, item) => {\n /* item 仅数组模式提供 */\n}\n<\/script>\n\n<!-- 用法二:自己写 s-tab-item(需要自定义标签内容时用) -->\n<s-tab v-model:activeKey="active">\n <s-tab-item value="1">任务配置</s-tab-item>\n <s-tab-item value="2">\n <span>执行日志</span>\n <a-badge :count="3" />\n </s-tab-item>\n</s-tab>\n```\n\n**默认选中**:不传 `activeKey` 也能用 —— 传 `default-active-key` 就选中它,两者都没传则自动选中第一项(组件挂载后补默认值,并通过 `update:activeKey` 同步给父级,`@change` 不算用户操作、不会触发)。\n\n```vue\n<s-tab :tabs="tabs" default-active-key="2" />\n```\n\n| 项 | 说明 |\n| ------------------- | ---------------------------------------------------------------------------------------- |\n| `v-model:activeKey` | 当前选中值,`String`/`Number`;**不传 / 传空(`\'\'`)都会自动选中**(见下一行) |\n| `defaultActiveKey` | 默认选中值:`activeKey` 没传或传空时生效;**它也没传就默认选中第一项** |\n| `tabs` | `[{ label, value }]`;字段名不同用 `tabKey`(默认 `{ label: \'label\', value: \'value\' }`) |\n| `tabKey` | 字段映射,与 `SFormLayout`/`SSkeletonLayout` 的 `tabs` 约定一致 |\n| `stepRatio` | 已到首个/末个标签但仍可滚动时,一次滚多少屏,默认 `0.6` |\n| `@change` | `(key, item)`;插槽模式下 `item` 为 `undefined` |\n| 插槽 | 默认插槽放 `s-tab-item`;一旦使用默认插槽,`tabs` 不再参与渲染 |\n| expose | `syncArrow()` / `scrollToActive()` / `scrollRef` |\n\n**交互规则**\n\n| 场景 | 行为 |\n| ---------- | -------------------------------------------------------------- |\n| 内容放得下 | 不渲染箭头,标签铺满整行 |\n| 内容超出 | 左右箭头出现 |\n| 点右箭头 | 选中下一个标签并滚进可视区;已是最后一个则退化为「纯滚动一屏」 |\n| 箭头禁用 | 既没有上一个/下一个标签,也无法再滚动时禁用 |\n| 滚轮 | 纵向滚轮转横向滚动,不会带动整页 |\n| 鼠标拖动 | 按住左键左右拖动即可平移标签栏(仅溢出时生效);位移超过 5px 才算拖动,不会误触发标签切换;**悬停不显示抓手光标,按下才变抓手** |\n| 触摸 | 不接管,保持系统原生横向滚动与惯性 |\n| 键盘 | 标签聚焦后左右方向键切换 |\n\n> ⚠️ 只给标签栏,不给内容区。内容请自己按 `activeKey` 渲染(切显隐用 `v-show`,不要用 `v-if`,否则隐藏页签里的组件实例会丢)。\n> 典型例子:权限配置里按客户端分的多个表格,保存时要同时读到所有页签的勾选,必须全部渲染、只切显示。\n\n**配色跟随主题**(组件内没有写死颜色,换 `VITE_APP_THEME_VALUE` 自动跟着变)\n\n| 元素 | 取色 | 对应变量 |\n| ---------------- | ---------------------------------------------------------- | ---------------------------------------------- |\n| 选中 / 悬停标签 | 主题主色 | `--s-color` |\n| 未选中标签、箭头 | 主题主色 30% 混入中性灰 → 带主题倾向的灰(对比度 ≥ 4.5:1) | `color-mix(… var(--s-tab-color) 30%, #595959)` |\n| 箭头到头(禁用) | 主题描边色 | `--s-border-color` |\n\n想单独调整标签栏配色,在外层覆盖这几个变量即可,不用改组件、也不用动主题:\n\n```less\n.my-page {\n --s-tab-color: #333; // 未选中 / 箭头(参与颜色调和)\n --s-tab-active-color: #fa541c; // 选中 / 悬停\n --s-tab-disabled-color: #ddd; // 箭头到头\n}\n```\n\n> 老浏览器(不认识 `color-mix`)自动退化为中性灰 `#595959`,不会出现「文字继承不到颜色」的问题。\n\n### 2.22 SFilterTableToolbar(查询区 + 表格区组合件)\n\n`SFilterToolbar` + `STableToolbar` 的现成组合:上半查询区、下半表格区,**表格吃掉剩余高度并在内部滚动**。\n\n```vue\n<s-filter-table-toolbar :columns="columns" :data="page" row-key="id" @reset="onReset">\n <template #filter>\n <s-filter-item label="名称">\n <a-input v-model:value="query.name" @pressEnter="reload" />\n </s-filter-item>\n </template>\n\n <!-- 列插槽按 dataIndex 命名,与 s-table 一致 -->\n <template #action="{ record }">\n <a @click="edit(record)">修改</a>\n </template>\n</s-filter-table-toolbar>\n```\n\n| 项 | 说明 |\n| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 查询区插槽 | `filter`、`filterMore`(透传给 `SFilterToolbar`) |\n| 表格插槽 | 其余插槽全部透传给 `STableToolbar`(列名插槽、`bodyCell`、`expandedRowRender`…) |\n| 其余属性 | `columns` / `data` / `rowKey` / `pageSize` / `size` / `scrollX` / `tableHeight`,其余通过 `$attrs` 透传给 `s-table`(如 `showPagination`) |\n| `@reset` | 只抛事件,**查询参数在业务侧**,清空后自己调 `refresh()` |\n| expose | `refresh(deleteFlag)` / `reload()` / `resize()` / `tableRef` |\n\n**高度前提**:组件根节点是 `height:100%` 的 flex 列,需要外层给到确定高度才会撑满 ——\n\n- 放进 `SFormLayout` 的 `#form` 插槽 ✅(`form-container-wrap` 已是 `flex:1`)\n- 放进 `SSkeletonLayout` 默认插槽 ✅(`.skeleton-container` 已是 `flex:1`)\n- 直接丢进普通 `div` ❌,高度会退化成内容高度(这是 CSS 的规矩,不是组件 bug)\n\n## 三、布局与高度规范\n\n> 本章是**基座内部布局组件的强制约定**。业务页面只管用 layout,不要自己写高度;如果要新增布局组件,必须先满足本章规则。\n\n### 3.1 高度:优先 CSS flex 撑满;需要动态计算时按三条约束做\n\n> **2026-10-28 修订**:旧标题「禁止 JS 减法算高度」已作废。业务内容区需要出滚动条时,**高度就该动态计算**,只是必须按下面的约束写,不能每页抄魔数。\n\n**错误做法**(早期 `SListLayout` / `SFormLayout` 都犯过):\n\n```js\n// ❌ 用 offsetHeight 减法算子区域高度\nthis.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16\n```\n\n为什么必错:`offsetHeight` 读的是**当前渲染结果**,而这个结果又取决于你即将写入的 `height` —— 循环依赖。表现是:\n\n- 数据不满页时分页浮在中间,底部空 15~588px;\n- 表格/表单区溢出容器 1~N px,页面多出一条滚动条;\n- 改一个固定魔数(如 `tpH = 103`)其它页面全歪。\n\n**首选做法(零 JS)**:父容器 `height:100%` + `display:flex; flex-direction:column`,主体区 `flex:1 1 auto; min-height:0; overflow:auto`,底部条 `flex:0 0 auto`。列表页、表单页绝大多数场景用这个就够。\n\n> **2026-11-06 现状**:`SSkeletonLayout`、`SListLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SNewestDataListLayout`、`SListCardLayout`、`SListBasicLayout`、`SFormLayout`、`SFormBasicLayout`、`SPanelLayout`、`SFilterTableToolbar` **已全部改为纯 CSS flex,零 JS 测量高度**。业务页面不需要再写任何高度代码。\n\n**布局组件根节点的标准写法**(新增布局组件请照抄):\n\n```less\n.xxx-layout {\n height: 100%; /* 吃满父容器,父级必须有确定高度 */\n min-height: 0; /* ✅ 必须:允许被压缩 */\n display: flex;\n flex-direction: column;\n overflow: hidden;\n}\n```\n\n两个必须记住的点:\n\n| 点 | 说明 |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| ✅ 必须写 `min-height: 0` | flex item 默认 `min-height: auto` = **内容最小高度**。不写它,内容一多就会被顶开、把父级(`PageView` 的 `.page-view-common`)撑破,表现为**外层 router-view 多出一条滚动条**。 |\n| ❌ 不要写 `max-height: 100%` | 父级高度不是显式值时,这个百分比会把根节点压成 0/极小,**整条 flex 链瞬间塌掉**(表格只剩表头、左侧树错位)。防塌陷靠父级显式高度,不靠 `max-height`。 |\n\n**中间层必须一起贯通**,漏一层就断链:\n\n- `a-spin` 夹在中间时:`.ant-spin-nested-loading`、`.ant-spin-container` 都要 `flex:1 1 auto; min-height:0; display:flex; flex-direction:column`\n- 滚动包裹层(如 `.form-layout-main-scroll`)也要设成 flex 列,否则里面的 `flex:1` 拿不到高度\n- 分隔条、滚动条这类固定尺寸元素写 `flex: 0 0 <尺寸>`,**不要只写 `width`** —— 否则空间一紧就被压成 0(左边树拖不动的元凶)\n\n**现在唯一还需要 JS 的地方**:表格的 `scroll.y`。它只用于启用 antd 固定表头,值取 `.ant-table-body` 的真实 `clientHeight`,**不参与布局**(CSS 已用 `max-height: none !important` 覆盖 antd 写入的内联 `max-height`)。\n\n**需要 JS 动态计算的情形**(内容区要出滚动条、容器高度随窗口或兄弟节点变化):**允许并推荐动态计算**,但必须满足三条:\n\n1. **收敛到一处**:同一种布局只留一个 `calcXxxHeight()`,不要每页一份魔数\n2. **跟着容器走**:用 `ResizeObserver` 观察父容器重算,别只监听 `window.resize`\n3. **不读 `$parent.$el`**:父级 DOM 结构一变就错,用 `ref` 取自己的容器\n\n**仍然禁止的错法**:拿「自己即将写入 height 的那个祖先」的 `offsetHeight` 做减法 —— 循环依赖。要读就读**不依赖自身高度**的量(`window.innerHeight`、上级固定头/脚节点的高度)。\n\n### 3.2 表格区撑满链路(列表页分页贴底的关键)\n\n`STable` 的 body 要靠 flex 拿到剩余高度,链路上**任何一层漏掉都会导致撑不开**:\n\n```less\n.table-content {\n flex: 1;\n display: flex;\n flex-direction: column;\n min-height: 0;\n}\n.tabs-wrap {\n flex: 0 0 auto;\n}\n.table-container {\n flex: 1 1 auto;\n min-height: 0;\n display: flex;\n flex-direction: column;\n}\n.table-wrapper {\n flex: 1 1 auto;\n ...;\n} /* STable 组件根节点,漏它整条链断 */\n.ant-table-wrapper {\n flex: 1 1 auto;\n ...;\n}\n.ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container {\n margin-left: 10px;\n} /* 表格缩进走 margin,不走 padding */\n.ant-table-header {\n flex: 0 0 auto;\n}\n.ant-table-body {\n flex: 1 1 auto;\n min-height: 0;\n max-height: none !important;\n}\n.ant-table-pagination {\n margin-bottom: 0;\n flex: 0 0 auto;\n} /* 差一个 margin 就是 15~16px 空隙 */\n```\n\n要点:\n\n1. **`.table-wrapper` 不能漏** —— 它是 `STable` 组件根节点,实测漏掉它 body 就撑不开;\n2. `scroll.y` 写入的 `max-height` 必须 `none !important` 覆盖掉,否则和 flex 打架;\n3. 分页 `margin-bottom: 0`,否则分页与容器底边恒差一个 margin;\n4. 表格缩进用 `:deep(.ant-table-container){margin-left:10px}`,**不要**用 `padding-left`(会挤压 body 宽度计算)。\n\n### 3.3 `.tools` 头部条统一 60px\n\n所有布局的 `.tools`(标题 + 按钮条)统一:\n\n```less\n.tools {\n height: 60px;\n display: flex;\n justify-content: space-between;\n align-items: center;\n padding: 0 16px;\n box-sizing: border-box;\n border-bottom: 1px solid #f0f2f5;\n}\n.list-filter-wrap {\n padding: 10px 16px;\n box-sizing: border-box;\n}\n```\n\n> ⚠️ 若某天调整了 `.tools` 高度,所有布局里 `initTable()` 的减数(如 `- 76`)必须同步改,否则全站列表页一起歪。\n\n### 3.4 表单布局 SFormLayout\n\n`.form-layout` 用同一套 flex 撑满,`initStyle()` 里**只算 footer 宽度**(collapses + anchor 场景要避开右侧锚点),不再算高度:\n\n```less\n.form-layout {\n height: 100%;\n overflow: hidden;\n :deep(.ant-spin-nested-loading),\n :deep(.ant-spin-container) {\n /* a-spin 包裹层必须逐层撑满,否则 form-layout 高度取不到 */\n height: 100%;\n display: flex;\n flex-direction: column;\n min-height: 0;\n }\n}\n.tools,\n.step-wrap,\n.tabs-wrap,\n.modal,\n.form-fixed-footer {\n flex: 0 0 auto;\n}\n.form-layout-main {\n flex: 1 1 auto;\n min-height: 0;\n overflow: hidden auto;\n}\n.form-fixed-footer {\n height: 60px;\n}\n```\n\n**多列与独占整行(`full`)**\n\n`SForm` 的 `a-form` 与 `SCollapsesItem` 的内容区都是 `display:grid; grid-template-columns: repeat(column, 1fr)`。多列时想让某一项独占整行,给子项加 `full` 即可(内部落成 `grid-column: 1 / -1`):\n\n```vue\n<!-- 表单 3 列,备注独占一行 -->\n<s-form :column="3" :model="form">\n <s-form-item label="名称" name="name"><a-input /></s-form-item>\n <s-form-item label="编码" name="code"><a-input /></s-form-item>\n <s-form-item label="备注" name="remark" full><a-textarea /></s-form-item>\n</s-form>\n\n<!-- 折叠分组 2 列 -->\n<s-collapses>\n <s-collapses-item title="基础信息" :column="2">\n <s-form-item label="姓名" name="a"><a-input /></s-form-item>\n <s-form-item label="年龄" name="b"><a-input /></s-form-item>\n <s-form-item label="详细地址" name="c" full><a-input /></s-form-item>\n </s-collapses-item>\n</s-collapses>\n```\n\n**筛选区独占整行(`SFilterItem` 的 `full`)**\n\n`SFilterWrap` 是 `display:flex; flex-wrap:wrap; gap:10px` 容器,子项宽度默认由 `width`(px,默认 280)决定。加 `full` 后该项宽度拉满 `100%`(`flex: 1 1 100%`),自然独占一行,后面的项自动换到下一行:\n\n```vue\n<s-filter-wrap>\n <s-filter-item label="名称"><a-input /></s-filter-item>\n <s-filter-item label="状态"><a-select /></s-filter-item>\n <!-- 备注太长,让它单独占一行 -->\n <s-filter-item label="备注" full><a-textarea /></s-filter-item>\n</s-filter-wrap>\n```\n\n- `full` 优先于 `width`:同时传时忽略 `width`。\n- `label` 仍按 `labelWidth`(默认 70)渲染,剩余宽度全部给内容区,`a-select` 会自动撑满。\n- 只有 `SFilterItem` 有这个属性;`SFilterWrap` 本身不需要配列数。\n\n| 参数 | 类型 | 默认 | 归属 |\n| ------ | ------- | ------- | -------------------------------------------- |\n| `full` | Boolean | `false` | `SFormItem`、`SCollapsesItem`、`SFilterItem` |\n\n- 单列时 `1 / -1` 等价于一整行,没有副作用,所以同一个表单项在 1 列 / N 列之间切换不用改代码。\n- `column` 是 **`SCollapsesItem`** 的 prop,不是 `SCollapses` 的;写在 `<s-collapses column="2">` 上不生效。\n- `SFormItem` 的 `full` 已声明为 prop,不会透传到内部 `a-form-item` 上触发 antd 警告;`SFilterItem` 同理,不会落到内层节点。\n- 实现方式不同:`SFormItem` / `SCollapsesItem` 落在 `grid-column: 1 / -1`,`SFilterItem` 落在 `flex-basis: 100%`,用法一致。\n\n**查询区外壳(`SFilterToolbar`)**\n\n只想要查询区(不带表格、不带布局外壳)时用 `SFilterToolbar`:主查询区常显 + 「更多 / 收起」折叠 + 条件重置。功能与 `SListLayout` / `SListBasicLayout` 的 `filter` / `filterMore` 插槽一致,但**内部已包 `SFilterWrap`**,业务只写 `SFilterItem`。\n\n```vue\n<s-filter-toolbar @reset="reset" @toggle="onFilterToggle">\n <template #filter>\n <s-filter-item label="关键字" :width="320"><a-input v-model:value="query.keyword" /></s-filter-item>\n <s-filter-item label="状态" :width="220"><a-select v-model:value="query.status" /></s-filter-item>\n </template>\n <!-- 可选:没有这个插槽时「更多 / 收起」按钮不渲染 -->\n <template #filterMore>\n <s-filter-item label="维度" full><check-box v-model:value="query.scopeIds" /></s-filter-item>\n </template>\n</s-filter-toolbar>\n```\n\n| 插槽 | 说明 |\n| ------------ | --------------------------------------- |\n| `filter` | 主查询区,常显 |\n| `filterMore` | 折叠区,`v-show` 控制;不传则按钮不渲染 |\n\n| 事件 | 参数 | 说明 |\n| -------- | -------------- | ----------------------------------------------------------------------------------------------- |\n| `reset` | — | 点「条件重置」,父级清空查询参数后自行 `reload` |\n| `toggle` | `isMoreFilter` | 折叠状态变化;表格区用 `STableToolbar` 时**无需处理**(它自己观察容器尺寸),自建表格才需要重算 |\n\n- 「更多 / 收起」按钮**紧跟查询内容右侧**(居左),重置按钮推到最右,与 `SListLayout` 的 `.filter-more-btn` / `.reset-wrap` 完全同款。\n- 查询区高度随折叠变化。表格区**优先用 `STableToolbar`**,它内部 `ResizeObserver` 观察自身容器,折叠后自动重算表体高度,父级零配置。\n- `defineExpose`:`isMoreFilter`、`toggleFilter()`、`filterReset()`、`collapse()`(切 tab 时主动收起)。\n\n**表格区外壳(`STableToolbar`)**\n\n`SFilterToolbar` 的固定搭档:封装 `STable` + 分页 + **表体高度自适应**,替业务承担「内容区 − 查询区 − 表头 − 分页」这套算法,保证不出页面级滚动条。\n\n```vue\n<!-- 父级只负责纵向排布,不需要给表格区写 flex / height -->\n<div class="page">\n <s-filter-toolbar @reset="reset">\n <template #filter>...</template>\n <template #filterMore>...</template>\n </s-filter-toolbar>\n\n <s-table-toolbar ref="tableToolbar" row-key="id" :columns="columns" :data="page" :page-size="10">\n <!-- 单元格插槽与 SListLayout 一致:列 dataIndex 就是插槽名 -->\n <template #ruleName="{ record }">\n <a @click="detail(record)">{{ record.ruleName }}</a>\n </template>\n <template #action="{ record }">\n <a @click="edit(record)" v-action="\'edit\'">修改</a>\n </template>\n </s-table-toolbar>\n</div>\n```\n\n```less\n.page {\n height: 100%;\n min-height: 0;\n display: flex;\n flex-direction: column;\n}\n```\n\n| prop | 默认值 | 说明 |\n| ------------------ | ---------- | ------------------------------------------------------------- |\n| `columns` / `data` | — | 同 `STable`,`data` 必填 |\n| `rowKey` | `\'id\'` | 同 `STable` |\n| `pageSize` | `10` | 同 `STable` |\n| `size` | `\'middle\'` | 同 `STable` |\n| `scrollX` | `\'100%\'` | 横向滚动;表体 `y` 由组件自己算,**父级传 `scroll` 会被忽略** |\n| `tableHeight` | `300` | `scroll.y` 的初值;真实高度由布局 flex 决定,父级一般不用传 |\n\n- 属性除上表外原样透传给 `STable`。\n- **单元格插槽与 `SListLayout` 完全一致:列 `dataIndex` 就是插槽名**,参数 `{ text, record, index, column }`,没有同名插槽的列按原值渲染。`#headerCell` / `#expandedRowRender` / `#emptyText` 这类非列插槽仍原样透传。\n- **不要再写 `#bodyCell`**:组件内部已经占用了它做列分发,业务再写会被忽略,该列整列空白(操作列"消失"就是踩的这个坑)。\n- 高度:**纯 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`,所以**永远不会顶出页面级滚动条**。\n- 布局可视内容区变化(`filterMore` 展开、tab 切换、窗口缩放、侧栏收起)由布局自动跟随,父级不用写 `onFilterToggle`。\n- `defineExpose`:`resize()`(手动重算)、`refresh(deleteFlag)`(转发 `STable.refresh` 并在刷新后补算分页高度)、`reload()`、`tableRef`、`scrollY`。\n- 父级根节点必须给「有高度 + `flex` 纵向」的排布(`height:100%; display:flex; flex-direction:column`),组件靠 `flex: 1 1 0%` 接手剩余空间。\n\n### 3.5 左侧树容器高度统一(`.s-side-tree`)\n\n`SListLayout` / `SListTableTreeLayout` / `SListCardLayout` 的 `.side` 都是 `padding: 10px`(四边),树容器高度必须等于「`.side` 盒高 − 上下 padding(20px)」,否则双滚动条或树被截断。\n\n规则写在**全局** `packages/style/tree.less` 的 `.s-side-tree`(`.side` 的唯一化追加类,避免通用名被业务覆盖),业务页面 scoped 里**禁止再写副本**。覆盖两种树来源:\n\n- ① 标准 `<s-tree>`:根节点即 `.s-tree-common`,`height:100%`;\n- ② 原生 `<a-spin><a-tree>`:逐层撑高 `.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder`,由 `.ant-tree-list-holder` 承担 `overflow-y:auto`。\n\n> ⚠️ ② 的分支必须用 `>` 从 `.s-side-tree` 直接起算,**不能写成后代选择器** —— `STree` 内部同样是 `.ant-tree`,后代写法会误伤 ①。\n\n### 3.6 STree 自适应与横向省略\n\n`STree` 的 `height` prop 默认值必须是 `undefined`(**不能写死 300**):\n\n```js\nheight: { type: Number, default: undefined }\n```\n\n原因:antd 的 `Tree` 会把 `height` 转成虚拟列表 holder 的行内 `max-height:300px`,导致树被截断且自身产生内层滚动条。\n\n横向文字不换行、超出省略、宽度随父容器拉伸 —— 这套结构规则已统一写在全局 `packages/style/tree.less`(`.s-tree-common` / `.ant-tree*` / `.node-title`),**组件和业务页面都不要再用 scoped 副本**:\n\n```less\n/* packages/style/tree.less(节选,实际见文件) */\n.s-tree-common {\n height: 100%;\n width: 100%;\n overflow-x: hidden;\n overflow-y: auto;\n}\n.ant-tree,\n.ant-tree-list,\n.ant-tree-list-holder,\n.ant-tree-list-holder-inner {\n width: 100%;\n min-width: 0;\n}\n.ant-tree-node-content-wrapper {\n min-width: 0;\n overflow: hidden;\n}\n.ant-tree-title,\n.ant-tree-title > .node-title {\n display: block;\n width: 100%;\n overflow: hidden;\n white-space: nowrap;\n text-overflow: ellipsis;\n}\n```\n\n> `.node-title` 是通用类名,全局规则统一写成 `.ant-tree-title > .node-title`(限树标题层内),避免污染业务同名类。\n\n### 3.7 树样式统一文件与主题变量(`packages/style/tree.less`)\n\n所有树的样式只在这一个文件里,`common.less` 末尾 `@import \'./tree.less\'` 引入。原先散落在 `STree.vue`(scoped)、`SBelowChoosePosition.vue`(scoped 副本)、`common.less`(全局)三处的规则已全部收编。\n\n覆盖的树类型:\n\n| 类型 | 选择器根 | 用到的组件 |\n| ------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------- |\n| 目录树 / 普通树(`a-directory-tree` / `a-tree`) | `.s-tree-common`、`.ant-tree*` | `STree`、`SBelowChoosePosition`、业务原生 `<a-tree>` |\n| 树下拉弹层(`a-tree-select`) | `.s-tree-select-popup` | `STreeSelect`、`SDataRangeTreeSelect`(`popup-class-name` 挂类) |\n| 侧栏树容器高度 | `.s-side-tree` | `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` |\n\n颜色与尺寸全部走 `--s-tree-*` 变量,**默认值等于改造前的硬编码值,视觉零变化**:\n\n| 变量 | 默认值 | 说明 |\n| ---------------------------------- | --------------------------------- | ------------------------------------------- |\n| `--s-tree-node-height` | `30px` | 节点内容行高(弹层同用) |\n| `--s-tree-node-line-height` | `32px` | 树本体标题行高 |\n| `--s-tree-node-padding-x` | `4px` | 弹层节点左右内边距 |\n| `--s-tree-row-gap` | `4px` | 行间距(整行底色留缝) |\n| `--s-tree-node-radius` | `8px` | 整行圆角(悬浮 + 选中,画在 `::before` 上) |\n| `--s-tree-switcher-color` | `#000000a6` | 展开箭头色 |\n| `--s-tree-hover-bg` | `var(--s-color-bg)` | 悬浮整行底色,**跟随主题主色**(主色混白 90%;暗色下自动换主色深底) |\n| `--s-tree-selected-bg` | `var(--s-color, #1677ff)` | 选中整行底色,**已跟随主题主色** |\n| `--s-tree-selected-text` | `#fff` | 选中整行文字/箭头色 |\n| `--s-tree-directory-selected-bg` | `#bae7ff` | 目录树选中浅色底(antd blue-2) |\n| `--s-tree-directory-selected-text` | `#000000a6` | 目录树选中文字色 |\n| `--s-tree-icon-color` | `#fff` | 节点类型图标文字色 |\n| `--s-tree-icon-bg` | `transparent` | 节点图标默认底色 |\n| `--s-tree-icon-bg-g` / `-c` / `-d` | `#a9a9f5` / `#d3b403` / `#f09191` | 节点图标 G/C/D 类型底色 |\n\n换主题色时按需覆盖即可,不用改组件:\n\n```css\n/* 纯 CSS 主题:body 上已由基座挂 theme-xxx 类(见 §2.8) */\nbody.theme-green {\n --s-tree-selected-bg: #00b96b;\n --s-tree-directory-selected-bg: #d9f7e9;\n --s-tree-directory-selected-text: #1f1f1f;\n}\n\n/* 全局微调尺寸 */\n:root {\n --s-tree-node-height: 32px;\n --s-tree-row-gap: 6px;\n}\n```\n\n注意两点:\n\n1. `--s-tree-selected-bg` 默认是 `var(--s-color, #1677ff)`,切主题色会自动跟随;浅色档 `--s-tree-directory-selected-bg` 默认仍是 antd blue-2,要跟随就显式覆盖。\n2. 变量只放「颜色/长度」本身,不要往里塞整条声明(如 `--x: background:red`)。\n\n### 3.8 排查渲染问题的铁律\n\n**页面渲染/高度问题必须用 puppeteer 登录后量真实 `offsetHeight`/`offsetLeft`/盒模型,禁止静态读代码猜根因。**\n\n```js\n// 量:容器高、主体高、底部条位置差、文档溢出\nconst r = await page.evaluate(() => {\n const q = (s) => document.querySelector(s)\n const box = (s) => {\n const el = q(s)\n if (!el) return null\n const b = el.getBoundingClientRect()\n return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) }\n }\n return {\n container: box(\'.list-layout-main\'),\n tableContent: box(\'.table-content\'),\n pagination: box(\'.ant-table-pagination\'),\n docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight\n }\n})\n```\n\n验收标准(全部为 0 才算过):\n\n| 指标 | 通过条件 |\n| ---------------------------- | --------------------------- |\n| `documentOverflowY` | `0`(页面不出现滚动条) |\n| `pagination.bottom` 减容器底 | `0`(分页刚好卡在视口底部) |\n| 表格主体溢出容器 | `0` |\n\n多视口抽查(建议 1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440)全过才算改完。\n\n---\n\n## 四、构建与配置\n\n### 4.1 构建与发布\n\n```bash\nnpm run dev # 基座本地开发\nnpm run build # lib 构建 + 复制 docs/vite-plugins/package.json 到 dist + git push\nnpm run lint\n```\n\n> 基座构建 **不 drop console**(`$utils`/i18n 调试输出由运行时 `VITE_CONFIG_sapit-base-template` 控制);业务构建才 drop。\n\n产物:入口 `./packages/index.js`,`vue` external,输出 `dist/lib`,打包内容为**入口依赖图**(不是整个项目);`package.json` 的 `files: ["lib","docs","vite-plugins"]`。\n\n### 4.2 配置来源与优先级\n\n```text\n基座默认 defaultEnv < 业务 web-config.js < .env.[sapit-base-template](构建时写入 config.json) < 部署 config.json(运行时覆盖)\n```\n\n- `web-config.js`:可写默认值或 `import.meta.env.VITE_APP_*`;\n- `.env` / `.env.[sapit-base-template]`:各环境一套(dev/test/uat/prod),由业务 `vite.config.js` 写入 `config.json`;\n- `config.json`:站点根(子路径为 `<base>config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `"true"/"false"` 归一为布尔。\n\n常用开关(业务可按需覆盖;判断统一用 `!== false`,即未配置时取基座默认值):\n\n| 配置项 | 默认值 | 说明 |\n| ----------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |\n| `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 |\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | 是否显示右上角消息铃铛(设 `false` 隐藏) |\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | socket 地址:**只写协议+主机+端口,不要带 `/apig/` 等路径**;为空或 `/` 时走同源;本地占位地址在非本机环境下自动跳过 |\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io 握手路径,需与后端一致(真正的服务路径只认这一项) |\n| `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化 |\n| `VITE_APP_MENU_BAR` | `left` | 菜单布局:`left` / `top`(业务可选) |\n| `VITE_APP_MENU_THEME` | `light` | 菜单配色模式:`light` 跟主题色的浅色系 / `dark` 黑色(业务可选) |\n| `VITE_APP_THEME_FOLLOW_SYSTEM`| `true` | 是否跟随系统深浅色(`prefers-color-scheme`):系统切深色时菜单换黑 + 中性色令牌换暗色版,运行时即时生效(业务可选) |\n| `VITE_APP_MENU_BG` | `theme` | 基座锁定:`light` 一级底;`theme` 跟随主题色(默认)/ `#RRGGBB` 固定 |\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 基座锁定:一级底亮度 0-100 |\n| `VITE_APP_MENU_BG_SATURATION` | `66` | 基座锁定:饱和度上限 0-100 |\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 基座锁定:选中块里主题色的占比 0-100 |\n| `VITE_APP_MENU_SUB_BG` | 空 | 基座锁定:子菜单展开区底色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_HOVER_BG` | 空 | 基座锁定:悬停项底色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_ACTIVE_BG` | 空 | 基座锁定:选中块底色;空 = 主题色兑白(占比见 `_BG_ACTIVE_MIX`) |\n| `VITE_APP_MENU_TEXT` | 空 | 基座锁定:普通文字色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_TEXT_HOVER` | 空 | 基座锁定:悬停文字色 |\n| `VITE_APP_MENU_TEXT_ACTIVE` | 空 | 基座锁定:选中文字色 |\n| `VITE_APP_MENU_GROUP_TITLE` | 空 | 基座锁定:分组标题文字色 |\n\n> 标「基座锁定」的 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菜单配色侧边顶部)。\n\nsocket 是**整站一条连接**(`packages/utils/socket.js`,单例,与源项目 `VueSocketIO` 只注册一次一致),消息与扫码登录共用同一个地址、同一个 `path`,只靠事件名区分:\n\n| 业务 | 上报事件 | 接收事件 | 模块 |\n| --- | --- | --- | --- |\n| 右上角消息铃铛 | `sendUserId`(userId) | `wsEvent` | `packages/utils/message-socket.js` |\n| 扫码登录 | `QRCodeKey`(qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` |\n\n数量逻辑:进入系统先调 `message/center/counts` 取 `totalCount`,之后由 socket 推送的 `wsEvent` 触发重新拉取。业务侧无需注册任何东西,只要把 `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` 配到网关即可。\n\n> `VITE_APP_SOCKET_URL` 里写了路径会踩坑:socket.io 把 URL 的 path 当 **namespace**(`io(\'http://h:50001/apig/\')` → namespace `/apig/`),服务端回 `Invalid namespace`,握手成功但永远不 connect,也不报 `connect_error`。基座虽已在 `resolveSocketUrl` 里剥掉 path 兜底,配置仍建议规范写。\n\n### 4.3 业务项目启动(`npm start`)\n\n业务项目(`sapit-base-template`)的 `npm start` 执行内置脚本 `refresh-sapit-base-template.ps1`:\n\n1. 清理 `node_modules/.vite`、`node_modules/sapit-ui-plus` 及锁文件(`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);\n2. `npm install` 拉取 `sapit-ui-plus` 最新发布版本;\n3. 自动执行 `npm run dev` 启动。\n\n> 作用:清理依赖缓存,更新业务依赖并一键启动。也可双击 `refresh-sapit-base-template.cmd`;`-NoStart` 仅更新不启动。\n> 这个命令通常在基座项目有更新时才会用到。\n\n## 五、业务项目接入\n\n### 5.1 安装\n\n```json\n{ "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } }\n```\n\n### 5.2 入口 `main.js`\n\n```js\nimport { createApp } from \'vue\'\nimport App from \'./App.vue\'\nimport config from \'./config/web-config\'\nimport appConfig from \'./config/app-config\'\nimport SapitUiPlus from \'sapit-ui-plus\'\nimport \'sapit-ui-plus/lib/css/style.css\'\n\nasync function init() {\n const pages = import.meta.glob(\'@/views/**/*.vue\')\n const app = createApp(App)\n app.use(SapitUiPlus)\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\n app.mount(\'#app\')\n}\ninit()\n```\n\n- `config`:环境配置(web-config);\n- `appConfig`:构建期配置(登录/首页覆盖、静态路由、语言包),**不进入 config.json**;\n- `pages`:业务所有页面,用于动态路由按 `hrefs` 匹配。\n\n### 5.3 登录页 / 首页覆盖\n\n`app-config.js`:\n\n```js\nexport default {\n components: {\n login: () => import(\'@/views/login/index.vue\'),\n home: () => import(\'@/views/home/index.vue\')\n }\n}\n```\n\n不配置则用基座默认(`pages/login.vue`、`todo.vue`)。\n\n### 5.4 静态页面 `staticRoutes`\n\n```js\nexport default {\n staticRoutes: [\n {\n path: \'/help\',\n name: \'Help\',\n component: () => import(\'@/views/help/index.vue\'),\n meta: { title: \'帮助\' } // hidden: 不进菜单;public: 免登录\n }\n ]\n}\n```\n\n`layout: false` / `raw: true` 时不包 `BasicLayout`;同 `path` 时业务覆盖基座内置。\n\n### 5.5 业务页面与菜单\n\n后端菜单 `hrefs` 需匹配业务 `views` 路径(或组件名);页面放 `src/views/**` 即可被动态路由识别。侧边菜单渲染「动态菜单 + `staticRoutes`」,基座常量菜单不进菜单。\n\n### 5.6 国际化 / 主题\n\n**国际化**\n\n- 词条文件:`views/<模块>/i18n.js`,扁平 `{ \'中文\': \'English\' }`,命名空间 = `views` 之后的第一段目录名。\n- 页面里不用写 `useI18n`:`$l(\'中文\')` 自动按页面所在目录命中;跨目录强制指定用 `this.useI18n(\'<模块>\')`(Options API)或 `window.useI18n(\'<模块>\')`(`<script setup>`)。\n- 聚合只在业务 `src/config/app-config.js` 里做一次,新增文件 / 新增目录都不用改代码:\n\n```js\n// src/config/app-config.js\nconst locales = import.meta.glob([\'@/views/**/i18n.js\', \'@/locales/**/i18n.js\'], { eager: true })\nexport default {\n // ...其它业务配置\n locales // 由 main.js 的 { ...config, ...appConfig } 交给 $registerGlobalConfig 与基座合并\n}\n```\n\n- `locales/**` 用来覆盖基座词条:`src/locales/components/i18n.js` 对应命名空间 `components`(组件库通用词),业务同名优先。\n- 语言切换器由 `.env` 的 `VITE_APP_LANG_ENABLE` 控制(`true` 显示);`false` 时词条照常工作,中文直出。\n- 老写法 `home-i18n.js` / `login-i18n.js` 这类带前缀的文件名已废弃:一律用 `i18n.js`,否则推导出的命名空间是 `default/home`、`default/login` 这种不存在的名字,词条不会命中。\n\n**主题**\n\n只改 `VITE_APP_THEME_VALUE`;样式用 `var(--s-*)` 或 `.s-theme-*`。菜单配色只由基座决定(跟随主题色推导 + 系统深色跟随),业务只能选 `VITE_APP_MENU_THEME` 的 light / dark、以及要不要开 `VITE_APP_THEME_FOLLOW_SYSTEM`(见 2.18)。\n\n### 5.7 子路径部署(示例 `/monitor/`)\n\n1. `.env`:`VITE_APP_BASE_URL=/monitor/`;\n2. 业务 `vite.config.js`:`base: getViteEnv(res.sapit-base-template, \'VITE_APP_BASE_URL\') || \'/\'`;\n3. 基座路由 base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 均读该值自动带前缀;\n4. nginx:\n\n```nginx\nlocation /monitor/ {\n alias /home/project/tmp/dist/;\n index index.html;\n try_files $uri $uri/ /monitor/index.html;\n}\nlocation = /monitor/config.json {\n alias /home/project/tmp/dist/config.json;\n add_header Cache-Control "no-store";\n}\n```\n\n> `createWebHistory` base、Vite `base`、`window.location` 跳转三者必须都是 `/monitor/`(带尾斜杠)。\n\n### 5.8 使用组件与权限\n\n```html\n<template>\n <s-list-layout :columns="columns" :loadData="page" title="示例" />\n <s-user-select v-sapit-base-templatel:value="ids" />\n <a-button v-action="\'add\'">添加</a-button>\n</template>\n```\n\n后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。\n\n---\n\n### 5.9 内置依赖(业务开箱即用)\n\n`sapit-ui-plus` 的 `dependencies` 会随基座一起装进业务 `node_modules`,业务**无需再装即可直接 import**(业务 `package.json` 里通常只见 `sapit-ui-plus` 一项)。\n\n| 依赖 | 版本 | 用途 |\n| ------------------------------------------------ | ----------------- | ----------------------------------------------------- |\n| `dayjs` | ^1.11.12 | 日期格式化(推荐,`$utils` 内也用) |\n| `axios` | ^1.7.3 | 请求(已封装为 `window.$utils.http`,一般不用直接用) |\n| `qs` | ^6.13.0 | 参数序列化(`stringify`) |\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | 安全取值 / 深拷贝 |\n| `crypto-js` | ^4.2.0 | 加解密 |\n| `js-base64` | ^3.7.2 | Base64 编解码 |\n| `jsencrypt` | ^3.3.2 | RSA 加密 |\n| `moment` | ^2.30.1 | 日期(老代码兼容,新代码用 dayjs) |\n| `html2canvas` | ^1.4.1 | 页面截图 |\n| `nprogress` | ^0.2.0 | 顶部加载进度条 |\n| `@vueuse/core` | ^11.0.3 | 组合式工具函数 |\n| `vue-cropper` | ^1.1.4 | 图片裁剪(SCopperUpload 用它) |\n| `vuedraggable` | ^4.1.0 | 拖拽排序 |\n| `v-clipboard` | ^3.0.0-next.1 | 复制到剪贴板(`v-clipboard` 指令) |\n| `vue-ls` | ^4.2.0 | localStorage 封装(已包成 `$utils.ls`) |\n| `jodit` | 3.24.7 | 富文本编辑器(SEditor) |\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | 样式编译 |\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | 构建插件(生成 config.json 等) |\n| `@ant-design/icons-vue` | 随 ant-design-vue | 图标,**全部已全局注册为组件** |\n\n**单例依赖:基座不做打包,业务必须自己安装**(`vite.config.js` 的 `external`),否则会出现两个模块实例(路由注入不上、pinia 对不上、主题/消息上下文丢失):\n\n| 依赖 | 版本 |\n| ---------------- | ------- |\n| `vue` | ^3.4.29 |\n| `vue-router` | ^4.3.3 |\n| `pinia` | ^2.1.7 |\n| `vue-i18n` | ^9.14.0 |\n| `ant-design-vue` | 4.x |\n\n> 用法:`import dayjs from \'dayjs\'` 直接可用;但**不要**在业务里再装一份与基座不同大版本的 `vue`/`ant-design-vue`/`pinia`,版本以基座为准。\n\n### 5.10 全局注入(无需 import)\n\n| 名称 | 说明 |\n| ------------------------------------------ | ------------------------------------------------------------------------------ |\n| `$utils` | 工具类:`$utils.http`(请求)、`$utils.ls`(本地存储)、`$utils.env`(配置)等 |\n| `$message` / `$modal` / `$notice` | ant-design-vue 的 message / Modal / notification |\n| `$push` / `$open` | 站内跳转 / 新窗口打开(自动拼接部署 base) |\n| `$l` | 国际化取词(`$l(\'中文\')`) |\n| `$theme` | 当前主题变量;CSS 变量 `--s-color` 等 |\n| `$icons` | 全部 antd 图标组件 |\n| `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / 过滤器 / 用户 store / i18n 实例 |\n| `env` | 同 `$utils.env` |\n| `$staticRoutes` | 静态页面路由(含业务自定义) |\n| `$getPdf({ el, title })` | 页面导出 PDF;`html2canvas` + `jsPDF` 动态加载(见 2.2) |\n\n---\n\n## 六、注意事项\n\n### 6.1 业务侧\n\n1. <span style="color:#d4380d;font-weight:700">依赖是预构建产物</span>:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。\n2. <span style="color:#d4380d;font-weight:700">锁文件会钉住旧提交</span>:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。\n3. <span style="color:#d46b08;font-weight:700">子路径</span>:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。\n4. <span style="color:#d46b08;font-weight:700">全局组件命名</span>:按文件名注册(`SForm.vue` → `<SForm>`,不是 kebab-case);冲突后者覆盖。\n5. <span style="color:#d46b08;font-weight:700">主题 / 菜单配色 / 国际化</span>:定义都在基座。业务只选 `VITE_APP_THEME_VALUE`、`VITE_APP_MENU_THEME`(light / dark)、`VITE_APP_THEME_FOLLOW_SYSTEM`(是否跟随系统深浅色)、只写 i18n 文案;`VITE_APP_MENU_*` 颜色与调色项由基座锁定,业务写了也会被回填(见 2.18)。\n6. <span style="color:#d46b08;font-weight:700">不能深路径 import 基座内部模块</span>:lib 产物只有 `lib/js/index.js` 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性(`$utils` / `$modal` 那样)。\n7. <span style="color:#d4380d;font-weight:700">功能去留</span>:源码(老 Vue2 项目)有的我们就有,源码没有的不要"顺手补齐"。新增功能前先确认参照实现。\n\n### 6.2 开发 / 构建\n\n8. **不要并发跑两个 `vite build`**:会报 `Rollup failed to resolve import "sapit-ui-plus"`,是缓存冲突的假报错,串行重跑即恢复。若串行仍报错,检查 `node_modules/sapit-ui-plus` 是否被清空(npm 重装常清掉)——恢复方式:\n\n ```bash\n # 基座 dist 就是 npm 包内容(build 脚本把 package.json + docs + vite-plugins 拷进 dist)\n cp -r <基座>/dist/lib <基座>/dist/docs <基座>/dist/vite-plugins <基座>/dist/package.json <业务>/node_modules/sapit-ui-plus/\n cp -r <基座>/packages/sso <基座>/packages/static <业务>/node_modules/sapit-ui-plus/\n ```\n\n9. **`vite build --emptyOutDir false`**:清空 `dist` 会被批量删除守卫拦截;只验证编译时用这个参数,**不要**为了验证去执行会 `git push` 内网仓库的 `npm run build`(对外发布动作,须先确认)。\n10. **不要并发跑两个基座构建 / 业务安装**,避免缓存互相污染。\n11. **`vite build` 不检查未定义变量**:模板/脚本里引用不存在的变量照样通过。改完大段代码必须 `git diff` 复核增删行,配合未使用 import 扫描发现误删。\n12. **npm 国内网络**:`registry.npmjs.org` 基本不通,装 `sapit-ui-plus` 会卡在大包上(最重的是 `ant-design-vue` 解压 78MB、`jodit` 23MB)。装包指定国内源:\n\n ```bash\n npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com\n ```\n\n 若 npm 进程内的 `git ls-remote` 返回 403(沙箱/网络拦截,手工 `git ls-remote` 却通),只能临时摘掉该 git 依赖装其余包,再按第 8 条从基座本地 `dist` 恢复。\n\n13. **npm 包必须含根级 `static/`**:lib 构建不重写 `new URL(\'../../static/...\', import.meta.url)`,运行时从 `lib/js/*.js` 解析到包根 `static/`。缺它业务 dev 登录页图片全 404,而基座自身 dev 正常、生产正常,**极具迷惑性**。\n14. **lib 构建图片**:Vite 对 `build.lib` 强制内联所有资产 → 产物可能出现 MB 级 base64 data URI(超 Chrome URL 上限)。`vite-plugins/sso-plugin` 的 `closeBundle` 会把 >100KB 的 data URI 抽为 `lib/img/` 真实文件;源码资产引用一律改 `import`。\n\n### 6.3 业务字典 / 表单约定(hy-monitor)\n\n15. **下拉 value / 文案一律取字典项的 `value`(字典值),绝不用 `id`(主键)**。字典调`mapByDictTypes(\'a\',\'b\')` 一次性取多个,按**下划线转驼峰**取返回值(`recycle_status` → `res.recycleStatus`),项为 `{label, value, id}`。\n16. **`a-select` 的 placeholder 只在值为 `undefined`/`null` 时显示**,空字符串 `\'\'` 会被视为已有值。所有下拉类字段(搜索参数、表单字段)初始值一律 `undefined`,**禁用 `\'\'`**(多选绑定 `[]` 正常)。\n17. **时间范围参数统一传毫秒时间戳**(`dayjs(x).valueOf()`),不是 unix 秒。依据:源码 `DateRange` 的 onChange 输出 `date.map(o => dayjs(o).valueOf())`,`useFormValues.fieldMapToTime` 默认 `format=\'\'` 原样透传。\n18. **接口请求不写 `catch`**(错误由全局拦截器统一提示)。但三类 catch 必须保留:① 表单校验链 `.catch(() => {})`;② `try { await validate() } catch { return }`;③ `JSON.parse` 解析容错。\n19. **接口报错会跳内置错误页**:HTTP 403(含 301)→ `/403`、404 → `/404`,**在内容区 `router-view` 内切换**(保留侧边菜单与顶栏,不整页顶掉外壳),且不再叠加通知。跳转 URL 带 `?api=<接口地址>&status=<原始状态码>`,错误页据此切换成接口口径文案(403「接口无权限」、301「接口地址已变更」、404「接口不存在」)并显示接口地址;不带 `?api=` 时仍是页面口径(页面无权限 / 页面不存在)。**5xx 不跳错误页**,仍走原来的通知提示(`/500` 页面保留,可直接访问)。后台轮询等非主流程请求若要保住当前页面,可传 `{ skipErrorPage: true }` 跳过跳转:\n\n ```js\n this.$utils.http.post(\'/api/msg/count\', {}, { skipErrorPage: true })\n ```\n\n---\n\n## 七、常见全局方法速查\n\n| 调用 | 作用 |\n| --------------------------------------------------------- | --------------------------------------- |\n| `$l(\'中文\'[, key])` | 国际化 |\n| `$push(path, query)` / `$open(path, query)` | 跳转 / 新窗口(自动拼 base) |\n| `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | 轻提示 / 弹窗 / 通知 / 确认框 |\n| `this.$utils.ls.get/set/clear` | 本地存储 |\n| `this.$utils.http(config)` | 发起请求(默认 POST) |\n| `$filter.dateFormat(v, fmt)` | 日期格式化 |\n| `v-action:code` | 按钮级权限(按 `button_code` 全等匹配) |\n| `$utils.hasAction(code)` | 按钮级权限(函数式,可做「或 / 且」) |\n| `$utils.iconOf(\'info-circle\')` | antd v1 `type` 写法换图标组件 |\n| `$utils.messageFormat(str, values)` | `{0}` / `{name}` 占位符替换 |\n| `$utils.filterSelectOption(iv, opt)` | antd4 版下拉过滤 |\n| `$utils.randomDrawerPlacement()` | 随机抽屉方向 |\n| `var(--s-color)` / `.s-theme-color` | 主题色(CSS 变量 / 工具类) |\n\n---\n\n## 八、在线文档入口\n\n| 地址 | 内容 |\n| ------------------- | ------------------------------------------- |\n| `<base>/docs` | 说明文档(本文) |\n| `<base>/components` | s组件(基座内置组件:左菜单 + 预览 + 源码) |\n', L = '# sapit-ui base framework guide and business usage\n\n> Applies to: <span style="color:#1677ff;font-weight:700">sapit-ui-framework</span> (the base / sources), <span style="color:#1677ff;font-weight:700">sapit-ui-plus</span> (published artifact), <span style="color:#1677ff;font-weight:700">sapit-base-template</span> (business sample).\n>\n> This document is also the data source of the built-in `/docs` page and the `/components` page.\n>\n> Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.\n\n---\n\n## Contents\n\n- [1. Overview](#docs-1Overview)\n- [2. What the base provides](#docs-2Whatthebaseprovides)\n- [3. Layout and height rules](#docs-3Layoutandheightrules)\n- [4. Build and configuration](#docs-4Buildandconfiguration)\n- [5. Business project integration](#docs-5Businessprojectintegration)\n- [6. Caveats](#docs-6Caveats)\n- [7. Global method quick reference](#docs-7Globalmethodquickreference)\n- [8. Online documentation entry](#docs-8Onlinedocumentationentry)\n\n---\n\n## 1. Overview\n\n### 1.1 The five pieces\n\n| Project | Role | Description |\n| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `sapit-ui-framework` | <span style="color:#d4380d">Base (sources)</span> | Library project holding the built-in components and common dependencies, packed in Vite lib mode |\n| `sapit-ui-plus` | <span style="color:#d46b08">Published artifact</span> | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) |\n| `sapit-base-template` | <span style="color:#389e0d">Business consumer</span> | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency |\n\n```text\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\n```\n\n### 1.2 Directory structure (base)\n\n```text\nsapit-ui-framework/\n├─ packages/ # published content source (entry dependency graph)\n│ ├─ index.js # library entry, exports registerGlobalConfig\n│ ├─ components/ # built-in S* components\n│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView\n│ ├─ router/ # constant routes + dynamic routes + static routes + guards\n│ ├─ store/ api/ utils/ locales/ static/ style/\n│ └─ pages/ # login, workplace, todo, message, 404/403/500, docs pages\n├─ docs/ # this document (rendered by the built-in /docs)\n├─ vite-plugins/ # docs-viewer plugin\n├─ src/ # the base\'s own debug shell\n└─ vite.config.js / package.json\n```\n\n---\n\n## 2. What the base provides\n\n### 2.1 Global components\n\n`packages/index.js` uses `import.meta.glob(\'./components/**/*.vue\')` to register every `components/**/*.vue` **by file name**, so templates can use the file name as the tag (e.g. `<s-modal>`, `<s-user-select>`).\n\n| Category | Components |\n| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Layout | `SSkeletonLayout` (skeleton layout: title + button group + content, see 2.16), `SListLayout`, `SListCardLayout` (card list, see 2.19), `SListTableTreeLayout`, `SSuperListLayout` (advanced list, see 2.20), `SFormLayout`, `SPanelLayout`, `SCollapses`/`SCollapsesItem`, `SDrawer` |\n| Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import, see 2.11) |\n| Form / filter | `SForm`, `SFormItem` (multi-column + `full` for a whole row, see 3.4), `SExtendFieldsForm`/`SExtendFieldsFormItem` (dynamic extra fields), `SFilterWrap`, `SFilterItem` (`full` for a whole row, see 3.4), `SFilterToolbar` (filter area shell: main row + more-filters collapse + reset, see 3.4), `STableToolbar` (table area shell: body height auto-fits the content area; used as a pair with `SFilterToolbar`, see 3.4), `SCascader`, `STree`, `STreeSelect`, `SDataRangeTreeSelect` (data-permission scope tree), `SUserSelect`, `SUserSelectButton`, `SChooseUser` (user picker with data permission, see 2.14), `SBelowChoosePosition` (position picker, see 2.15), `SOfficeSelect`, `SIconSelect` (icon dropdown, searchable/multiple), `SIconSelectPopover` (icon grid panel), `SIconModal` (icon browser) |\n| Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` |\n| Display / others | `STab`/`STabItem` (tab bar: arrows + drag when the tabs overflow, see 2.21), `SEditor`, `SEmpty`, `SIcon`, `SSvg`, `SAnchor`, `SColorPicker`, `SToggleLanguage`, `SettingFilter`, `SettingColumns`, `SSideMenu`/`STopMenu` |\n\n> Component usage lives in the built-in component page **`/components`** (two tabs: "s components" and "tools / config"; the latter lists every web-config option and every `$utils` method).\n>\n> Registration rule: `components/**/*.vue` is registered globally **by file name** (`SForm.vue` → `<SForm>`, **not kebab-case**); the later one wins on conflict.\n> `Table/index.jsx` is a `.jsx` file that `import.meta.glob` cannot match, so the base **registers it separately as the global `STable`** in `packages/index.js` (`<s-table>` works without any import).\n> All `@ant-design/icons-vue` icons are registered globally and exposed as `$icons`.\n> Some helper components are internal only: `ModalHeader` (SModal), `CropperModal` (SCopperUpload), `CustomInput`/`SettingColumns`/`SettingFilter` (SSuperListLayout).\n\n### 2.1.1 Choosing a layout component\n\n| Scenario | Use |\n| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| Title + buttons + custom content (no table / pagination / form) | `SSkeletonLayout` (see 2.16, ships with a title bar and permission-aware buttons) |\n| Ordinary list page | `SListLayout` |\n| Card list | `SListCardLayout` (card grid + three slots, see 2.19) |\n| List + left tree | `SListTableTreeLayout` (the left tree container class must be `.side.s-side-tree`, see 3.5) |\n| List with advanced search / table | `SSuperListLayout` (column settings + advanced filter, see 2.20) |\n| Add / edit / detail (routed) | `SFormLayout` (`#form` slot holds `SForm`; `#footer-callback` receives `save`/`cancel`/`prev`/`next`) |\n| Form as modal content | `SModal` (do not nest `SFormLayout`) |\n| Dynamic form driven by backend fields | `SExtendFieldsForm` (`data` + `defaultValue`; the ref exposes `validate/clearValidate/getModel`) |\n| Data-permission scope selection | `SDataRangeTreeSelect` (`autoSysConfig` manages the system `dataScope` config) |\n\n### 2.2 Global properties / methods\n\nAvailable after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`):\n\n| Name | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `$registerGlobalConfig(config, pages)` | Initialization entry (see 5.2) |\n| `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers |\n| `env` | Merged environment configuration (= `$utils.env`) |\n| `$i18n` / `$l(name, key)` | Internationalization (see 2.7). Lives on `globalProperties`: usable **directly in templates** as `$l(\'xx\')`; inside `<script setup>` **scripts** you must call `window.$l(\'xx\')` (setup has no `this`) |\n| `$theme` / `$staticRoutes` / `$pinia` | Theme object / static route list / user store instance |\n| `$modal` / `$message` / `$notice` / `$confirm` | antd `Modal` / `message` / `notification` / `Modal.confirm` (list component button api branch calls `this.$confirm`) |\n| `$push(path, query)` / `$open(...)` | In-app navigation / new window (automatically prefixes `VITE_APP_BASE_URL`) |\n| `$filter` / `$icons` / `$socket` | Date formatting / icon collection / websocket wrapper. `$icons` maps every `@ant-design/icons-vue` icon by **Pascal name** (`InfoCircleOutlined`) and is **also exposed on `window.$icons`** (so `$utils.iconOf` works outside components). Legacy antd v1 `<a-icon type="info-circle">` names convert via `$utils.iconOf(\'info-circle\')`; `SIcon`\'s `name` only accepts Pascal names |\n| `$getPdf({ el, title })` | Export the page to PDF (Vue3 port of the legacy `Vue.prototype.getPdf`). Pass the capture container and file name explicitly: `<a-button @click="$getPdf({ el: \'#pdfDom\', title: htmlTitle })">Export</a-button>`. `html2canvas` + `jsPDF` are **imported dynamically**, so nothing loads until the button is clicked; A4 pagination is automatic and it returns `Promise<boolean>`. Optional `fileName` / `scale` / `backgroundColor` / `beforeCapture` / `afterCapture` / `onError`. A dollar-less `getPdf` alias is registered for legacy code (default container `#pdfDom`, title from `document.title`) |\n\n### 2.3 Layouts\n\n`packages/layouts/index.js`: `BasicLayout` (header + side menu + content), `BlankLayout`, `UserLayout` (login), `RouteView`, `PageView`.\n\nThe height chain of `BasicLayout` (**business layout components must match it**, see chapter 3):\n\n```text\n.basic-layout-common (100vh)\n→ .ant-layout\n→ .main-content\n→ .container (height = mainHeight = clientHeight - headerHeight)\n └─ minus footerHeight(56) when the footer is shown\n → router-view (height = contentHeight, overflow: hidden auto)\n → business layout component (.list-layout / .form-layout, flex:1)\n```\n\n> `mainHeight` / `contentHeight` are computed from the **real `header.offsetHeight`** (not a hard-coded 58) so the layout cannot disagree with the actual rendering and produce overflow scrollbars.\n\n### 2.4 Routes\n\n**Constant routes** (`packages/router/index.js`):\n\n| Path | Description |\n| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/login/index` | Login page (base default, can be overridden by the business, see 5.3) |\n| `/login/:officeCode` | Same page entered with an office code (written to `$utils.ls` as `officeCode` and reused for later logins) |\n| `/user/qrCode`, `/user/forgotPassword`, `/user/activate` | QR login / forgot password / account activation pages. The parent `/user` carries `meta.public`, so they are **reachable before login**; `/user/login` redirects to `VITE_APP_LOGIN_PATH` (see 2.10) |\n| `/workplace/index` | Default home (`VITE_APP_DEFAULT_PATH`, overridable) |\n| `/workbench/index`, `/message/index` | Workbench / messages |\n| `/docs`, `/components` | Built-in docs / component pages (`public` = no login, `hidden` = not in the menu) |\n| `/404`, `/403`, `/500`, `/:pathMatch(.*)*` | Error pages; the catch-all renders 404 (**no redirect**, so refreshing dynamic routes never lands on a 404). All four sit under `BasicLayout` and swap **only the content-area `router-view`**, keeping the sidebar and header untouched |\n\n> Redirect rules, query parameters, wording and color overrides for the error pages are documented in [2.17 Error pages](#docs-217Errorpages301403404500).\n\n**Static routes** (`staticRoutes`, independent of backend menus): see 5.4. The base ships `/docs` and `/components`.\n\n**Dynamic routes** (`packages/router/generator-routers.js`): after login a tree is generated from the backend `menus`, rooted at `BasicLayout`; leaf nodes use `item.hrefs` to match business `pages` (keys of `import.meta.glob(\'@/views/**/*.vue\')`) and fall back to 404 when nothing matches. Registration happens inside the guard (memory flag, re-registered on refresh).\n\n**Guards**: public pages (`meta.public`) pass straight through; the token is read live; unauthenticated users are redirected to login; an authenticated user visiting the login page or the root is sent to the default home; a failed user-info fetch clears state and returns to login (so nothing stays pending). When the URL carries a `code`, the guard exchanges it for a token (see 5.8 permissions and 6.1).\n\n### 2.5 State management (pinia)\n\n`packages/store/user.js` (`useUserStore`): state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`; actions `Info()` (fetch and write to localStorage), `setDynamicRouter()`, `setMenuOpenKeys()`; persisted in localStorage.\n\n### 2.6 Utilities (`$utils`)\n\n| Module | Description |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$utils.env` | Environment configuration object |\n| `$utils.ls` | Local storage (namespace `VITE_APP_SYS_SERVER_NAME`) |\n| `$utils.http` | axios instance (token/`client-id` injection, response unwrapping, login timeout, file download) |\n| `parseAppUrl` / `innerRedirect` etc. | Build in-app URLs with the base (sub-path aware); external http(s) URLs are kept as-is |\n| `messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution (confirm dialogs etc.) |\n| `filterSelectOption(iv, opt)` | antd4-ready `:filterOption` (reads `option.label` / `option.value`) |\n| `randomDrawerPlacement()` | Randomly returns `left` / `right` / `top` / `bottom` (kept from the source project) |\n| `getTableHeight({ selector, offset })` | List table height = window height − search area − offset (defaults `.table-page-search-wrapper` / `320`; no-arg call keeps legacy behaviour). **Only for legacy fixed-height lists** — `SListLayout` uses flex sizing |\n| `iconOf(type)` | Converts legacy antd v1 `<a-icon type="info-circle">` names: kebab / snake / Pascal in → icon component. Usage: `<component :is="$utils.iconOf(\'info-circle\')" />` |\n| `hasAction(name)` | Functional button-level permission check, same source as `v-action`; for `v-if` OR / AND logic and `disabled` computation |\n| Others | Type checks, dates, arrays, url, dom, debounce/throttle, money, phone validation, etc. |\n\n> ⚠️ **Type checks are not format validation**: `$utils.isNumber` / `isInt` / `isDate` use `Object.prototype.toString` (`$utils.isNumber(\'123\')` is always `false`). They are **not** string-format validators; a business-side regex version with the same name must **not** be replaced by them.\n>\n> Likewise `$utils.uuid(len)` returns a purely random string, a different shape from a "timestamp + random" `getUUID()` — do not swap them when the value feeds backend keys.\n\n`v-action:xxx` is the button-level permission directive: `<a-button v-action="\'add\'">Add</a-button>`.\n\n- It delegates to `$utils.hasAction(actionName)` — the directive and the function share **one** decision path\n- Source priority: `permission` (**singular**, the current route\'s button array written by the `router/index.js` guard) → falls back to `permissions` (**plural**, the full route → buttons map written by `store/user.js`) + `CURRENT_ROUTER_KEY`\n- Matching rule: `String(button_code) === String(actionName)`, **exact equality** (`add` no longer matches `batchAdd`)\n- Functional usage: `<a-button v-if="$utils.hasAction(\'add\') || $utils.hasAction(\'edit\')">`\n\n### 2.7 Internationalization\n\nA language pack is a file named `i18n.js` placed directly in a module\'s top-level folder, with no prefix, and its shape is a flat dictionary:\n\n```js\n// src/views/user/i18n.js -> namespace user\nexport default {\n \'<source text>\': \'Cancel\'\n}\n```\n\nThe namespace is the first path segment after `views/` or `packages/` (`views/user/i18n.js` → `user`, `packages/components/i18n.js` → `components`). Packs are aggregated at build time by `import.meta.glob`, so adding files or folders requires no code change.\n\nRegister the namespace inside the page, then call `$l(\'<source text>\')` directly — never `$l(\'user.<source text>\')`:\n\n```js\nexport default {\n created() {\n this.useI18n(\'user\') // Options API\n }\n}\n```\n\n```js\n// also works inside <script setup>\nconst { $l } = useI18n(\'user\')\n```\n\nLookup order for `$l(name)`: **namespace registered by the current component → global fallback dictionary (`packages/locales/lang/dict.js`) → the name itself**. `useI18n` logs a `console.warn` (non-blocking) when the namespace does not exist.\n\n| Call site | Usage | Namespace |\n| --------------------------------------------- | ---------------------------- | ------------------------------------------- |\n| Template / inside a component, `this.$l(...)` | `{{ $l(\'<source text>\') }}` | yes, the one registered via `useI18n` first |\n| Plain JS outside components (api / utils) | `window.$l(\'<source text>\')` | no, global dictionary only |\n\nIn Chinese mode the source text is returned as-is; in English mode, a missing translation falls back to the source text. antd\'s own locale is controlled by `a-config-provider`\'s `locale`.\n\n### 2.8 Theme\n\nDefinitions are maintained by the base only: `VITE_APP_THEME` in `packages/config/web-config.js` (each set carries `color/lightColor/darkColor/borderColor/bgColor`); the business only picks one with `VITE_APP_THEME_VALUE` (`blue`/`green`/`orange`). A `VITE_APP_THEME` coming from the business or `config.json` is ignored.\n\nHow it takes effect:\n\n1. **antd**: `a-config-provider` tokens (`colorPrimary`/`colorLink`).\n2. **CSS variables**: on startup the selected theme is resolved into the full token set and written to `:root` (10 primary-family + 11 semantic + 11 neutral tokens, see the table below); the utility classes `.s-theme-bg`, `.s-theme-color`, `.s-theme-border`, `.s-theme-border-top`, `.s-theme-icon-bg` are built in.\n3. **body class**: `theme-<VITE_APP_THEME_VALUE>` (e.g. `theme-blue`).\n4. **Menu palette**: on startup the palette is **derived from the primary color** (`light`) or fixed to **antd black** (`dark`) and **emitted as solid `#rrggbb` only — no alpha**. It is written to `:root` as `--s-menu-bg`, `--s-menu-sub-bg`, `--s-menu-text`, `--s-menu-text-hover`, `--s-menu-text-active`, `--s-menu-hover-bg`, `--s-menu-active-bg`, `--s-menu-active-text`, plus `window.$menuTheme` (a `reactive` object carrying the antd `Menu` tokens and an `isLightBg` flag).\n\nThe menu defaults to `light` with backgrounds derived from the primary color (orange `#f9f1e1` / blue `#e1ebf9` / green `#e1f9ef`). **The colors are owned by the base**: the business can only pick `light` or `dark` via `VITE_APP_MENU_THEME`; color values written into the business `.env` / `config.json` are forced back to the base defaults. **Palette derivation, OS light / dark following and the locking mechanism live in [2.18 Menu palette](#docs-218Menupalettesidetop)**.\n\n> In `light` only the text colors follow the primary hue (blue → `#344051`, green → `#345145`); backgrounds stay fixed, so switching `VITE_APP_THEME_VALUE` keeps the pale blue menu and still holds a contrast ratio >= 4.6. The side menu, the top menu (`VITE_APP_MENU_BAR: \'top\'`), the logo variant and the header text color all share `window.$menuTheme.isLightBg`.\n\n```css\n.my-box {\n color: var(--s-color);\n background: var(--s-bg-color);\n}\n```\n\n**Full token set** (resolved by `packages/utils/theme-vars.js` into `:root` on startup; components and business code use `var(--s-*)` only, never literal colors):\n\n| Group | Token | Default (blue) | Notes |\n| -------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------- |\n| Primary family | `--s-color` | `#1677ff` | Primary color from `VITE_APP_THEME` |\n| | `--s-light-color`, `--s-dark-color`, `--s-border-color`, `--s-bg-color` | `#6495ed`, `#00008b`, `#b0c4de`, `#f0f2f5` | Taken straight from the theme |\n| | `--s-color-hover` / `--s-color-active` | `#4592ff` / `#146be6` | Hover (+20% white) / active (+10% black) |\n| | `--s-color-bg` / `--s-color-bg-hover` / `--s-color-border` | `#e8f1ff` / `#d5e7ff` / `#adcfff` | Selected tint / hover tint / light border |\n| Semantic | `--s-color-success`, `--s-color-warning`, `--s-color-error`, `--s-color-info` | `#52c41a`, `#faad14`, `#ff4d4f`, `#1677ff` | Status semantics, theme independent |\n| | `--s-color-success-bg`, `--s-color-warning-bg`, `--s-color-error-bg` | `#f6ffed`, `#fffbe6`, `#fff1f0` | Status tints |\n| | `--s-color-warning-light` / `--s-color-error-light` | `#ffc069` / `#ff7875` | Light status variants (error pages) |\n| | `--s-color-warning-border` / `--s-color-error-border` | `rgba(250,140,22,.42)` / `rgba(245,34,45,.42)` | Translucent status borders |\n| Neutral | `--s-text-color` | `#262626` | Primary text |\n| | `--s-text-color-regular` | `#595959` | Regular text |\n| | `--s-text-color-secondary`, `--s-text-color-disabled`, `--s-text-color-inverse` | `#8c8c8c`, `#bfbfbf`, `#ffffff` | Secondary / disabled / inverse |\n| | `--s-border-color-base`, `--s-border-color-light`, `--s-border-color-split` | `#d9d9d9`, `#e8e8e8`, `#f0f0f0` | Three border levels |\n| | `--s-bg-color-container` / `--s-bg-color-hover` | `#ffffff` / `#f5f5f5` | Container / hover background |\n| | `--s-mask-color` | `rgba(0,0,0,.45)` | Mask |\n\n> Components no longer contain literal colors: primary-related values use the primary tokens, greys use the neutral tokens, statuses use the semantic tokens. New components must follow the same rule — no more `#1677ff` / `#e8e8e8` / `rgba(0,0,0,.65)`.\n\n> Adding a theme: append a set to the base `VITE_APP_THEME`, select it with the business `VITE_APP_THEME_VALUE`, and antd plus `var(--s-*)` follow automatically.\n\n### 2.9 API / page components / others\n\n- `packages/api`: `login.js` (login, `getCode`, `verify`, `rsaPublicKey`, `getLoginConfig`, ...), `common.js`, `upload.js`, `workbench.js`.\n- `packages/pages`: `login.vue`, `login-common/LoginForm.vue`, `workbench.vue`, `todo.vue`, `message.vue`, `403/404/500.vue`, `docs.vue`, `components-doc.vue`.\n- Static assets live in `packages/static/*`, styles in `packages/style/*`; antd icons, axios, dayjs, moment, pinia, vue-router, vue-i18n, jodit, vue-cropper, vuedraggable, html2canvas, crypto-js, jsencrypt, nprogress, qs, lodash.\\* and more are already bundled.\n\n### 2.10 Login / SSO\n\n- Login page `/login/index`: account + password. Once failures reach the `getLoginConfig` policy (`enabled` + `codeThreshold`), an **image captcha** appears (`/user/verify`); `verificationCode` is submitted as plain text together with `verificationCodeId`.\n- SSO callback: when the URL carries a `code`, the **guard** calls `getCode(code)` to exchange it for a token → stores it via `$utils.ls` → strips the code and does a full page reload (same as the reference project).\n- Related configuration: `VITE_APP_CLIENT_ID` must equal the client registered in the auth center; the API gateway uses `VITE_APP_PORTAL_SERVER_NAME`.\n\n**Four login themes** (`VITE_APP_LOGIN_PATH_THEME`, `1`~`4`; an unset or invalid value falls back to `1`):\n\n`packages/pages/login/index.vue` only resolves the theme id, passes `logo`/`sysName` down and renders the language switcher. Each layout lives in its own page-level component under `login-themes/`, so they are independent and can be edited separately.\n\n| Id | Component | Layout |\n| -- | ------------------ | ----------------------------------------------------------------------------------- |\n| 1 | `LoginTheme1.vue` | Split screen: `login-cover.png` + logo + system name on the left, form on the right |\n| 2 | `LoginTheme2.vue` | Full-bleed `login-cover-right.png`, form pinned left (`padding-left: 336px`) |\n| 3 | `LoginTheme3.vue` | Full-bleed `login-cover-center.png`, form centred (**web-config default**) |\n| 4 | `LoginTheme4.vue` | Dark-blue brand panel + white card, same as the portal ops console (full version) |\n\n**Theme 4 capabilities** (`login-themes/LoginTheme4.vue`):\n\n- Account/password login + remember me (stores `LOGIN_ACCOUNT`, account only, never the password).\n- Image captcha: shown once failures reach the `getLoginConfig` threshold; click the image to refresh.\n- Account lock countdown: when the backend returns `lockUser` (`lockEndTime`/`nowTime`) the button switches to `a-statistic-countdown` and login stays disabled until it ends.\n- "Activate account" entry: visibility is driven by `defaultActivateAccount` from `getSysAccountConfig`.\n- "Forgot password" / "QR login": navigate to the built-in `/user/forgotPassword` and `/user/qrCode`.\n- Office code: entering via `/login/:officeCode` stores the code as `officeCode` in `$utils.ls`.\n- After a successful login: writes `token` / `USER-TOKEN`; when `redirect_client_id` is present it resolves the client list and hands over to `sso.html` for client authorization, otherwise it returns to `VITE_APP_DEFAULT_PATH`.\n- The form column is **flex-centred** (`align-items: safe center` + `justify-content: center`). It deliberately avoids `overflow-y: auto`: the parent `.login-page` is `overflow: hidden`, so scrolling cannot rescue a clipped card; `safe center` degrades to top alignment when the viewport is too short, so the top of the card is never pushed out of view.\n\n**Login helper pages** (`packages/pages/login/`, all `meta.public`, reachable before login):\n\n| Route | Component | Description |\n| ---------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `/user/qrCode` | `qr-code.vue` | QR login: fetches a key via `qrLogin/generate`, renders with `a-qrcode`, counts down validity, expired overlay + refresh |\n| `/user/forgotPassword` | `forgot-password.vue` | Four steps: pick method → account info → verify code (gets a temporary token) → set new password; policy from `sysPwdConfig` |\n| `/user/activate` | `activate.vue` | Four steps: identity check (+captcha) → SMS/email code → set password (strength bar) → completion summary card |\n| `/user/login` | — | Redirects to `VITE_APP_LOGIN_PATH`; used by the "back to login" links on the three pages |\n\n**Account APIs** live in `packages/api/account.js` (pre-login whitelist chain, gateway `VITE_APP_PORTAL_SERVER_NAME`):\n\n| Method | Description |\n| --- | --- |\n| `getSysAccountConfig` | Activation entry switch (`sysAccountConfig/listByActivate`) |\n| `getPwdConfig` | Password policy (`sysPwdConfig/getFirstData`) |\n| `getLoginQrCodeKey` | QR login key (`qrLogin/generate`) |\n| `getValidationCodeWithoutToken` | Send reset-password verification code |\n| `checkValidationCodeWithoutToken` | Verify code → temporary `access_token` |\n| `updatePasswordWithoutToken` | Reset password with the temporary token (account/password Base64, token via the `user-token` header) |\n| `checkUseInfo` | Activation identity check |\n| `getActivateValidationCode` | Send activation code |\n| `checkActivateValidationCode` | Verify activation code |\n| `activateUpdatePassword` | Set the password during activation |\n\n**SSO static assets are now part of the base**: the sources live in `packages/sso/` (`sso.js` / `sso.html`) and ship with the npm package (`sso` is listed in `files`, and the build copies `dist/sso`). Business projects **no longer maintain sso files under `public/`**; just add this to `vite.config.js`:\n\n```js\nimport ssoPlugin from \'sapit-ui-plus/vite-plugins/sso-plugin.js\'\nssoPlugin()\n```\n\nIn dev the plugin middleware serves them (registered before the internal middleware, shadowing `public` with the packaged version). `sso.html` reads the **same-origin localStorage** (wrapped by vue-ls) when exchanging the token, so a cross-origin platform SSO cannot be used directly.\n\n> ⚠️ `redirect_uri` supports the `{code}` placeholder; **without the placeholder the jump is raw and the code is not exchanged**.\n> The platform standard requires `?code={code}` — keep that in the portal client\'s `redirectUri`, do not "optimize" the placeholder away.\n\n### 2.11 SImportModal — generic bulk import modal\n\nThree-step import: **upload file → data preview (rows editable / deletable) → import result (with exception export)**. File limits: `.xls/.xlsx`, ≤ 500KB.\n\n```vue\n<s-import-modal\n ref="importModalRef"\n :upload-url="IMPORT_UPLOAD_URL"\n :columns="importColumns"\n :apis="importApis"\n :type-select="importTypeSelect"\n @reload="handChange"\n/>\n\n<script setup>\nimportModalRef.value.show() // open the modal (it resets its own state)\n\nconst importApis = { templateDownload, importPreview, importData, exportExceptionData }\nconst importColumns = [{ title: \'Device SN\', dataIndex: \'sn\', width: 150 }]\n// optional: a business-parameter dropdown passed with the import; its value is submitted with every API call via extraKey\nconst importTypeSelect = computed(() => ({\n options: [{ label: \'Camera\', value: \'1\' }],\n placeholder: \'Select device category\'\n}))\n<\/script>\n```\n\n| props | Type | Default | Description |\n| ------------ | --------------- | ---------------- | ------------------------------------------------------------------------------ |\n| `value` | Boolean | `false` | Visibility (`v-model:value`) |\n| `title` | String | `Bulk import` | Modal title |\n| `width` | String / Number | `1000` | Modal width |\n| `uploadUrl` | String | `\'\'` | Upload endpoint (full gateway address, e.g. `/monitor/DeviceInfo/Uploader`) |\n| `columns` | Array | `[]` | Preview / result table columns `[{ title, dataIndex, width }]` |\n| `apis` | Object | `{}` | The four import APIs (see below) |\n| `typeSelect` | Object | `null` | `{ options, placeholder, loading }`; omit when no business parameter is needed |\n| `extraKey` | String | `\'deviceTypeId\'` | Field name used to submit the `typeSelect` value |\n\n| events | Description |\n| -------------- | -------------------------------------------------------- |\n| `update:value` | Visibility change (`v-model`) |\n| `reload` | List must be refreshed after a successful import / close |\n\n| methods (via ref) | Description |\n| ----------------- | ---------------------------------- |\n| `show()` | Open the modal and reset its state |\n\nAPI contract (all return a Promise; the component accepts both `{ code, data }` and plain data):\n\n| API | Input | Output |\n| --------------------- | ------------------------------ | --------------------------------------------------------- |\n| `templateDownload` | `{ ...extraParams }` | `{ url }` (the component triggers the download) |\n| `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` |\n| `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` |\n| `exportExceptionData` | `{ list, ...extra }` | `{ url }` |\n| Upload (internal) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }` (later APIs receive fileName) |\n\n> ⚠️ `SImportModal` is **three-step** (upload → preview/edit → result/exception export).\n> If a business project has a **single-step** import component that imports as soon as a file is chosen (e.g. hy-monitor\'s `views/people/components/ImportModal.vue`, `views/basicData/components/ImportModal.vue`),\n> the two differ in layout, API, events and the contract with the calling page, so **they must not be swapped for one another** — keep each implementation.\n\n### 2.12 SDataRangeTreeSelect — data permission scope tree\n\nSelects a data permission scope (organization / campus / unit); internally calls `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode(\'dataScope\')`.\n\n```vue\n<s-data-range-tree-select v-model:value="ids" :auto-sys-config="true" />\n```\n\nCommon props: `value` (array of ids) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup` (`\'1\'` organization, `\'2\'` campus, `\'3\'` unit; an array is allowed) / `showOnlyOrganization` / `treeSelectData` (pass an array to skip the request) / `isDataScopeFilter` / `autoSysConfig` / `defaultValue`.\nevents: `update:value`, `change` (both emit an **array of ids**).\n\n> ⚠️ The template hard-codes `label-in-value` + `tree-check-strictly`, so antd requires `value` to be an array of `{ label, value }` objects.\n> Therefore **echoing back a value must first convert ids with `getOfficeByIds(ids)`**; assigning raw id strings raises an `Invalid prop value` warning and the input shows bare numeric ids.\n\n### 2.13 SExtendFieldsForm — dynamic extra field form\n\nThe backend delivers field configuration (`fillModeConfig` is a JSON string containing `showType` / `config`) and the front end renders from it.\n\n```vue\n<s-extend-fields-form ref="extRef" :data="fields" :default-value="values" type="edit" :cols="2" />\n<script setup>\n// the ref exposes three methods\nextRef.value.validate() // Promise<boolean>\nextRef.value.clearValidate()\nextRef.value.getModel() // [{ fieldCode, value }] (object values are already JSON.stringify\'d)\n<\/script>\n```\n\n| props | Type | Default | Description |\n| -------------- | ------ | ------- | -------------------------------------------------------- |\n| `data` | Array | `[]` | Field definitions (`fieldCode/fieldName/fillModeConfig`) |\n| `type` | String | `\'add\'` | `add` / `edit` / `view` (`view` skips validation) |\n| `defaultValue` | Array | `[]` | Values echoed in edit mode `[ { fieldCode, value } ]` |\n| `cols` | Number | `2` | Columns per row (non-full-width fields take `100/cols%`) |\n| `labelWidth` | String | `auto\'` | Label width |\n\n`showType` values that automatically take the whole row: `textarea`, `upload`, and `select` with `config.multiple`. Default values are converted per `showType`: `datePicker` → dayjs object, `number` → Number, multi-select `select` → comma-split array.\n\n### 2.14 SChooseUser — user picker modal (with data permission)\n\nModal user picker: organization tree on the left, user list on the right (avatar / name / employee or student number + unit). The search area contains a **user-type filter** (all / staff / student / external), and it supports single or multiple selection, scroll paging, select-all / invert, and a selected list on the right in multi-select mode. **The modal closes automatically after confirming.**\n\nHow it differs from `SUserSelect` (the criteria for choosing between them):\n\n| Aspect | `SUserSelect` | `SChooseUser` |\n| --------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| Shape | Read-only input plus an integrated modal | Pure modal; visibility controlled by the business |\n| Data permission | Tree / list APIs carry no data permission | Uses `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`, **filtered by the logged-in user\'s permission** |\n| User type | No filter | Built-in staff / student / external filter |\n| Value contract | `v-model:value` binds ids directly (string for single, array for multiple) | `v-model:value` controls visibility; `v-model:selectedIds`/`selectedId` bind selected ids; `@callback` emits the **list of selected objects** |\n\n```vue\n<s-choose-user\n v-model:value="userScopeVisible"\n v-model:selectedIds="userScopeIds"\n :multiple="true"\n @callback="userScopeCallback"\n/>\n<script setup>\n// confirm (single or multiple): payload = [{ id, name, cover, userid, company, department }] (a single pick is a one-element array)\n// cancel / close: payload = undefined\nconst userScopeCallback = (payload) => {\n if (payload) userNames.value = payload.map((u) => u.name).join(\',\')\n userScopeVisible.value = false\n}\n<\/script>\n```\n\n| props | Type | Default | Description |\n| ------------------- | ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| `value` | Boolean | `false` | Modal visibility (`v-model:value`) |\n| `title` | String | `Select users` | Modal title |\n| `multiple` | Boolean | `false` | Multiple selection (the selected list appears on the right) |\n| `searchPlaceholder` | String | `Search by name, employee/student number or phone` | Search box placeholder |\n| `required` | Boolean | `false` | When nothing is selected, confirming warns and does not close |\n| `selectedIds` | Array | `[]` | Echoed id array for multi-select (`v-model:selectedIds`); `getBUseryIds` loads objects |\n| `selectedId` | String | `\'\'` | Echoed id for single select (`v-model:selectedId`); `getUserById` loads the object |\n\n| events | Description |\n| -------------------- | -------------------------------------------------------------------------------- |\n| `update:value` | Modal closed (both confirm and cancel set it to `false`, no manual close needed) |\n| `update:selectedIds` | Two-way binding of the selected id array |\n| `update:selectedId` | Selected id in single-select mode |\n| `callback` | On confirm emits the selected objects **array**; nothing on close |\n\n> ⚠️ All APIs live in the base `packages/api/common.js` (`findUsersWithAuth` = `/user/users/authorized`, etc.), so the business passes none; an empty tree/list in a backend-less preview environment is expected. In the list, `userid` shows `loginName` (employee / student number).\n\n### 2.15 SBelowChoosePosition — position picker modal\n\nModal **position** picker (originally from the business project\'s `/components/BelowChoosePosition`, now part of the base): the left tree loads the whole tree of "the root node and every unit below it" in one call (`getBelowUnit`, scope determined by `rootId`), while the right list queries positions (`findJobs`); single and multiple selection are supported.\n\nHow it differs from the other base selectors: `SOfficeSelect`/`SUserSelect` query organizations/users with a lazily loaded left tree, whereas this component queries **positions** with a fully loaded tree. **It does not close automatically after confirming**; the business must close it in `callback` (same behaviour as the source project).\n\n```vue\n<s-below-choose-position\n v-model:value="visible"\n v-model:selectedIds="positionIds"\n multiple\n :root-id="campusId"\n @callback="onCallback"\n/>\n<script setup>\n// confirm (multiple): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }\n// confirm (single): payload = { selected: { id, name, ... } }\n// cancel / close: payload = false\nconst onCallback = (payload) => {\n if (payload && payload.selectedList) {\n names.value = payload.selectedList.map((i) => i.name).join(\',\')\n }\n visible.value = false // the component does not close on confirm, so close it manually\n}\n<\/script>\n```\n\nThe props match `SChooseUser` (`title` defaults to `Select position`, `searchPlaceholder` to `Search by position name or code`), plus one component-specific prop:\n\n| props | Type | Default | Description |\n| -------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------- |\n| `rootId` | String | `\'\'` | Left tree root id, which defines the data scope; changing it reloads the tree, `\'-1\'` is used when omitted |\n\n| methods (via ref) | Description |\n| ---------------------- | ----------------------------- |\n| `initLeftTreeData(id)` | Manually reload the left tree |\n\n| events | Description |\n| -------------------- | --------------------------------------------------------------------------- |\n| `update:value` | Set to `false` only on cancel; **confirm does not close the modal** |\n| `update:selectedIds` | Two-way binding of the selected position ids (echo uses `getPositionByIds`) |\n| `update:selectedId` | Single-select id (echo uses `getPositionById`) |\n| `callback` | Confirm emits `{ selectedList }` / `{ selected }`; close emits `false` |\n\n> ⚠️ The `callback` payload shape differs from `SChooseUser` (an object `{ selectedList }` versus an array) and the close-on-confirm behaviour is the opposite, so the two callbacks are not interchangeable.\n\n---\n\n### 2.16 SSkeletonLayout — skeleton layout (title + button group + content)\n\n> Added 2026-10-28. A page-level "title bar + action buttons + content area" shell. Same tier as `SListLayout` / `SFormLayout` but lighter: **no table, no form, no pagination** — the content area is entirely up to the slot.\n\n```vue\n<s-skeleton-layout\n :title="$l(\'Collection jobs\')"\n :buttons="[\n { key: \'add\', name: \'Add\', icon: true },\n { key: \'remove\', name: \'Delete\', disabled: true },\n { key: \'export\', name: \'Export\', icon: \'DownloadOutlined\' }\n ]"\n bg-color="#fff"\n @btnCallback="onBtnClick"\n>\n <div class="my-content">...</div>\n <template #otherBtns><a-button>Custom</a-button></template>\n <template #other>Footer content</template>\n</s-skeleton-layout>\n```\n\n| props | Type | Default | Description |\n| -------------------- | ------ | ------- | ------------------------------ |\n| `title` | String | — | **Required** title bar text |\n| `buttons` | Array | `[]` | Button config array, see below |\n| Each `buttons` item: |\n\n| Field | Type | Description |\n| ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `key` | String | Unique key, emitted on click; `\'add\'` makes the button `primary` by default |\n| `name` | String | Button label (passed through `$l`, so the source Chinese text is fine) |\n| `icon` | String \\| Boolean | String = icon component name (e.g. `\'PlusOutlined\'`); `true` = look up the built-in iconMap by `key`; omit for no icon |\n| `action` | String | `v-action` permission code, defaults to `key` (real permission filtering — unauthorised buttons are removed) |\n| `show` | Boolean | Default `true`; `false` hides via `v-show` (keeps layout, still permission-registered) |\n| `disabled` | Boolean | Greyed out |\n| `type` | String | Overrides `a-button`\'s `type` |\n\n| slots | Description |\n| ----------- | ----------------------------------------- |\n| default | Content area (`.skeleton-layout-main`) |\n| `otherBtns` | Appended to the right of the button group |\n| `other` | Bottom area |\n\n| events | Description |\n| ------------- | -------------------------------- |\n| `btnCallback` | Emits the clicked button\'s `key` |\n\n| methods (via ref) | Description |\n| ----------------- | --------------------------------------------------------------------------- |\n| — | **None.** Height is allocated by flex; no method call is needed (see below) |\n\nBuilt-in iconMap keys: `add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`.\n\n> **Height implementation (revised 2026-10-28)**: root `height:100%; display:flex; flex-direction:column`, title bar `flex:0 0 60px`, content area `flex:1 1 auto; min-height:0; overflow:hidden auto`, bottom slot `flex:0 0 auto`. **Zero JS, no resize listener** — follows window resize / sidebar collapse automatically.\n>\n> Prerequisite: the parent container must have a definite height. The base `BasicLayout` already renders `router-view` with `:style="{ height: contentHeight + \'px\' }"`, which falls through to the page root component, so usually nothing extra is needed; a custom `height:auto` wrapper must be given a definite height.\n>\n> The old `initLayoutHeight()` method **has been removed**, and `layoutHeight` is no longer exposed (the previous implementation was `parentNode.offsetHeight - 76`, computed only once on `mounted`).\n\n---\n\n### 2.17 Error pages (301 / 403 / 404 / 500)\n\nThe base ships three error pages. **One page serves both "the page itself failed" and "an API failed"**, and the wording is selected by the `?api=` query parameter.\n\n| Path | Component | Status sources | Accent |\n| ------ | --------------- | ------------------------------------------------------------------------------------- | ------------------------------ |\n| `/403` | `pages/403.vue` | API 403 (no permission), API 301 (address changed), page without permission | Orange `#fa8c16` |\n| `/404` | `pages/404.vue` | No route matched (catch-all `/:pathMatch(.*)*`), API 404 | Primary color `var(--s-color)` |\n| `/500` | `pages/500.vue` | Reachable directly only; **API 5xx does not redirect**, it still shows a notification | Red `#f5222d` |\n\n**Where they render**: `buildErrorRoute()` wraps all three under `BasicLayout` as nested children (`children: [{ path: \'\' }]`) — navigation **replaces only the content-area `router-view`**, leaving the sidebar, header and footer untouched. The route-miss 404 (catch-all) and the API 404 share the same structure and behave identically.\n\n**Login-free**: `/403`, `/404` and `/500` carry `meta.public` (an API failure may mean the token is already gone, and the page must not get stuck in the login guard); the catch-all `/:pathMatch(.*)*` **does not** — an unauthenticated visit to an unknown URL still goes to login.\n\n**API status mapping** (`packages/utils/request.js`):\n\n| HTTP status | Behaviour | Target URL |\n| ------------------------- | --------------------------------------------------------- | --------------------------------------- |\n| 301 | Go to the 403 page with the "API address changed" wording | `/403?api=<api>&status=301&from=<page>` |\n| 403 | Go to the 403 page with the "no API permission" wording | `/403?api=<api>&status=403&from=<page>` |\n| 404 | Go to the 404 page with the "API does not exist" wording | `/404?api=<api>&status=404&from=<page>` |\n| Anything else (incl. 5xx) | **No redirect**, a notification is shown as before | — |\n\n**Query parameters**:\n\n| Parameter | Meaning |\n| --------- | ---------------------------------------------------------------------------------------------- |\n| `api` | Failing API address. **Its presence switches to the API wording**; page-level failures omit it |\n| `status` | Original status code; `301` gets its own "API address changed" wording |\n| `from` | Source page address (with `VITE_APP_BASE_URL` stripped), rendered as the "source address" line |\n\nWording matrix:\n\n| Source | 403 page | 404 page |\n| ---------------- | ---------------------------- | ------------------ |\n| Page (no `api`) | Insufficient page permission | Page not found |\n| API (with `api`) | No API permission | API does not exist |\n| API 301 | API address changed | — |\n\nThe two buttons: "Back to home" uses `VITE_APP_DEFAULT_PATH` (default `/workplace/index`); "Back" calls `router.back()` and falls back to home when there is no history, so the button is never dead.\n\n**Skipping the redirect** (polling, auxiliary requests — keeps one failing side request from taking over the whole page):\n\n```js\n// the third argument accepts { skipErrorPage: true } (also readable from the request meta)\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\n```\n\n**Concurrency and fallback**: error-page navigation is **serialised, last one wins**, so a 403 and a 404 arriving together no longer cancel each other. After navigating it re-reads `currentRoute` to verify the arrival (tolerating a redirect that rewrites the path), retries twice, and only then falls back to a full-page `location.replace`, so the user always ends up on the error page. When already on the error page with an `api` parameter the reason is not overwritten — otherwise an auxiliary request fired by the error page itself would replace the real cause.\n\n**Changing colors / wording**:\n\n- All wording lives in i18n entries (`packages/pages/i18n.js`, namespace `pages`).\n- The 403 and 500 pages each declare `--e-color` (accent), `--e-light-color` (light accent) and `--e-border-color` (dashed border) on their root node, so the business can override them with the same variables; the 404 page uses the primary `--s-color` and follows `VITE_APP_THEME_VALUE`.\n- Every root node is `height:100%; overflow:hidden`, and the decorative glows are clipped by `__deco`, so overflow only scrolls inside the card and never creates a page scrollbar.\n\n> The error pages sit under `BasicLayout`, so the layout still fires the `getSystemIcon` and message-count requests. If those are auxiliary endpoints that can fail on their own, give them `skipErrorPage: true`; otherwise a 403 can bounce to the 404 page.\n\n### 2.18 Menu palette (side / top)\n\nThe palette is either **derived from the primary color** (`light`) or a **fixed antd black** (`dark`). On startup `packages/utils/menu-theme.js` emits solid `#rrggbb` values (**no rgba / alpha**), writes them to `:root` as `--s-menu-*` and exposes `window.$menuTheme` (antd `Menu` tokens + `isLightBg`). Switching `VITE_APP_THEME_VALUE` re-derives the whole menu — it is no longer a hard-coded pale blue.\n\n| Part | CSS variable | `light` (orange default) | `light` (blue) | `light` (green) | `dark` |\n| -------------------- | ---------------------------------------------- | ------------------------ | -------------- | --------------- | ----------------------- |\n| Top-level background | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` |\n| Submenu panel | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` |\n| Hovered item | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` |\n| Selected item | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500` (primary) |\n| Normal text | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` |\n| Hover text | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` |\n| Selected text | `--s-menu-text-active`, `--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` |\n| Group title text | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` |\n| `isLightBg` | — | `true` | `true` | `true` | `false` |\n\n> The three `light` columns are **one set of rules** evaluated against different primary colors (`VITE_APP_MENU_BG: \'theme\'`): hue from the primary, saturation capped by `_BG_SATURATION`, lightness from `_BG_LIGHTNESS`, and text colors solved for a contrast ratio >= 4.6. `dark` fixes the antd black background and ignores `VITE_APP_MENU_BG`; only the selected item follows the primary color.\n\n**Following the OS light / dark setting**\n\n`VITE_APP_THEME_FOLLOW_SYSTEM` (default `true`) is handled by `packages/utils/color-scheme.js`: it listens to `prefers-color-scheme`; when the OS goes dark it **immediately** recomputes the menu in `dark`, swaps the neutral tokens to their dark variants and adds `scheme-dark` to `body` — and restores everything when the OS goes light. No reload needed.\n\n| Token | Light | Dark |\n| --------------------------- | ---------- | ------------------------- |\n| `--s-text-color` | `#262626` | `#e8e8e8` |\n| `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` |\n| `--s-bg-color-container` | `#ffffff` | `#1f1f1f` |\n| `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` |\n| `--s-color-warning-bg` | `#fffbe6` | `#2b2413` (darkened) |\n\n> ⚠️ The dark tokens only affect places that **read `var(--s-*)`**. Hard-coded `background: #fff` in business pages will not darken on its own — switch those to `var(--s-bg-color-container)`, or write your own overrides under `body.scheme-dark`.\n> With the switch off (`VITE_APP_THEME_FOLLOW_SYSTEM: false`) the scheme stays as configured by `VITE_APP_MENU_THEME`; businesses that already set `dark` are unaffected.\n\n**The business picks the mode, never the colors**\n\n| Config | Default | Business can override | Notes |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------- | ------------------------------------------------------ |\n| `VITE_APP_MENU_THEME` | `light` | Yes | `light` derived from the primary / `dark` black |\n| `VITE_APP_MENU_BAR` | `left` | Yes | `left` sidebar / `top` top bar (a layout option) |\n| `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | Yes | Whether to follow the OS `prefers-color-scheme` |\n| `VITE_APP_MENU_BG` / `_SUB_BG` / `_HOVER_BG` / `_ACTIVE_BG` / `_TEXT` / `_TEXT_HOVER` / `_TEXT_ACTIVE` / `_GROUP_TITLE` / `_BG_LIGHTNESS` / `_BG_SATURATION` / `_BG_ACTIVE_MIX` | see 4.2 | No | 11 color / tuning keys, always forced back by the base |\n\nLocking mechanism: `packages/config/web-config.js` exports `menuColorKeys` (the 11 keys marked "No" above); `packages/index.js` force-writes the base defaults for those keys onto `env` inside `registerGlobalConfig`, **after `loadRemoteConfig()` has merged**. So menu colors written in the business `.env`, `src/config/web-config.js` or the deployed `config.json` have no effect, and every business project matches the base demo exactly.\n\n> To verify the lock yourself: put `"VITE_APP_MENU_BG": "#ff0000"` into the business `config.json` and reload — the menu still uses the palette derived from the primary color.\n\n**Changing a whole palette** (base-side work, not something a single business can do):\n\n1. Values: edit the `VITE_APP_MENU_*` defaults in `packages/config/web-config.js`;\n2. Derivation: the `light` branch lives in `packages/utils/menu-theme.js` (the `dark` branch is a fixed black system and ignores `VITE_APP_MENU_BG`);\n3. CSS fallback: update the `--s-menu-*` variables in `packages/style/theme.less`;\n4. Rebuild the base → business projects update `sapit-ui-plus` (see 4.1).\n\n> Notes\n>\n> 1. `VITE_APP_MENU_BG: \'dark\'` under `light` is ignored with a warning (a black background belongs to `dark` mode); the pale palette is still used.\n> 2. Per-part color overrides only apply to `light`; `dark` stays pure black, so a "black background + pale blue submenu" mix cannot happen.\n> 3. Do not hard-code menu colors such as `#001529` or `rgba(255,255,255,.1)` in business styles — use `var(--s-menu-*)`.\n> 4. The side menu, the top menu (`VITE_APP_MENU_BAR: \'top\'`), the logo variant and the header text color all read `window.$menuTheme.isLightBg`, not `VITE_APP_MENU_THEME` — OS dark-mode following rewrites it, so always branch on this field.\n> 5. `window.$menuTheme` is a `reactive` object: light / dark switching only mutates its properties (same reference), so `SSideMenu`\'s `computed` reading `window.$menuTheme.token` re-evaluates and the antd `Menu` tokens follow without any manual refresh.\n\n### 2.19 SListCardLayout card list layout\n\nSame skeleton as `SListLayout` (title bar + filter area + pagination) with the table replaced by a card grid. Cards are square with an 8px radius, and the header / body / footer are all slot-driven.\n\n```vue\n<s-list-card-layout title="Card list" :column="5" :load-data="loadData" @card-action="onCardAction">\n <!-- header: falls back to item.title; if that is empty the header is not rendered -->\n <template #cardHeader="{ item }">{{ item.title }}</template>\n\n <!-- default: the body, fully custom (scope has item / index) -->\n <template #default="{ item, index }">\n <div>Name: {{ item.name }}</div>\n </template>\n\n <!-- footer: omitted = default edit / delete buttons; provided = fully replaces them -->\n <template #cardFooter="{ item }">\n <a-button type="link" size="small" @click="edit(item)">Edit</a-button>\n </template>\n</s-list-card-layout>\n```\n\n| Prop | Type | Default | Description |\n| ----------------- | ----------------- | ------------------------------------ | ----------------------------------------------------------- |\n| `title` | String | required | Title bar text |\n| `column` | Number / String | `5` | Cards per row, applied as `repeat(column, 1fr)` |\n| `loadData` | Function | required | `({ pageNo, pageSize }) => { list, total }` |\n| `rowKey` | String / Function | `\'id\'` | Card key; falls back to the index when missing |\n| `buttons` | Array | add / batch remove / import / export | Same shape as `SListLayout` (`name/key/show/type/icon/api`) |\n| `showPagination` | Boolean | `true` | Whether to show pagination |\n| `pSize` | Number / String | `20` | Default page size |\n| `pageSizeOptions` | Array | `[\'10\', \'20\', \'40\', \'80\']` | Page size choices |\n\n| Slot | Scope | Description |\n| ------------------------------------------------------------------------------------ | --------------------- | -------------------------------------------------------------------------------- |\n| `default` | `{ item, index }` | Card body, fully custom |\n| `cardHeader` | `{ item, index }` | Card header; falls back to `item.title`, and renders nothing when both are empty |\n| `cardFooter` | `{ item, index }` | Card footer; omitted = default edit / delete, which emit `cardAction` |\n| `filter` / `filterMore` / `desc` / `tabs` / `tree` / `empty` / `other` / `otherBtns` | same as `SListLayout` | Identical to the ordinary list layout |\n\nEvents: `cardAction(key, item, index)` (`key` is `edit` / `delete`), `btnCallback(key, selections)`, `reset`. The ref exposes `reload(forceFirst)` / `fetchList()`.\n\n**Style conventions** (all component-scoped, class names prefixed with `s-card-` so business `card-*` classes are never hit):\n\n| Class | Description |\n| ------------------- | ----------------------------------------------------------------------------------- |\n| `s-card-grid` | `display:grid` + `gap:12px`, column count from `column` |\n| `s-card-item` | `aspect-ratio: 1/1` square + `border-radius: 8px` |\n| `s-card-header` | Header, single line with ellipsis |\n| `s-card-body` | Body, fills the remaining height, overflow clipped inside |\n| `s-card-footer` | Footer button area, `min-height:36px`, space-between |\n| `s-card-empty` | Empty state, `grid-column: 1 / -1` spans the whole row |\n| `s-card-pagination` | Pagination bar; its height is subtracted from the card area, so no double scrollbar |\n\n**Response normalisation**: rows come from `list` (or `data`), the total from `total` / `pagination.total` / `totalCount`, the current page is written back from `pageNo` / `pageNum` / `pagination.current`. A failed request only logs a `console.warn` and clears the list instead of spinning forever. Changing the page size is handled once in `change`, so one action never fires two requests.\n\n### 2.20 SSuperListLayout advanced list (column settings + advanced filter)\n\nAdds two drawers on top of `SListLayout`: "advanced table" for columns and "advanced search" for conditions. Both use a **draft + confirm** model — the drawer edits a copy, "OK" writes back and refreshes the table, "Close" discards the draft, so a single click never re-renders the table.\n\n```vue\n<s-super-list-layout title="Advanced list" :columns="columns" :load-data="loadData" />\n```\n\n| Prop | Type | Default | Description |\n| ---------------- | ----------------- | ------------------------------------ | ----------------------------------- |\n| `title` | String | required | Title bar text |\n| `columns` | Array | `[]` | Column config, see below |\n| `loadData` | Function | required | Fetcher; receives the filter result |\n| `rowKey` | String / Function | `\'id\'` | Row key |\n| `buttons` | Array | add / batch remove / import / export | Same shape as `SListLayout` |\n| `isSelection` | Boolean | `false` | Show the selection column |\n| `showPagination` | Boolean | `true` | Show pagination |\n| `pSize` | Number / String | `20` | Default page size |\n\nColumn config adds two fields on top of `SListLayout`:\n\n| Field | Description |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `filterConfig` | Only columns with it appear in "advanced search"; without it the column can be displayed but not filtered |\n| `width` | px / plain number → applied as-is and seeded into the width input of the column drawer; `%` → header-only, the pixel input stays empty |\n\n`filterConfig` keys: `filterType` / `filterApi` / `filterData` / `props` / `precision` / `step` / `minValue` / `maxValue` / `length` / `startDate` / `endDate`.\n`filterType`: `INPUT` text, `INT`, `FLOAT`, `DATE`, `DATETIME`, `SINGLE_SELECT`, `MULTIPLE_SELECT`, `GANDER` (gender), `IS` (boolean), `USER`, `OFFICE`. Select-type options come from `filterData` first; only when it is missing does `filterApi` run once and backfill.\n\n**Column settings (`SettingColumns`)**\n\n- Show / hide: ticking edits the draft; only after "OK" are `show === false` columns dropped from the table (they can still be filtered);\n- Freeze / unfreeze: the original freeze side of each column is remembered, so unfreezing then freezing restores the previous `left` / `right`; the action column (`action`) is always `right` and disabled;\n- Width: a px or plain-number `width` is rounded and seeded into the input; a `20%` value is not seeded; clearing the input restores "auto";\n- "OK" writes the columns back and closes the drawer; "Reset" restores the `columns` passed by the caller; "Close" discards the draft.\n\n**Advanced filter (`SettingFilter`)**\n\n- Filterable fields = columns with `filterConfig` (a hidden column can still be filtered);\n- Operators narrow by type: text (`INPUT` or no type) allows `includes` / `excludes` / `equal` / `notequal` / `null` / `notnull`; select, number and date keep only `equal` / `notequal` / `null` / `notnull`;\n- Switching the field resets the operator for the new type (text defaults to "contains", everything else to "equals");\n- `null` / `notnull` need no value; any other row without a value is dropped on submit, so empty conditions never reach the backend.\n\nThe fetch payload becomes:\n\n```js\nloadData({\n pageNo,\n pageSize,\n filterMode, // 1\n filterConditions: [{ dataIndex, equals, value }],\n [dataIndex]: value // single-value equal / includes conditions are also flattened\n})\n```\n\nSingle-value `equal` / `includes` conditions are additionally flattened to a same-named field (`params[dataIndex] = value`), so the backend can read them directly without parsing `filterConditions`.\n\n### 2.21 STab — horizontal tab bar (arrows appear only when the tabs overflow)\n\nA single horizontal row of tabs. Left/right arrows appear **only when the tabs do not fit**, and the bar can be dragged horizontally with the left mouse button.\n\n```vue\n<!-- option 1: pass an array, the component renders the tabs -->\n<s-tab v-model:activeKey="active" :tabs="tabs" @change="onChange" />\n\n<!-- option 2: write <s-tab-item> yourself (for custom tab content) -->\n<s-tab v-model:activeKey="active">\n <s-tab-item value="1">Task config</s-tab-item>\n <s-tab-item value="2"><span>Execution log</span><a-badge :count="3" /></s-tab-item>\n</s-tab>\n\n<!-- no activeKey at all: defaultActiveKey wins, otherwise the first tab is selected -->\n<s-tab :tabs="tabs" default-active-key="2" />\n```\n\n| Item | Description |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `v-model:activeKey` | Current value, `String`/`Number`. Leaving it empty (or `\'\'`) still selects something — see the next row |\n| `defaultActiveKey` | Default value used when `activeKey` is absent or empty; **if both are absent the first tab is selected** |\n| `tabs` | `[{ label, value }]`; map other field names with `tabKey` (default `{ label: \'label\', value: \'value\' }`) |\n| `tabKey` | Field mapping, same convention as `SFormLayout` / `SSkeletonLayout` |\n| `stepRatio` | Screens to scroll per arrow click when already at the first/last tab, default `0.6` |\n| `@change` | `(key, item)`; `item` is `undefined` in slot mode |\n| Slot | Default slot holds `s-tab-item`; once used, `tabs` is ignored |\n| expose | `syncArrow()` / `scrollToActive()` / `scrollRef` |\n\n**Interaction rules**\n\n| Case | Behaviour |\n| ----------------------- | ----------------------------------------------------------------------------------------------------- |\n| Tabs fit | No arrows rendered, tabs fill the row |\n| Tabs overflow | Left/right arrows appear |\n| Click right arrow | Selects the next tab and scrolls it into view; on the last tab it degrades to "scroll one screen" |\n| Arrow disabled | Neither the previous/next tab nor further scrolling is available |\n| Mouse wheel | Vertical wheel scrolls horizontally, the page does not move |\n| Mouse drag | Hold the left button and drag to pan the bar (only when overflowing); a move beyond 5px counts as a drag, so click-to-switch never fires by accident. **Hovering shows no grab cursor — it turns into a grabbing hand only while the button is pressed** |\n| Touch | Not intercepted — native horizontal scrolling and momentum are kept |\n| Keyboard | Left/right arrow keys switch tabs once a tab has focus |\n\n> The bar only renders the tab bar, not the panes. Render the content yourself from `activeKey` — use `v-show` rather than `v-if`, otherwise component instances inside hidden tabs are destroyed (permission pages that must read every tab\'s selection depend on this).\n\nColours are derived from the theme (`--s-color`); override `--s-tab-color` / `--s-tab-active-color` / `--s-tab-disabled-color` on a wrapper to tune them without touching the component.\n\n## 3. Layout and height rules\n\n> This chapter is a **mandatory contract for the base\'s internal layout components**. Business pages only use the layouts and never compute heights themselves; any new layout component must satisfy these rules first.\n\n### 3.1 Heights: prefer CSS flex fill; when dynamic calculation is needed, follow the three constraints\n\n> **Revised 2026-10-28**: the old title "never compute heights via JS subtraction" is **deprecated**. When a business content area needs its own scrollbar, the height **should** be computed dynamically — it just has to follow the constraints below instead of copying magic numbers per page.\n\n**The wrong way** (both `SListLayout` and `SFormLayout` did this early on):\n\n```js\n// ❌ compute the main area height by subtracting offsetHeight values\nthis.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16\n```\n\nWhy it is always wrong: `offsetHeight` reads the **current rendering result**, and that result depends on the `height` you are about to write — a circular dependency. Symptoms:\n\n- with less than a full page of data the pagination floats in the middle, leaving 15–588px of empty space at the bottom;\n- the table/form area overflows its container by 1–N px, adding an extra page scrollbar;\n- changing one magic number (e.g. `tpH = 103`) skews every other page.\n\n**Preferred (zero JS)**: parent `height:100%` + `display:flex; flex-direction:column`, main area `flex:1 1 auto; min-height:0; overflow:auto`, footer bar `flex:0 0 auto`. This covers the vast majority of list and form pages.\n\n**When dynamic JS calculation is needed** (the content area must scroll, or its height follows the window / sibling nodes): **it is allowed and recommended**, but must satisfy three constraints:\n\n1. **One place only**: a single `calcXxxHeight()` per layout, never a magic number per page\n2. **Follow the container**: recalculate with `ResizeObserver` on the parent container, not just `window.resize`\n3. **Never read `$parent.$el`**: it breaks as soon as the parent DOM changes — use a `ref` on your own container\n\n**Still forbidden**: subtracting the `offsetHeight` of the very ancestor whose `height` you are about to write — a circular dependency. Read only values that do not depend on your own height (`window.innerHeight`, the height of a fixed header/footer node).\n\n### 3.2 The table fill chain (what keeps pagination pinned to the bottom)\n\n`STable`\'s body gets its remaining height through flex, and **a single missing level in the chain prevents the fill**:\n\n```less\n.table-content {\n flex: 1;\n display: flex;\n flex-direction: column;\n min-height: 0;\n}\n.tabs-wrap {\n flex: 0 0 auto;\n}\n.table-container {\n flex: 1 1 auto;\n min-height: 0;\n display: flex;\n flex-direction: column;\n}\n.table-wrapper {\n flex: 1 1 auto;\n ...;\n} /* STable\'s root node — omit it and the whole chain breaks */\n.ant-table-wrapper {\n flex: 1 1 auto;\n ...;\n}\n.ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container {\n margin-left: 10px;\n} /* indent the table with margin, not padding */\n.ant-table-header {\n flex: 0 0 auto;\n}\n.ant-table-body {\n flex: 1 1 auto;\n min-height: 0;\n max-height: none !important;\n}\n.ant-table-pagination {\n margin-bottom: 0;\n flex: 0 0 auto;\n} /* one margin off is a 15–16px gap */\n```\n\nKey points:\n\n1. **`.table-wrapper` must not be missed** — it is `STable`\'s root node; measurement shows the body will not fill without it;\n2. the `max-height` written by `scroll.y` must be overridden with `none !important`, otherwise it fights flex;\n3. pagination needs `margin-bottom: 0`, otherwise a permanent margin separates it from the container edge;\n4. indent the table with `:deep(.ant-table-container){margin-left:10px}`, **never** `padding-left` (it distorts the body width calculation).\n\n### 3.3 The `.tools` header bar is uniformly 60px\n\nEvery layout\'s `.tools` (title + button bar) is:\n\n```less\n.tools {\n height: 60px;\n display: flex;\n justify-content: space-between;\n align-items: center;\n padding: 0 16px;\n box-sizing: border-box;\n border-bottom: 1px solid #f0f2f5;\n}\n.list-filter-wrap {\n padding: 10px 16px;\n box-sizing: border-box;\n}\n```\n\n> ⚠️ If the `.tools` height ever changes, the subtrahend in every layout\'s `initTable()` (e.g. `- 76`) must change with it, otherwise every list page in the product skews at once.\n\n### 3.4 Form layout SFormLayout\n\n`.form-layout` fills with the same flex approach; `initStyle()` **only computes the footer width** (the collapses + anchor scenario must dodge the right-hand anchor) and no longer computes heights:\n\n```less\n.form-layout {\n height: 100%;\n overflow: hidden;\n :deep(.ant-spin-nested-loading),\n :deep(.ant-spin-container) {\n /* a-spin\'s wrappers must each fill, otherwise form-layout cannot resolve its height */\n height: 100%;\n display: flex;\n flex-direction: column;\n min-height: 0;\n }\n}\n.tools,\n.step-wrap,\n.tabs-wrap,\n.modal,\n.form-fixed-footer {\n flex: 0 0 auto;\n}\n.form-layout-main {\n flex: 1 1 auto;\n min-height: 0;\n overflow: hidden auto;\n}\n.form-fixed-footer {\n height: 60px;\n}\n```\n\n**Multi-column and full-row items (`full`)**\n\nThe `a-form` inside `SForm` and the content area of `SCollapsesItem` both use `display:grid; grid-template-columns: repeat(column, 1fr)`. With more than one column, give the child a `full` prop to make it span the whole row (implemented as `grid-column: 1 / -1`):\n\n```vue\n<!-- 3-column form, the remark spans a full row -->\n<s-form :column="3" :model="form">\n <s-form-item label="Name" name="name"><a-input /></s-form-item>\n <s-form-item label="Code" name="code"><a-input /></s-form-item>\n <s-form-item label="Remark" name="remark" full><a-textarea /></s-form-item>\n</s-form>\n\n<!-- 2-column collapse group -->\n<s-collapses>\n <s-collapses-item title="Basic info" :column="2">\n <s-form-item label="Name" name="a"><a-input /></s-form-item>\n <s-form-item label="Age" name="b"><a-input /></s-form-item>\n <s-form-item label="Address" name="c" full><a-input /></s-form-item>\n </s-collapses-item>\n</s-collapses>\n```\n\n**Full-row filter item (`full` on `SFilterItem`)**\n\n`SFilterWrap` is a `display:flex; flex-wrap:wrap; gap:10px` container, and each item\'s width comes from `width` (px, default 280). Adding `full` makes that item take the whole row (`100%` / `flex: 1 1 100%`), and the following items wrap onto the next line:\n\n```vue\n<s-filter-wrap>\n <s-filter-item label="Name"><a-input /></s-filter-item>\n <s-filter-item label="Status"><a-select /></s-filter-item>\n <!-- long field, give it its own row -->\n <s-filter-item label="Remark" full><a-textarea /></s-filter-item>\n</s-filter-wrap>\n```\n\n- `full` wins over `width`: when both are set, `width` is ignored.\n- `label` still uses `labelWidth` (default 70); the rest goes to the content area, so `a-select` stretches automatically.\n- Only `SFilterItem` has this prop; `SFilterWrap` needs no column count.\n\n| Prop | Type | Default | Belongs to |\n| ------ | ------- | ------- | -------------------------------------------- |\n| `full` | Boolean | `false` | `SFormItem`, `SCollapsesItem`, `SFilterItem` |\n\n- With a single column `1 / -1` is just the whole row, so switching a form between 1 and N columns needs no code change.\n- `column` is a prop of **`SCollapsesItem`**, not of `SCollapses`; putting it on `<s-collapses column="2">` does nothing.\n- `full` is declared as a prop on `SFormItem` and `SFilterItem`, so it is not forwarded onto the inner `a-form-item` and does not trigger an antd warning.\n- Implementation differs: `SFormItem` / `SCollapsesItem` use `grid-column: 1 / -1`, `SFilterItem` uses `flex-basis: 100%`; usage is identical.\n\n**Filter area shell (`SFilterToolbar`)**\n\nWhen you need only the filter area (no table, no layout shell), use `SFilterToolbar`: the main filter row is always visible, with a "More / Collapse" toggle and a condition reset. It behaves exactly like the `filter` / `filterMore` slots of `SListLayout` / `SListBasicLayout`, but it **already wraps `SFilterWrap`**, so you only write `SFilterItem`.\n\n```vue\n<s-filter-toolbar @reset="reset" @toggle="onFilterToggle">\n <template #filter>\n <s-filter-item label="Keyword" :width="320"><a-input v-model:value="query.keyword" /></s-filter-item>\n <s-filter-item label="Status" :width="220"><a-select v-model:value="query.status" /></s-filter-item>\n </template>\n <!-- optional: without this slot the "More / Collapse" button is not rendered -->\n <template #filterMore>\n <s-filter-item label="Dimension" full><check-box v-model:value="query.scopeIds" /></s-filter-item>\n </template>\n</s-filter-toolbar>\n```\n\n| Slot | Description |\n| ------------ | ---------------------------------------------------------------------- |\n| `filter` | Main filter row, always visible |\n| `filterMore` | Collapsed row, toggled via `v-show`; the button is hidden when omitted |\n\n| Event | Payload | Description |\n| -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `reset` | — | Reset clicked; the parent clears its params and reloads on its own |\n| `toggle` | `isMoreFilter` | Collapse state changed; **no handling needed** when the table area uses `STableToolbar` (it observes its own container), only custom tables must recompute |\n\n- The "More / Collapse" button sits **right next to the filter content (left-aligned)**, while the reset button is pushed to the far right — identical to `.filter-more-btn` / `.reset-wrap` in `SListLayout`.\n- The filter area\'s height changes on collapse. Prefer `STableToolbar` for the table area: it observes its own container with `ResizeObserver` and recomputes the body height automatically, zero config for the parent.\n- `defineExpose`: `isMoreFilter`, `toggleFilter()`, `filterReset()`, `collapse()` (collapse proactively when switching tabs).\n\n**Table area shell (`STableToolbar`)**\n\nThe fixed partner of `SFilterToolbar`: wraps `STable` + pagination + **auto-fitted body height**, so business pages never implement the "content area − filter − header − pagination" math and never produce a page-level scrollbar.\n\n```vue\n<!-- the parent only handles vertical layout; no flex / height needed on the table area -->\n<div class="page">\n <s-filter-toolbar @reset="reset">\n <template #filter>...</template>\n <template #filterMore>...</template>\n </s-filter-toolbar>\n\n <s-table-toolbar ref="tableToolbar" row-key="id" :columns="columns" :data="page" :page-size="10">\n <!-- cell slots follow SListLayout: the column dataIndex is the slot name -->\n <template #ruleName="{ record }">\n <a @click="detail(record)">{{ record.ruleName }}</a>\n </template>\n <template #action="{ record }">\n <a @click="edit(record)" v-action="\'edit\'">Edit</a>\n </template>\n </s-table-toolbar>\n</div>\n```\n\n```less\n.page {\n height: 100%;\n min-height: 0;\n display: flex;\n flex-direction: column;\n}\n```\n\n| Prop | Default | Description |\n| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |\n| `columns` / `data` | — | Same as `STable`; `data` is required |\n| `rowKey` | `\'id\'` | Same as `STable` |\n| `pageSize` | `10` | Same as `STable` |\n| `size` | `\'middle\'` | Same as `STable` |\n| `scrollX` | `\'100%\'` | Horizontal scroll; the body `y` is computed internally and **a parent-supplied `scroll` is ignored** |\n| `tableHeight` | `300` | Initial `scroll.y`; the real height comes from the flex layout, so the parent normally omits it |\n\n- All other attributes are forwarded as-is to `STable`.\n- **Cell slots follow `SListLayout` exactly: the column `dataIndex` is the slot name**, receiving `{ text, record, index, column }`. Columns without a matching slot render their raw value. Non-column slots (`#headerCell`, `#expandedRowRender`, `#emptyText`, ...) are still forwarded.\n- **Do not use `#bodyCell`**: the component already occupies it for column dispatching, so a business-provided `#bodyCell` is ignored and that column renders empty (this is exactly what made an action column "disappear").\n- Height is handled by **pure flex, no arithmetic**: root → `.table-wrapper` → `.ant-table-wrapper` → `.ant-spin-container` → `.ant-table` → `.ant-table-container` are all `flex:1 1 auto;min-height:0`; header/pagination are `flex:0 0 auto`; body is `flex:1 1 auto;max-height:none!important`. The container is `overflow: hidden`, so it **never pushes a page-level scrollbar**.\n- Viewport changes (expanding `filterMore`, switching tabs, window resize, collapsing the sidebar) follow the layout automatically; the parent needs no `onFilterToggle`.\n- `defineExpose`: `resize()` (manual recompute), `refresh(deleteFlag)` (forwards `STable.refresh` and recomputes pagination height), `reload()`, `tableRef`, `scrollY`.\n- The parent root must provide a sized vertical flex container (`height:100%; display:flex; flex-direction:column`); the component takes the remaining space via `flex: 1 1 0%`.\n\n### 3.5 Uniform left tree container height (`.s-side-tree`)\n\nThe `.side` of `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` all use `padding: 10px` (all four sides), so the tree container height must equal "`.side` box height − top/bottom padding (20px)", otherwise you get double scrollbars or a clipped tree.\n\nThe rule lives in the **global** `packages/style/tree.less` under `.s-side-tree` (a unique extra class on `.side`, so a generic name cannot be overridden by business styles); writing a copy inside a business page\'s scoped style is **forbidden**. It covers two tree sources:\n\n- ① a standard `<s-tree>`: the root is `.s-tree-common`, `height:100%`;\n- ② a native `<a-spin><a-tree>`: each level is stretched (`.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder`) and `.ant-tree-list-holder` takes `overflow-y:auto`.\n\n> ⚠️ Branch ② must start from `.s-side-tree` with `>`, **it must not be written as a descendant selector** — `STree` also renders `.ant-tree` internally and a descendant selector would hit branch ①.\n\n### 3.6 STree self-sizing and horizontal ellipsis\n\n`STree`\'s `height` prop default must be `undefined` (**never a hard-coded 300**):\n\n```js\nheight: { type: Number, default: undefined }\n```\n\nReason: antd\'s `Tree` turns `height` into an inline `max-height:300px` on the virtual-list holder, which clips the tree and adds an inner scrollbar.\n\nHorizontal text never wraps, overflows into an ellipsis, and the width follows the parent — these structural rules now live in one place, `packages/style/tree.less`. **Components and business pages must not keep scoped copies**:\n\n```less\n/* packages/style/tree.less (excerpt) */\n.s-tree-common {\n height: 100%;\n width: 100%;\n overflow-x: hidden;\n overflow-y: auto;\n}\n.ant-tree,\n.ant-tree-list,\n.ant-tree-list-holder,\n.ant-tree-list-holder-inner {\n width: 100%;\n min-width: 0;\n}\n.ant-tree-node-content-wrapper {\n min-width: 0;\n overflow: hidden;\n}\n.ant-tree-title,\n.ant-tree-title > .node-title {\n display: block;\n width: 100%;\n overflow: hidden;\n white-space: nowrap;\n text-overflow: ellipsis;\n}\n```\n\n> `.node-title` is a generic class name, so the global rule is scoped to `.ant-tree-title > .node-title` and cannot leak into business code.\n\n### 3.7 Unified tree style file and theme variables (`packages/style/tree.less`)\n\nAll tree styles live in that single file, pulled in by `common.less` via `@import \'./tree.less\'`. The rules previously spread over `STree.vue` (scoped), `SBelowChoosePosition.vue` (scoped copy) and `common.less` (global) have all been folded in.\n\nCovered tree types:\n\n| Type | Selector root | Used by |\n| ----------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------- |\n| Directory / plain tree (`a-directory-tree`, `a-tree`) | `.s-tree-common`, `.ant-tree*` | `STree`, `SBelowChoosePosition`, native `<a-tree>` in business pages |\n| Tree-select dropdown (`a-tree-select`) | `.s-tree-select-popup` | `STreeSelect`, `SDataRangeTreeSelect` (`popup-class-name`) |\n| Sidebar tree container height | `.s-side-tree` | `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` |\n\nEvery colour and size is a `--s-tree-*` variable; the defaults equal the previous hard-coded values, so the visuals are unchanged:\n\n| Variable | Default | Meaning |\n| ---------------------------------- | --------------------------------- | --------------------------------------------------------------------- |\n| `--s-tree-node-height` | `30px` | Node row height (dropdown uses it too) |\n| `--s-tree-node-line-height` | `32px` | Tree title line height |\n| `--s-tree-node-padding-x` | `4px` | Dropdown node horizontal padding |\n| `--s-tree-row-gap` | `4px` | Row gap (leaves a seam in the row background) |\n| `--s-tree-node-radius` | `8px` | Row corner radius (hover + selected, painted on `::before`) |\n| `--s-tree-switcher-color` | `#000000a6` | Expand arrow colour |\n| `--s-tree-hover-bg` | `var(--s-color-bg)` | Row hover background, **follows the theme primary colour** (primary mixed with 90% white; dark mode switches to a primary-based dark tone) |\n| `--s-tree-selected-bg` | `var(--s-color, #1677ff)` | Selected row background, **already follows the theme primary colour** |\n| `--s-tree-selected-text` | `#fff` | Selected row text / arrow colour |\n| `--s-tree-directory-selected-bg` | `#bae7ff` | Directory-tree selected row (antd blue-2) |\n| `--s-tree-directory-selected-text` | `#000000a6` | Directory-tree selected text colour |\n| `--s-tree-icon-color` | `#fff` | Node type icon glyph colour |\n| `--s-tree-icon-bg` | `transparent` | Default node icon background |\n| `--s-tree-icon-bg-g` / `-c` / `-d` | `#a9a9f5` / `#d3b403` / `#f09191` | Node icon G/C/D backgrounds |\n\nOverride per theme instead of touching the components:\n\n```css\n/* pure CSS theme: the base already puts theme-xxx on body (see 2.8) */\nbody.theme-green {\n --s-tree-selected-bg: #00b96b;\n --s-tree-directory-selected-bg: #d9f7e9;\n --s-tree-directory-selected-text: #1f1f1f;\n}\n\n/* global size tweak */\n:root {\n --s-tree-node-height: 32px;\n --s-tree-row-gap: 6px;\n}\n```\n\nTwo caveats:\n\n1. `--s-tree-selected-bg` defaults to `var(--s-color, #1677ff)`, so it follows the theme primary colour automatically; the light variant `--s-tree-directory-selected-bg` still defaults to antd blue-2 — override it explicitly if it should follow.\n2. Variables hold a colour/length only, never a whole declaration (e.g. `--x: background:red`).\n\n### 3.8 The iron rule for diagnosing rendering issues\n\n**Rendering/height problems must be measured on the real page after logging in, using puppeteer to read `offsetHeight`/`offsetLeft`/box metrics — never guess the root cause by reading code statically.**\n\n```js\n// measure: container height, main height, bottom bar offset, document overflow\nconst r = await page.evaluate(() => {\n const q = (s) => document.querySelector(s)\n const box = (s) => {\n const el = q(s)\n if (!el) return null\n const b = el.getBoundingClientRect()\n return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) }\n }\n return {\n container: box(\'.list-layout-main\'),\n tableContent: box(\'.table-content\'),\n pagination: box(\'.ant-table-pagination\'),\n docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight\n }\n})\n```\n\nAcceptance criteria (all must be 0):\n\n| Metric | Pass condition |\n| ------------------------------------------ | ---------------------------------------------------- |\n| `documentOverflowY` | `0` (no page scrollbar) |\n| `pagination.bottom` minus container bottom | `0` (pagination sits exactly at the viewport bottom) |\n| table body overflow beyond the container | `0` |\n\nSpot-check several viewports (1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440); the change is only done when all of them pass.\n\n---\n\n## 4. Build and configuration\n\n### 4.1 Build and release\n\n```bash\nnpm run dev # base local development\nnpm run build # lib build + copy docs/vite-plugins/package.json into dist + git push\nnpm run lint\n```\n\n> The base build **does not drop console** (`$utils`/i18n debug output is controlled at runtime by `VITE_CONFIG_sapit-base-template`); only business builds drop it.\n\nOutput: entry `./packages/index.js`, `vue` external, output `dist/lib`, and the bundle contains the **entry dependency graph** (not the whole project); `package.json` declares `files: ["lib","docs","vite-plugins"]`.\n\n### 4.2 Configuration sources and priority\n\n```text\nbase defaultEnv < business web-config.js < .env.[sapit-base-template] (written into config.json at build time) < deployed config.json (runtime override)\n```\n\n- `web-config.js`: may hold defaults or `import.meta.env.VITE_APP_*`;\n- `.env` / `.env.[sapit-base-template]`: one set per environment (dev/test/uat/prod), written into `config.json` by the business `vite.config.js`;\n- `config.json`: at the site root (or `<base>config.json` for sub-path deploys), fetched and merged by `loadRemoteConfig()` at startup, **editable after deployment without rebuilding**; values in `.env` are strings and the base normalizes `"true"/"false"` to booleans.\n\nCommon switches (the business may override them; checks use `!== false`, so an unset value keeps the base default):\n\n| Option | Default | Description |\n| ----------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `VITE_APP_FOOTER_VISIBLE` | `false` | Whether to show the footer |\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | Whether to show the message bell at the top right (set `false` to hide) |\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | Socket address: **protocol + host + port only, no `/apig/` or any path**; empty or `/` means same origin; the local placeholder is skipped automatically outside a local machine |\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io handshake path, must match the backend (the only place the service path is defined) |\n| `VITE_APP_LANG_ENABLE` | `false` | Whether internationalization is enabled |\n| `VITE_APP_MENU_BAR` | `left` | Menu layout: `left` / `top` (business may override) |\n| `VITE_APP_MENU_THEME` | `light` | Menu palette mode: `light` derived from the primary color / `dark` black (business may override) |\n| `VITE_APP_THEME_FOLLOW_SYSTEM`| `true` | Follow the OS light / dark setting (`prefers-color-scheme`): dark menu + dark neutral tokens, applied at runtime without reload (business may override) |\n| `VITE_APP_MENU_BG` | `theme` | Locked by the base: `light` top-level background; `theme` follows the primary color (default) / fixed `#RRGGBB` |\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Locked by the base: top-level lightness 0-100 |\n| `VITE_APP_MENU_BG_SATURATION` | `66` | Locked by the base: saturation ceiling 0-100 |\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Locked by the base: share of the primary color in the selected background 0-100 |\n| `VITE_APP_MENU_SUB_BG` | empty | Locked by the base: submenu panel background; empty = derived from the primary hue |\n| `VITE_APP_MENU_HOVER_BG` | empty | Locked by the base: hovered item background; empty = derived from the primary hue |\n| `VITE_APP_MENU_ACTIVE_BG` | empty | Locked by the base: selected item background; empty = primary mixed with white (share set by `_BG_ACTIVE_MIX`) |\n| `VITE_APP_MENU_TEXT` | empty | Locked by the base: normal text color; empty = derived from the primary hue |\n| `VITE_APP_MENU_TEXT_HOVER` | empty | Locked by the base: hover text color |\n| `VITE_APP_MENU_TEXT_ACTIVE` | empty | Locked by the base: selected text color |\n| `VITE_APP_MENU_GROUP_TITLE` | empty | Locked by the base: group title color |\n\n> The 11 rows marked "locked by the base" are force-rewritten to the defaults above even when set in the business `.env`, `src/config/web-config.js` or the deployed `config.json`; the business only decides `VITE_APP_MENU_THEME` (which palette) and `VITE_APP_MENU_BAR` (sidebar / top bar). Mechanism and both palettes: [2.18](#docs-218Menupalettesidetop).\n\nThere is **one socket connection for the whole site** (`packages/utils/socket.js`, a singleton — same as the source project registering `VueSocketIO` once). Message badge and QR-code login share the same address and the same `path`, separated only by event names:\n\n| Feature | Emits | Listens to | Module |\n| --- | --- | --- | --- |\n| Top-right message badge | `sendUserId` (userId) | `wsEvent` | `packages/utils/message-socket.js` |\n| QR-code login | `QRCodeKey` (qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` |\n\nBadge logic: on entering the system it calls `message/center/counts` for `totalCount`, and afterwards every `wsEvent` pushed over the socket triggers a refetch. The business registers nothing extra — just point `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` at the gateway.\n\n> Putting a path into `VITE_APP_SOCKET_URL` breaks the handshake: socket.io treats the URL path as the **namespace** (`io(\'http://h:50001/apig/\')` → namespace `/apig/`), the server answers `Invalid namespace`, the WebSocket opens but the socket never connects and no `connect_error` is raised. The base strips the path in `resolveSocketUrl` as a fallback, but the config should still be written correctly.\n\n### 4.3 Starting a business project (`npm start`)\n\nA business project\'s (`sapit-base-template`) `npm start` runs the bundled script `refresh-sapit-base-template.ps1`:\n\n1. remove `node_modules/.vite`, `node_modules/sapit-ui-plus` and the lock files (`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);\n2. `npm install` to pull the latest published `sapit-ui-plus`;\n3. run `npm run dev` automatically.\n\n> Purpose: clear the dependency cache, update business dependencies and start in one step. You can also double-click `refresh-sapit-base-template.cmd`; `-NoStart` only updates without starting.\n> This command is normally needed only when the base project has been updated.\n\n## 5. Business project integration\n\n### 5.1 Install\n\n```json\n{ "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } }\n```\n\n### 5.2 Entry `main.js`\n\n```js\nimport { createApp } from \'vue\'\nimport App from \'./App.vue\'\nimport config from \'./config/web-config\'\nimport appConfig from \'./config/app-config\'\nimport SapitUiPlus from \'sapit-ui-plus\'\nimport \'sapit-ui-plus/lib/css/style.css\'\n\nasync function init() {\n const pages = import.meta.glob(\'@/views/**/*.vue\')\n const app = createApp(App)\n app.use(SapitUiPlus)\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\n app.mount(\'#app\')\n}\ninit()\n```\n\n- `config`: environment configuration (web-config);\n- `appConfig`: build-time configuration (login/home overrides, static routes, language packs) that **never enters config.json**;\n- `pages`: every business page, used by dynamic routing to match `hrefs`.\n\n### 5.3 Login page / home override\n\n`app-config.js`:\n\n```js\nexport default {\n components: {\n login: () => import(\'@/views/login/index.vue\'),\n home: () => import(\'@/views/home/index.vue\')\n }\n}\n```\n\nWhen not configured, the base defaults are used (`pages/login.vue`, `todo.vue`).\n\n### 5.4 Static pages `staticRoutes`\n\n```js\nexport default {\n staticRoutes: [\n {\n path: \'/help\',\n name: \'Help\',\n component: () => import(\'@/views/help/index.vue\'),\n meta: { title: \'Help\' } // hidden: not in the menu; public: no login required\n }\n ]\n}\n```\n\n`layout: false` / `raw: true` skips `BasicLayout`; a business route with the same `path` overrides the built-in one.\n\n### 5.5 Business pages and menus\n\nBackend menu `hrefs` must match the business `views` path (or the component name); any page under `src/views/**` is picked up by dynamic routing. The side menu renders "dynamic menu + `staticRoutes`" and the base\'s constant routes never appear in it.\n\n### 5.6 Internationalization / theme\n\n**Internationalization**\n\n- Dictionary file: `views/<module>/i18n.js`, a flat `{ \'<source text>\': \'English\' }`; the namespace is the first folder after `views`.\n- Pages do not need `useI18n`: `$l(\'<source text>\')` resolves against the page\'s own folder automatically. To force a namespace across folders use `this.useI18n(\'<module>\')` (Options API) or `window.useI18n(\'<module>\')` (`<script setup>`).\n- Aggregation happens once, in the business `src/config/app-config.js`; new files or folders need no code change:\n\n```js\n// src/config/app-config.js\nconst locales = import.meta.glob([\'@/views/**/i18n.js\', \'@/locales/**/i18n.js\'], { eager: true })\nexport default {\n // ...other business config\n locales // main.js spreads { ...config, ...appConfig } into $registerGlobalConfig, merging with the base\n}\n```\n\n- `locales/**` overrides base entries: `src/locales/components/i18n.js` maps to the `components` namespace (shared component-library words); the business wins on duplicates.\n- The language switcher is controlled by `VITE_APP_LANG_ENABLE` in `.env` (`true` shows it); with `false` the dictionaries still work and Chinese is rendered as-is.\n- Prefixed filenames such as `home-i18n.js` / `login-i18n.js` are obsolete: always use `i18n.js`, otherwise the derived namespace is a non-existent `default/home`, `default/login` and the entries never resolve.\n\n**Theme**\n\nOnly change `VITE_APP_THEME_VALUE`; style with `var(--s-*)` or `.s-theme-*`. Menu colors are owned by the base (derived from the primary color, plus OS dark-mode following) — the business only picks `light` or `dark` via `VITE_APP_MENU_THEME` and decides whether to enable `VITE_APP_THEME_FOLLOW_SYSTEM` (see 2.18).\n\n### 5.7 Sub-path deployment (example `/monitor/`)\n\n1. `.env`: `VITE_APP_BASE_URL=/monitor/`;\n2. business `vite.config.js`: `base: getViteEnv(res.mode, \'VITE_APP_BASE_URL\') || \'/\'`;\n3. the base router base, `$push`/`$open`, `redirectLogin` and `parseAppUrl` all read that value and prefix automatically;\n4. nginx:\n\n```nginx\nlocation /monitor/ {\n alias /home/project/tmp/dist/;\n index index.html;\n try_files $uri $uri/ /monitor/index.html;\n}\nlocation = /monitor/config.json {\n alias /home/project/tmp/dist/config.json;\n add_header Cache-Control "no-store";\n}\n```\n\n> `createWebHistory` base, the Vite `base` and every `window.location` jump must all be `/monitor/` (with the trailing slash).\n\n### 5.8 Using components and permissions\n\n```html\n<template>\n <s-list-layout :columns="columns" :loadData="page" title="Example" />\n <s-user-select v-model:value="ids" />\n <a-button v-action="\'add\'">Add</a-button>\n</template>\n```\n\nAfter the backend delivers `permissions` the base writes `permission`, and `v-action:xxx` controls button-level permission. Documentation is available at `<business base>/docs` and `<business base>/components`.\n\n---\n\n### 5.9 Built-in dependencies (ready to use in a business project)\n\nThe `dependencies` of `sapit-ui-plus` are installed into the business `node_modules` together with the base, so the business can **import them without installing anything** (a business `package.json` usually only lists `sapit-ui-plus`).\n\n| Dependency | Version | Purpose |\n| ------------------------------------------------ | ---------------------- | ---------------------------------------------------------------- |\n| `dayjs` | ^1.11.12 | Date formatting (recommended, also used inside `$utils`) |\n| `axios` | ^1.7.3 | Requests (wrapped as `window.$utils.http`, rarely used directly) |\n| `qs` | ^6.13.0 | Parameter serialization (`stringify`) |\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | Safe access / deep clone |\n| `crypto-js` | ^4.2.0 | Encryption / decryption |\n| `js-base64` | ^3.7.2 | Base64 encode/decode |\n| `jsencrypt` | ^3.3.2 | RSA encryption |\n| `moment` | ^2.30.1 | Dates (legacy compatibility; use dayjs for new code) |\n| `html2canvas` | ^1.4.1 | Page screenshots |\n| `nprogress` | ^0.2.0 | Top loading progress bar |\n| `@vueuse/core` | ^11.0.3 | Composition utilities |\n| `vue-cropper` | ^1.1.4 | Image cropping (used by SCopperUpload) |\n| `vuedraggable` | ^4.1.0 | Drag-and-drop sorting |\n| `v-clipboard` | ^3.0.0-next.1 | Copy to clipboard (`v-clipboard` directive) |\n| `vue-ls` | ^4.2.0 | localStorage wrapper (already exposed as `$utils.ls`) |\n| `jodit` | 3.24.7 | Rich text editor (SEditor) |\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | Style compilation |\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | Build plugins (generate config.json etc.) |\n| `@ant-design/icons-vue` | follows ant-design-vue | Icons, **all registered globally as components** |\n\n**Singleton dependencies: the base does not bundle them and the business must install them itself** (`external` in `vite.config.js`), otherwise two module instances appear (routes cannot be injected, pinia mismatches, theme/message context is lost):\n\n| Dependency | Version |\n| ---------------- | ------- |\n| `vue` | ^3.4.29 |\n| `vue-router` | ^4.3.3 |\n| `pinia` | ^2.1.7 |\n| `vue-i18n` | ^9.14.0 |\n| `ant-design-vue` | 4.x |\n\n> Usage: `import dayjs from \'dayjs\'` just works; but **do not** install a second copy of `vue`/`ant-design-vue`/`pinia` with a different major version in the business — the base version wins.\n\n### 5.10 Global injection (no import needed)\n\n| Name | Description |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------- |\n| `$utils` | Utilities: `$utils.http` (requests), `$utils.ls` (local storage), `$utils.env` (config), etc. |\n| `$message` / `$modal` / `$notice` | ant-design-vue message / Modal / notification |\n| `$push` / `$open` | In-app navigation / new window (deployment base prefixed automatically) |\n| `$l` | i18n lookup (`$l(\'<source text>\')`) |\n| `$theme` | Current theme variables; CSS variables such as `--s-color` |\n| `$icons` | All antd icon components |\n| `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / filters / user store / i18n instance |\n| `env` | Same as `$utils.env` |\n| `$getPdf({ el, title })` | Export the page to PDF; `html2canvas` + `jsPDF` are loaded dynamically (see 2.2) |\n| `$staticRoutes` | Static page routes (including business-defined ones) |\n\n---\n\n## 6. Caveats\n\n### 6.1 On the business side\n\n1. <span style="color:#d4380d;font-weight:700">Dependencies are prebuilt artifacts</span>: a base change only takes effect after `npm run build` + push + reinstalling dependencies in the business; the base\'s own dev server reflects changes immediately.\n2. <span style="color:#d4380d;font-weight:700">Lock files pin the old commit</span>: delete `package-lock.json`, `yarn.lock` and `node_modules/.package-lock.json` before updating.\n3. <span style="color:#d46b08;font-weight:700">Sub-path</span>: keep `VITE_APP_BASE_URL` and the Vite `base` identical and trailing-slashed.\n4. <span style="color:#d46b08;font-weight:700">Global component naming</span>: registered by file name (`SForm.vue` → `<SForm>`, not kebab-case); the later one wins on conflict.\n5. <span style="color:#d46b08;font-weight:700">Theme / menu palette / i18n</span>: all defined in the base. The business only picks `VITE_APP_THEME_VALUE`, `VITE_APP_MENU_THEME` (light / dark) and `VITE_APP_THEME_FOLLOW_SYSTEM` (whether to follow the OS scheme), and writes i18n copy; the `VITE_APP_MENU_*` colors and tuning keys are locked by the base and forced back if set (see 2.18).\n6. <span style="color:#d46b08;font-weight:700">Deep imports into base internals are not allowed</span>: the lib output has a single entry, `lib/js/index.js`, and internal modules are rolled into chunks. To expose a capability to the business, attach it as a global property (like `$utils` / `$modal`).\n7. <span style="color:#d4380d;font-weight:700">Feature parity</span>: whatever the reference (old Vue2) project has, we have; do not "helpfully" add what it does not have. Confirm the reference implementation before adding a feature.\n\n### 6.2 Development / build\n\n8. **Never run two `vite build` at the same time**: it reports `Rollup failed to resolve import "sapit-ui-plus"`, which is a false cache-conflict error; rerun serially and it recovers. If it persists serially, check whether `node_modules/sapit-ui-plus` was emptied (npm reinstall often clears it) — restore it with:\n\n ```bash\n # the base dist is exactly the npm package content (the build script copies package.json + docs + vite-plugins into dist)\n cp -r <base>/dist/lib <base>/dist/docs <base>/dist/vite-plugins <base>/dist/package.json <business>/node_modules/sapit-ui-plus/\n cp -r <base>/packages/sso <base>/packages/static <business>/node_modules/sapit-ui-plus/\n ```\n\n9. **`vite build --emptyOutDir false`**: emptying `dist` is blocked by the bulk-delete guard; use this flag when only verifying compilation, and **do not** run the `npm run build` that pushes to the internal git repository just to verify (that is a release action and needs confirmation first).\n10. **Never run two base builds or two business installs concurrently**, to avoid cache contamination.\n11. **`vite build` does not check undefined variables**: referencing a non-existent variable in a template or script still compiles. After a large edit, review added and removed lines with `git diff` and scan for unused imports to catch accidental deletions.\n12. **npm network in China**: `registry.npmjs.org` is basically unreachable and installing `sapit-ui-plus` stalls on the big packages (`ant-design-vue` unpacks to 78MB, `jodit` to 23MB). Use a domestic registry:\n\n ```bash\n npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com\n ```\n\n If `git ls-remote` inside the npm process returns 403 (sandbox/network interception, while a manual `git ls-remote` works), temporarily remove that git dependency, install the rest, then restore it from the local base `dist` as in item 8.\n\n13. **The npm package must contain a root-level `static/`**: the lib build does not rewrite `new URL(\'../../static/...\', import.meta.url)`, and at runtime it resolves from `lib/js/*.js` to `static/` at the package root. Without it every login-page image 404s in the business dev server while the base\'s own dev and production are fine — **extremely misleading**.\n14. **Images in the lib build**: Vite forces every asset inline for `build.lib`, so the output can contain MB-sized base64 data URIs (beyond Chrome\'s URL limit). `closeBundle` in `vite-plugins/sso-plugin` extracts data URIs larger than 100KB into real files under `lib/img/`; always reference source assets through `import`.\n\n### 6.3 Business dictionary / form conventions (hy-monitor)\n\n15. **Always bind dropdown values and copy to the dictionary item\'s `value` (the dictionary value), never its `id` (primary key)**. Fetch several dictionaries at once with `mapByDictTypes(\'a\',\'b\')` and read the result with **underscores converted to camelCase** (`recycle_status` → `res.recycleStatus`); each item is `{label, value, id}`.\n16. **An `a-select` placeholder only shows when the value is `undefined`/`null`**; an empty string `\'\'` counts as an existing value. Initialize every dropdown-like field (search parameters, form fields) to `undefined` and **never `\'\'`** (multi-select binding to `[]` is fine).\n17. **Time range parameters are always millisecond timestamps** (`dayjs(x).valueOf()`), not unix seconds. Basis: the reference `DateRange` onChange emits `date.map(o => dayjs(o).valueOf())` and `useFormValues.fieldMapToTime` passes values through by default (`format=\'\'`).\n18. **Do not add `catch` to API requests** (errors are reported by the global interceptor). Three kinds of catch must stay: ① the form validation chain `.catch(() => {})`; ② `try { await validate() } catch { return }`; ③ tolerant `JSON.parse`.\n19. **API failures navigate to the built-in error pages**: HTTP 403 (301 included) → `/403`, 404 → `/404`, swapped **inside the content-area `router-view`** (sidebar and header stay, the shell is never replaced) with no notification stacked on top. The URL carries `?api=<endpoint>&status=<original status>`, so the page switches to the API wording (403 "no permission for this API", 301 "API endpoint moved", 404 "API not found") and shows the endpoint; without `?api=` it stays on the page wording (no page permission / page not found). **5xx does not navigate** — it keeps the normal notification (`/500` stays available by direct URL). Background polling and other auxiliary requests can pass `{ skipErrorPage: true }` to keep the current page:\n\n ```js\n this.$utils.http.post(\'/api/msg/count\', {}, { skipErrorPage: true })\n ```\n\n---\n\n## 7. Global method quick reference\n\n| Call | Purpose |\n| --------------------------------------------------------- | ------------------------------------------------------- |\n| `$l(\'<source text>\'[, key])` | Internationalization |\n| `$push(path, query)` / `$open(path, query)` | Navigate / open a new window (base prefixed) |\n| `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | Toast / modal / notification / confirm dialog |\n| `this.$utils.ls.get/set/clear` | Local storage |\n| `this.$utils.http(config)` | Send a request (POST by default) |\n| `$filter.dateFormat(v, fmt)` | Date formatting |\n| `v-action:code` | Button-level permission (exact `button_code` match) |\n| `$utils.hasAction(code)` | Button-level permission (functional, supports OR / AND) |\n| `$utils.iconOf(\'info-circle\')` | Legacy antd v1 `type` name → icon component |\n| `$utils.messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution |\n| `$utils.filterSelectOption(iv, opt)` | antd4-ready select filter |\n| `$utils.randomDrawerPlacement()` | Random drawer direction |\n| `$utils.getTableHeight()` | Legacy list table height (window − search − offset) |\n| `var(--s-color)` / `.s-theme-color` | Theme color (CSS variable / utility class) |\n\n---\n\n## 8. Online documentation entry\n\n| Address | Content |\n| ------------------- | ---------------------------------------------------------------- |\n| `<base>/docs` | This guide |\n| `<base>/components` | s components (built-in components: left menu + preview + source) |\n', C = () => {
- var t, n;
- try {
- return ((n = (t = window.$utils) == null ? void 0 : t.ls) == null ? void 0 : n.get("lang")) === "en";
- } catch (r) {
- return !1;
- }
- }, j = {
- name: "DocsPage",
- data() {
- return {
- html: ""
- };
- },
- mounted() {
- this.render();
- },
- methods: {
- render() {
- this.html = S(C() ? L : A);
- }
- }
- }, M = { class: "s-docs-page" }, V = { class: "docs-header" }, $ = { class: "brand" }, U = { class: "nav" }, B = ["innerHTML"];
- function R(t, n, r, e, o, a) {
- const s = k("router-link");
- return x(), _("div", M, [
- u("header", V, [
- u("div", $, [
- n[0] || (n[0] = u("span", { class: "logo" }, "S", -1)),
- m(" " + g(t.$l("sapit-ui 文档")), 1)
- ]),
- u("nav", U, [
- y(s, {
- class: "nav-item active",
- to: "/docs"
- }, {
- default: v(() => [
- m(g(t.$l("说明文档")), 1)
- ]),
- _: 1
- }),
- y(s, {
- class: "nav-item",
- to: "/components"
- }, {
- default: v(() => [
- m(g(t.$l("s组件")), 1)
- ]),
- _: 1
- })
- ])
- ]),
- u("div", {
- class: "docs-body",
- innerHTML: o.html
- }, null, 8, B)
- ]);
- }
- const F = /* @__PURE__ */ E(j, [["render", R], ["__scopeId", "data-v-ca7cb8ac"]]);
- export {
- F as default
- };
|