# sapit-ui base framework guide and business usage > Applies to: sapit-ui-framework (the base / sources), sapit-ui-plus (published artifact), sapit-base-template (business sample). > > This document is also the data source of the built-in `/docs` page and the `/components` page. > > Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering. --- ## Contents - [1. Overview](#docs-1Overview) - [2. What the base provides](#docs-2Whatthebaseprovides) - [3. Layout and height rules](#docs-3Layoutandheightrules) - [4. Build and configuration](#docs-4Buildandconfiguration) - [5. Business project integration](#docs-5Businessprojectintegration) - [6. Caveats](#docs-6Caveats) - [7. Global method quick reference](#docs-7Globalmethodquickreference) - [8. Online documentation entry](#docs-8Onlinedocumentationentry) --- ## 1. Overview ### 1.1 The five pieces | Project | Role | Description | | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `sapit-ui-framework` | Base (sources) | Library project holding the built-in components and common dependencies, packed in Vite lib mode | | `sapit-ui-plus` | Published artifact | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) | | `sapit-base-template` | Business consumer | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency | ```text sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template ``` ### 1.2 Directory structure (base) ```text sapit-ui-framework/ ├─ packages/ # published content source (entry dependency graph) │ ├─ index.js # library entry, exports registerGlobalConfig │ ├─ components/ # built-in S* components │ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView │ ├─ router/ # constant routes + dynamic routes + static routes + guards │ ├─ store/ api/ utils/ locales/ static/ style/ │ └─ pages/ # login, workplace, todo, message, 404/403/500, docs pages ├─ docs/ # this document (rendered by the built-in /docs) ├─ vite-plugins/ # docs-viewer plugin ├─ src/ # the base's own debug shell └─ vite.config.js / package.json ``` --- ## 2. What the base provides ### 2.1 Global components `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. ``, ``). | Category | Components | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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` | | Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import, see 2.11) | | 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) | | Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` | | 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` | > 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). > > Registration rule: `components/**/*.vue` is registered globally **by file name** (`SForm.vue` → ``, **not kebab-case**); the later one wins on conflict. > `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` (`` works without any import). > All `@ant-design/icons-vue` icons are registered globally and exposed as `$icons`. > Some helper components are internal only: `ModalHeader` (SModal), `CropperModal` (SCopperUpload), `CustomInput`/`SettingColumns`/`SettingFilter` (SSuperListLayout). ### 2.1.1 Choosing a layout component | Scenario | Use | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Title + buttons + custom content (no table / pagination / form) | `SSkeletonLayout` (see 2.16, ships with a title bar and permission-aware buttons) | | Ordinary list page | `SListLayout` | | Card list | `SListCardLayout` (card grid + three slots, see 2.19) | | List + left tree | `SListTableTreeLayout` (the left tree container class must be `.side.s-side-tree`, see 3.5) | | List with advanced search / table | `SSuperListLayout` (column settings + advanced filter, see 2.20) | | Add / edit / detail (routed) | `SFormLayout` (`#form` slot holds `SForm`; `#footer-callback` receives `save`/`cancel`/`prev`/`next`) | | Form as modal content | `SModal` (do not nest `SFormLayout`) | | Dynamic form driven by backend fields | `SExtendFieldsForm` (`data` + `defaultValue`; the ref exposes `validate/clearValidate/getModel`) | | Data-permission scope selection | `SDataRangeTreeSelect` (`autoSysConfig` manages the system `dataScope` config) | ### 2.2 Global properties / methods Available after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`): | Name | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `$registerGlobalConfig(config, pages)` | Initialization entry (see 5.2) | | `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers | | `env` | Merged environment configuration (= `$utils.env`) | | `$i18n` / `$l(name, key)` | Internationalization (see 2.7). Lives on `globalProperties`: usable **directly in templates** as `$l('xx')`; inside ` ``` | props | Type | Default | Description | | ------------ | --------------- | ---------------- | ------------------------------------------------------------------------------ | | `value` | Boolean | `false` | Visibility (`v-model:value`) | | `title` | String | `Bulk import` | Modal title | | `width` | String / Number | `1000` | Modal width | | `uploadUrl` | String | `''` | Upload endpoint (full gateway address, e.g. `/monitor/DeviceInfo/Uploader`) | | `columns` | Array | `[]` | Preview / result table columns `[{ title, dataIndex, width }]` | | `apis` | Object | `{}` | The four import APIs (see below) | | `typeSelect` | Object | `null` | `{ options, placeholder, loading }`; omit when no business parameter is needed | | `extraKey` | String | `'deviceTypeId'` | Field name used to submit the `typeSelect` value | | events | Description | | -------------- | -------------------------------------------------------- | | `update:value` | Visibility change (`v-model`) | | `reload` | List must be refreshed after a successful import / close | | methods (via ref) | Description | | ----------------- | ---------------------------------- | | `show()` | Open the modal and reset its state | API contract (all return a Promise; the component accepts both `{ code, data }` and plain data): | API | Input | Output | | --------------------- | ------------------------------ | --------------------------------------------------------- | | `templateDownload` | `{ ...extraParams }` | `{ url }` (the component triggers the download) | | `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` | | `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` | | `exportExceptionData` | `{ list, ...extra }` | `{ url }` | | Upload (internal) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }` (later APIs receive fileName) | > ⚠️ `SImportModal` is **three-step** (upload → preview/edit → result/exception export). > 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`), > 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. ### 2.12 SDataRangeTreeSelect — data permission scope tree Selects a data permission scope (organization / campus / unit); internally calls `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`. ```vue ``` Common 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`. events: `update:value`, `change` (both emit an **array of ids**). > ⚠️ The template hard-codes `label-in-value` + `tree-check-strictly`, so antd requires `value` to be an array of `{ label, value }` objects. > 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. ### 2.13 SExtendFieldsForm — dynamic extra field form The backend delivers field configuration (`fillModeConfig` is a JSON string containing `showType` / `config`) and the front end renders from it. ```vue ``` | props | Type | Default | Description | | -------------- | ------ | ------- | -------------------------------------------------------- | | `data` | Array | `[]` | Field definitions (`fieldCode/fieldName/fillModeConfig`) | | `type` | String | `'add'` | `add` / `edit` / `view` (`view` skips validation) | | `defaultValue` | Array | `[]` | Values echoed in edit mode `[ { fieldCode, value } ]` | | `cols` | Number | `2` | Columns per row (non-full-width fields take `100/cols%`) | | `labelWidth` | String | `auto'` | Label width | `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. ### 2.14 SChooseUser — user picker modal (with data permission) Modal 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.** How it differs from `SUserSelect` (the criteria for choosing between them): | Aspect | `SUserSelect` | `SChooseUser` | | --------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Shape | Read-only input plus an integrated modal | Pure modal; visibility controlled by the business | | Data permission | Tree / list APIs carry no data permission | Uses `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`, **filtered by the logged-in user's permission** | | User type | No filter | Built-in staff / student / external filter | | 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** | ```vue ``` | props | Type | Default | Description | | ------------------- | ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------- | | `value` | Boolean | `false` | Modal visibility (`v-model:value`) | | `title` | String | `Select users` | Modal title | | `multiple` | Boolean | `false` | Multiple selection (the selected list appears on the right) | | `searchPlaceholder` | String | `Search by name, employee/student number or phone` | Search box placeholder | | `required` | Boolean | `false` | When nothing is selected, confirming warns and does not close | | `selectedIds` | Array | `[]` | Echoed id array for multi-select (`v-model:selectedIds`); `getBUseryIds` loads objects | | `selectedId` | String | `''` | Echoed id for single select (`v-model:selectedId`); `getUserById` loads the object | | events | Description | | -------------------- | -------------------------------------------------------------------------------- | | `update:value` | Modal closed (both confirm and cancel set it to `false`, no manual close needed) | | `update:selectedIds` | Two-way binding of the selected id array | | `update:selectedId` | Selected id in single-select mode | | `callback` | On confirm emits the selected objects **array**; nothing on close | > ⚠️ 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). ### 2.15 SBelowChoosePosition — position picker modal Modal **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. How 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). ```vue ``` The props match `SChooseUser` (`title` defaults to `Select position`, `searchPlaceholder` to `Search by position name or code`), plus one component-specific prop: | props | Type | Default | Description | | -------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------- | | `rootId` | String | `''` | Left tree root id, which defines the data scope; changing it reloads the tree, `'-1'` is used when omitted | | methods (via ref) | Description | | ---------------------- | ----------------------------- | | `initLeftTreeData(id)` | Manually reload the left tree | | events | Description | | -------------------- | --------------------------------------------------------------------------- | | `update:value` | Set to `false` only on cancel; **confirm does not close the modal** | | `update:selectedIds` | Two-way binding of the selected position ids (echo uses `getPositionByIds`) | | `update:selectedId` | Single-select id (echo uses `getPositionById`) | | `callback` | Confirm emits `{ selectedList }` / `{ selected }`; close emits `false` | > ⚠️ 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. --- ### 2.16 SSkeletonLayout — skeleton layout (title + button group + content) > 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. ```vue
...
``` | props | Type | Default | Description | | -------------------- | ------ | ------- | ------------------------------ | | `title` | String | — | **Required** title bar text | | `buttons` | Array | `[]` | Button config array, see below | | Each `buttons` item: | | Field | Type | Description | | ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | | `key` | String | Unique key, emitted on click; `'add'` makes the button `primary` by default | | `name` | String | Button label (passed through `$l`, so the source Chinese text is fine) | | `icon` | String \| Boolean | String = icon component name (e.g. `'PlusOutlined'`); `true` = look up the built-in iconMap by `key`; omit for no icon | | `action` | String | `v-action` permission code, defaults to `key` (real permission filtering — unauthorised buttons are removed) | | `show` | Boolean | Default `true`; `false` hides via `v-show` (keeps layout, still permission-registered) | | `disabled` | Boolean | Greyed out | | `type` | String | Overrides `a-button`'s `type` | | slots | Description | | ----------- | ----------------------------------------- | | default | Content area (`.skeleton-layout-main`) | | `otherBtns` | Appended to the right of the button group | | `other` | Bottom area | | events | Description | | ------------- | -------------------------------- | | `btnCallback` | Emits the clicked button's `key` | | methods (via ref) | Description | | ----------------- | --------------------------------------------------------------------------- | | — | **None.** Height is allocated by flex; no method call is needed (see below) | Built-in iconMap keys: `add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`. > **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. > > 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. > > 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`). --- ### 2.17 Error pages (301 / 403 / 404 / 500) The 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. | Path | Component | Status sources | Accent | | ------ | --------------- | ------------------------------------------------------------------------------------- | ------------------------------ | | `/403` | `pages/403.vue` | API 403 (no permission), API 301 (address changed), page without permission | Orange `#fa8c16` | | `/404` | `pages/404.vue` | No route matched (catch-all `/:pathMatch(.*)*`), API 404 | Primary color `var(--s-color)` | | `/500` | `pages/500.vue` | Reachable directly only; **API 5xx does not redirect**, it still shows a notification | Red `#f5222d` | **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. **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. **API status mapping** (`packages/utils/request.js`): | HTTP status | Behaviour | Target URL | | ------------------------- | --------------------------------------------------------- | --------------------------------------- | | 301 | Go to the 403 page with the "API address changed" wording | `/403?api=&status=301&from=` | | 403 | Go to the 403 page with the "no API permission" wording | `/403?api=&status=403&from=` | | 404 | Go to the 404 page with the "API does not exist" wording | `/404?api=&status=404&from=` | | Anything else (incl. 5xx) | **No redirect**, a notification is shown as before | — | **Query parameters**: | Parameter | Meaning | | --------- | ---------------------------------------------------------------------------------------------- | | `api` | Failing API address. **Its presence switches to the API wording**; page-level failures omit it | | `status` | Original status code; `301` gets its own "API address changed" wording | | `from` | Source page address (with `VITE_APP_BASE_URL` stripped), rendered as the "source address" line | Wording matrix: | Source | 403 page | 404 page | | ---------------- | ---------------------------- | ------------------ | | Page (no `api`) | Insufficient page permission | Page not found | | API (with `api`) | No API permission | API does not exist | | API 301 | API address changed | — | The 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. **Skipping the redirect** (polling, auxiliary requests — keeps one failing side request from taking over the whole page): ```js // the third argument accepts { skipErrorPage: true } (also readable from the request meta) window.$utils.http.post(url, data, { skipErrorPage: true }) ``` **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. **Changing colors / wording**: - All wording lives in i18n entries (`packages/pages/i18n.js`, namespace `pages`). - 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`. - 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. > 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. ### 2.18 Menu palette (side / top) The 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. | Part | CSS variable | `light` (orange default) | `light` (blue) | `light` (green) | `dark` | | -------------------- | ---------------------------------------------- | ------------------------ | -------------- | --------------- | ----------------------- | | Top-level background | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` | | Submenu panel | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` | | Hovered item | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` | | Selected item | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500` (primary) | | Normal text | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` | | Hover text | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` | | Selected text | `--s-menu-text-active`, `--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` | | Group title text | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` | | `isLightBg` | — | `true` | `true` | `true` | `false` | > 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. **Following the OS light / dark setting** `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. | Token | Light | Dark | | --------------------------- | ---------- | ------------------------- | | `--s-text-color` | `#262626` | `#e8e8e8` | | `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` | | `--s-bg-color-container` | `#ffffff` | `#1f1f1f` | | `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` | | `--s-color-warning-bg` | `#fffbe6` | `#2b2413` (darkened) | > ⚠️ 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`. > 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. **The business picks the mode, never the colors** | Config | Default | Business can override | Notes | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------- | ------------------------------------------------------ | | `VITE_APP_MENU_THEME` | `light` | Yes | `light` derived from the primary / `dark` black | | `VITE_APP_MENU_BAR` | `left` | Yes | `left` sidebar / `top` top bar (a layout option) | | `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | Yes | Whether to follow the OS `prefers-color-scheme` | | `VITE_APP_MENU_BG` / `_SUB_BG` / `_HOVER_BG` / `_ACTIVE_BG` / `_TEXT` / `_TEXT_HOVER` / `_TEXT_ACTIVE` / `_GROUP_TITLE` / `_BG_LIGHTNESS` / `_BG_SATURATION` / `_BG_ACTIVE_MIX` | see 4.2 | No | 11 color / tuning keys, always forced back by the base | Locking 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. > 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. **Changing a whole palette** (base-side work, not something a single business can do): 1. Values: edit the `VITE_APP_MENU_*` defaults in `packages/config/web-config.js`; 2. 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`); 3. CSS fallback: update the `--s-menu-*` variables in `packages/style/theme.less`; 4. Rebuild the base → business projects update `sapit-ui-plus` (see 4.1). > Notes > > 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. > 2. Per-part color overrides only apply to `light`; `dark` stays pure black, so a "black background + pale blue submenu" mix cannot happen. > 3. Do not hard-code menu colors such as `#001529` or `rgba(255,255,255,.1)` in business styles — use `var(--s-menu-*)`. > 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. > 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. ### 2.19 SListCardLayout card list layout Same 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. ```vue ``` | Prop | Type | Default | Description | | ----------------- | ----------------- | ------------------------------------ | ----------------------------------------------------------- | | `title` | String | required | Title bar text | | `column` | Number / String | `5` | Cards per row, applied as `repeat(column, 1fr)` | | `loadData` | Function | required | `({ pageNo, pageSize }) => { list, total }` | | `rowKey` | String / Function | `'id'` | Card key; falls back to the index when missing | | `buttons` | Array | add / batch remove / import / export | Same shape as `SListLayout` (`name/key/show/type/icon/api`) | | `showPagination` | Boolean | `true` | Whether to show pagination | | `pSize` | Number / String | `20` | Default page size | | `pageSizeOptions` | Array | `['10', '20', '40', '80']` | Page size choices | | Slot | Scope | Description | | ------------------------------------------------------------------------------------ | --------------------- | -------------------------------------------------------------------------------- | | `default` | `{ item, index }` | Card body, fully custom | | `cardHeader` | `{ item, index }` | Card header; falls back to `item.title`, and renders nothing when both are empty | | `cardFooter` | `{ item, index }` | Card footer; omitted = default edit / delete, which emit `cardAction` | | `filter` / `filterMore` / `desc` / `tabs` / `tree` / `empty` / `other` / `otherBtns` | same as `SListLayout` | Identical to the ordinary list layout | Events: `cardAction(key, item, index)` (`key` is `edit` / `delete`), `btnCallback(key, selections)`, `reset`. The ref exposes `reload(forceFirst)` / `fetchList()`. **Style conventions** (all component-scoped, class names prefixed with `s-card-` so business `card-*` classes are never hit): | Class | Description | | ------------------- | ----------------------------------------------------------------------------------- | | `s-card-grid` | `display:grid` + `gap:12px`, column count from `column` | | `s-card-item` | `aspect-ratio: 1/1` square + `border-radius: 8px` | | `s-card-header` | Header, single line with ellipsis | | `s-card-body` | Body, fills the remaining height, overflow clipped inside | | `s-card-footer` | Footer button area, `min-height:36px`, space-between | | `s-card-empty` | Empty state, `grid-column: 1 / -1` spans the whole row | | `s-card-pagination` | Pagination bar; its height is subtracted from the card area, so no double scrollbar | **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. ### 2.20 SSuperListLayout advanced list (column settings + advanced filter) Adds 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. ```vue ``` | Prop | Type | Default | Description | | ---------------- | ----------------- | ------------------------------------ | ----------------------------------- | | `title` | String | required | Title bar text | | `columns` | Array | `[]` | Column config, see below | | `loadData` | Function | required | Fetcher; receives the filter result | | `rowKey` | String / Function | `'id'` | Row key | | `buttons` | Array | add / batch remove / import / export | Same shape as `SListLayout` | | `isSelection` | Boolean | `false` | Show the selection column | | `showPagination` | Boolean | `true` | Show pagination | | `pSize` | Number / String | `20` | Default page size | Column config adds two fields on top of `SListLayout`: | Field | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `filterConfig` | Only columns with it appear in "advanced search"; without it the column can be displayed but not filtered | | `width` | px / plain number → applied as-is and seeded into the width input of the column drawer; `%` → header-only, the pixel input stays empty | `filterConfig` keys: `filterType` / `filterApi` / `filterData` / `props` / `precision` / `step` / `minValue` / `maxValue` / `length` / `startDate` / `endDate`. `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. **Column settings (`SettingColumns`)** - Show / hide: ticking edits the draft; only after "OK" are `show === false` columns dropped from the table (they can still be filtered); - 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; - 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"; - "OK" writes the columns back and closes the drawer; "Reset" restores the `columns` passed by the caller; "Close" discards the draft. **Advanced filter (`SettingFilter`)** - Filterable fields = columns with `filterConfig` (a hidden column can still be filtered); - 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`; - Switching the field resets the operator for the new type (text defaults to "contains", everything else to "equals"); - `null` / `notnull` need no value; any other row without a value is dropped on submit, so empty conditions never reach the backend. The fetch payload becomes: ```js loadData({ pageNo, pageSize, filterMode, // 1 filterConditions: [{ dataIndex, equals, value }], [dataIndex]: value // single-value equal / includes conditions are also flattened }) ``` Single-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`. ### 2.21 STab — horizontal tab bar (arrows appear only when the tabs overflow) A 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. ```vue Task config Execution log ``` | Item | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | `v-model:activeKey` | Current value, `String`/`Number`. Leaving it empty (or `''`) still selects something — see the next row | | `defaultActiveKey` | Default value used when `activeKey` is absent or empty; **if both are absent the first tab is selected** | | `tabs` | `[{ label, value }]`; map other field names with `tabKey` (default `{ label: 'label', value: 'value' }`) | | `tabKey` | Field mapping, same convention as `SFormLayout` / `SSkeletonLayout` | | `stepRatio` | Screens to scroll per arrow click when already at the first/last tab, default `0.6` | | `@change` | `(key, item)`; `item` is `undefined` in slot mode | | Slot | Default slot holds `s-tab-item`; once used, `tabs` is ignored | | expose | `syncArrow()` / `scrollToActive()` / `scrollRef` | **Interaction rules** | Case | Behaviour | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | Tabs fit | No arrows rendered, tabs fill the row | | Tabs overflow | Left/right arrows appear | | Click right arrow | Selects the next tab and scrolls it into view; on the last tab it degrades to "scroll one screen" | | Arrow disabled | Neither the previous/next tab nor further scrolling is available | | Mouse wheel | Vertical wheel scrolls horizontally, the page does not move | | 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 | | Touch | Not intercepted — native horizontal scrolling and momentum are kept | | Keyboard | Left/right arrow keys switch tabs once a tab has focus | > 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). Colours 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. ## 3. Layout and height rules > 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. ### 3.1 Heights: prefer CSS flex fill; when dynamic calculation is needed, follow the three constraints > **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. **The wrong way** (both `SListLayout` and `SFormLayout` did this early on): ```js // ❌ compute the main area height by subtracting offsetHeight values this.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16 ``` Why 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: - with less than a full page of data the pagination floats in the middle, leaving 15–588px of empty space at the bottom; - the table/form area overflows its container by 1–N px, adding an extra page scrollbar; - changing one magic number (e.g. `tpH = 103`) skews every other page. **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. **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: 1. **One place only**: a single `calcXxxHeight()` per layout, never a magic number per page 2. **Follow the container**: recalculate with `ResizeObserver` on the parent container, not just `window.resize` 3. **Never read `$parent.$el`**: it breaks as soon as the parent DOM changes — use a `ref` on your own container **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). ### 3.2 The table fill chain (what keeps pagination pinned to the bottom) `STable`'s body gets its remaining height through flex, and **a single missing level in the chain prevents the fill**: ```less .table-content { flex: 1; display: flex; flex-direction: column; min-height: 0; } .tabs-wrap { flex: 0 0 auto; } .table-container { flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; } .table-wrapper { flex: 1 1 auto; ...; } /* STable's root node — omit it and the whole chain breaks */ .ant-table-wrapper { flex: 1 1 auto; ...; } .ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container { margin-left: 10px; } /* indent the table with margin, not padding */ .ant-table-header { flex: 0 0 auto; } .ant-table-body { flex: 1 1 auto; min-height: 0; max-height: none !important; } .ant-table-pagination { margin-bottom: 0; flex: 0 0 auto; } /* one margin off is a 15–16px gap */ ``` Key points: 1. **`.table-wrapper` must not be missed** — it is `STable`'s root node; measurement shows the body will not fill without it; 2. the `max-height` written by `scroll.y` must be overridden with `none !important`, otherwise it fights flex; 3. pagination needs `margin-bottom: 0`, otherwise a permanent margin separates it from the container edge; 4. indent the table with `:deep(.ant-table-container){margin-left:10px}`, **never** `padding-left` (it distorts the body width calculation). ### 3.3 The `.tools` header bar is uniformly 60px Every layout's `.tools` (title + button bar) is: ```less .tools { height: 60px; display: flex; justify-content: space-between; align-items: center; padding: 0 16px; box-sizing: border-box; border-bottom: 1px solid #f0f2f5; } .list-filter-wrap { padding: 10px 16px; box-sizing: border-box; } ``` > ⚠️ 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. ### 3.4 Form layout SFormLayout `.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: ```less .form-layout { height: 100%; overflow: hidden; :deep(.ant-spin-nested-loading), :deep(.ant-spin-container) { /* a-spin's wrappers must each fill, otherwise form-layout cannot resolve its height */ height: 100%; display: flex; flex-direction: column; min-height: 0; } } .tools, .step-wrap, .tabs-wrap, .modal, .form-fixed-footer { flex: 0 0 auto; } .form-layout-main { flex: 1 1 auto; min-height: 0; overflow: hidden auto; } .form-fixed-footer { height: 60px; } ``` **Multi-column and full-row items (`full`)** The `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`): ```vue ``` **Full-row filter item (`full` on `SFilterItem`)** `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: ```vue ``` - `full` wins over `width`: when both are set, `width` is ignored. - `label` still uses `labelWidth` (default 70); the rest goes to the content area, so `a-select` stretches automatically. - Only `SFilterItem` has this prop; `SFilterWrap` needs no column count. | Prop | Type | Default | Belongs to | | ------ | ------- | ------- | -------------------------------------------- | | `full` | Boolean | `false` | `SFormItem`, `SCollapsesItem`, `SFilterItem` | - With a single column `1 / -1` is just the whole row, so switching a form between 1 and N columns needs no code change. - `column` is a prop of **`SCollapsesItem`**, not of `SCollapses`; putting it on `` does nothing. - `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. - Implementation differs: `SFormItem` / `SCollapsesItem` use `grid-column: 1 / -1`, `SFilterItem` uses `flex-basis: 100%`; usage is identical. **Filter area shell (`SFilterToolbar`)** When 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`. ```vue ``` | Slot | Description | | ------------ | ---------------------------------------------------------------------- | | `filter` | Main filter row, always visible | | `filterMore` | Collapsed row, toggled via `v-show`; the button is hidden when omitted | | Event | Payload | Description | | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reset` | — | Reset clicked; the parent clears its params and reloads on its own | | `toggle` | `isMoreFilter` | Collapse state changed; **no handling needed** when the table area uses `STableToolbar` (it observes its own container), only custom tables must recompute | - 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`. - 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. - `defineExpose`: `isMoreFilter`, `toggleFilter()`, `filterReset()`, `collapse()` (collapse proactively when switching tabs). **Table area shell (`STableToolbar`)** The 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. ```vue
``` ```less .page { height: 100%; min-height: 0; display: flex; flex-direction: column; } ``` | Prop | Default | Description | | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | | `columns` / `data` | — | Same as `STable`; `data` is required | | `rowKey` | `'id'` | Same as `STable` | | `pageSize` | `10` | Same as `STable` | | `size` | `'middle'` | Same as `STable` | | `scrollX` | `'100%'` | Horizontal scroll; the body `y` is computed internally and **a parent-supplied `scroll` is ignored** | | `tableHeight` | `300` | Initial `scroll.y`; the real height comes from the flex layout, so the parent normally omits it | - All other attributes are forwarded as-is to `STable`. - **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. - **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"). - 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**. - Viewport changes (expanding `filterMore`, switching tabs, window resize, collapsing the sidebar) follow the layout automatically; the parent needs no `onFilterToggle`. - `defineExpose`: `resize()` (manual recompute), `refresh(deleteFlag)` (forwards `STable.refresh` and recomputes pagination height), `reload()`, `tableRef`, `scrollY`. - 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%`. ### 3.5 Uniform left tree container height (`.s-side-tree`) The `.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. The 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: - ① a standard ``: the root is `.s-tree-common`, `height:100%`; - ② a native ``: 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`. > ⚠️ 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 ①. ### 3.6 STree self-sizing and horizontal ellipsis `STree`'s `height` prop default must be `undefined` (**never a hard-coded 300**): ```js height: { type: Number, default: undefined } ``` Reason: 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. Horizontal 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**: ```less /* packages/style/tree.less (excerpt) */ .s-tree-common { height: 100%; width: 100%; overflow-x: hidden; overflow-y: auto; } .ant-tree, .ant-tree-list, .ant-tree-list-holder, .ant-tree-list-holder-inner { width: 100%; min-width: 0; } .ant-tree-node-content-wrapper { min-width: 0; overflow: hidden; } .ant-tree-title, .ant-tree-title > .node-title { display: block; width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } ``` > `.node-title` is a generic class name, so the global rule is scoped to `.ant-tree-title > .node-title` and cannot leak into business code. ### 3.7 Unified tree style file and theme variables (`packages/style/tree.less`) All 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. Covered tree types: | Type | Selector root | Used by | | ----------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------- | | Directory / plain tree (`a-directory-tree`, `a-tree`) | `.s-tree-common`, `.ant-tree*` | `STree`, `SBelowChoosePosition`, native `` in business pages | | Tree-select dropdown (`a-tree-select`) | `.s-tree-select-popup` | `STreeSelect`, `SDataRangeTreeSelect` (`popup-class-name`) | | Sidebar tree container height | `.s-side-tree` | `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` | Every colour and size is a `--s-tree-*` variable; the defaults equal the previous hard-coded values, so the visuals are unchanged: | Variable | Default | Meaning | | ---------------------------------- | --------------------------------- | --------------------------------------------------------------------- | | `--s-tree-node-height` | `30px` | Node row height (dropdown uses it too) | | `--s-tree-node-line-height` | `32px` | Tree title line height | | `--s-tree-node-padding-x` | `4px` | Dropdown node horizontal padding | | `--s-tree-row-gap` | `4px` | Row gap (leaves a seam in the row background) | | `--s-tree-node-radius` | `8px` | Row corner radius (hover + selected, painted on `::before`) | | `--s-tree-switcher-color` | `#000000a6` | Expand arrow colour | | `--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) | | `--s-tree-selected-bg` | `var(--s-color, #1677ff)` | Selected row background, **already follows the theme primary colour** | | `--s-tree-selected-text` | `#fff` | Selected row text / arrow colour | | `--s-tree-directory-selected-bg` | `#bae7ff` | Directory-tree selected row (antd blue-2) | | `--s-tree-directory-selected-text` | `#000000a6` | Directory-tree selected text colour | | `--s-tree-icon-color` | `#fff` | Node type icon glyph colour | | `--s-tree-icon-bg` | `transparent` | Default node icon background | | `--s-tree-icon-bg-g` / `-c` / `-d` | `#a9a9f5` / `#d3b403` / `#f09191` | Node icon G/C/D backgrounds | Override per theme instead of touching the components: ```css /* pure CSS theme: the base already puts theme-xxx on body (see 2.8) */ body.theme-green { --s-tree-selected-bg: #00b96b; --s-tree-directory-selected-bg: #d9f7e9; --s-tree-directory-selected-text: #1f1f1f; } /* global size tweak */ :root { --s-tree-node-height: 32px; --s-tree-row-gap: 6px; } ``` Two caveats: 1. `--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. 2. Variables hold a colour/length only, never a whole declaration (e.g. `--x: background:red`). ### 3.8 The iron rule for diagnosing rendering issues **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.** ```js // measure: container height, main height, bottom bar offset, document overflow const r = await page.evaluate(() => { const q = (s) => document.querySelector(s) const box = (s) => { const el = q(s) if (!el) return null const b = el.getBoundingClientRect() return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) } } return { container: box('.list-layout-main'), tableContent: box('.table-content'), pagination: box('.ant-table-pagination'), docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight } }) ``` Acceptance criteria (all must be 0): | Metric | Pass condition | | ------------------------------------------ | ---------------------------------------------------- | | `documentOverflowY` | `0` (no page scrollbar) | | `pagination.bottom` minus container bottom | `0` (pagination sits exactly at the viewport bottom) | | table body overflow beyond the container | `0` | Spot-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. --- ## 4. Build and configuration ### 4.1 Build and release ```bash npm run dev # base local development npm run build # lib build + copy docs/vite-plugins/package.json into dist + git push npm run lint ``` > 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. Output: 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"]`. ### 4.2 Configuration sources and priority ```text base defaultEnv < business web-config.js < .env.[sapit-base-template] (written into config.json at build time) < deployed config.json (runtime override) ``` - `web-config.js`: may hold defaults or `import.meta.env.VITE_APP_*`; - `.env` / `.env.[sapit-base-template]`: one set per environment (dev/test/uat/prod), written into `config.json` by the business `vite.config.js`; - `config.json`: at the site root (or `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. Common switches (the business may override them; checks use `!== false`, so an unset value keeps the base default): | Option | Default | Description | | ----------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `VITE_APP_FOOTER_VISIBLE` | `false` | Whether to show the footer | | `VITE_APP_MESSAGE_VISIBLE` | `true` | Whether to show the message bell at the top right (set `false` to hide) | | `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 | | `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io handshake path, must match the backend (the only place the service path is defined) | | `VITE_APP_LANG_ENABLE` | `false` | Whether internationalization is enabled | | `VITE_APP_MENU_BAR` | `left` | Menu layout: `left` / `top` (business may override) | | `VITE_APP_MENU_THEME` | `light` | Menu palette mode: `light` derived from the primary color / `dark` black (business may override) | | `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) | | `VITE_APP_MENU_BG` | `theme` | Locked by the base: `light` top-level background; `theme` follows the primary color (default) / fixed `#RRGGBB` | | `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Locked by the base: top-level lightness 0-100 | | `VITE_APP_MENU_BG_SATURATION` | `66` | Locked by the base: saturation ceiling 0-100 | | `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Locked by the base: share of the primary color in the selected background 0-100 | | `VITE_APP_MENU_SUB_BG` | empty | Locked by the base: submenu panel background; empty = derived from the primary hue | | `VITE_APP_MENU_HOVER_BG` | empty | Locked by the base: hovered item background; empty = derived from the primary hue | | `VITE_APP_MENU_ACTIVE_BG` | empty | Locked by the base: selected item background; empty = primary mixed with white (share set by `_BG_ACTIVE_MIX`) | | `VITE_APP_MENU_TEXT` | empty | Locked by the base: normal text color; empty = derived from the primary hue | | `VITE_APP_MENU_TEXT_HOVER` | empty | Locked by the base: hover text color | | `VITE_APP_MENU_TEXT_ACTIVE` | empty | Locked by the base: selected text color | | `VITE_APP_MENU_GROUP_TITLE` | empty | Locked by the base: group title color | > 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). There 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: | Feature | Emits | Listens to | Module | | --- | --- | --- | --- | | Top-right message badge | `sendUserId` (userId) | `wsEvent` | `packages/utils/message-socket.js` | | QR-code login | `QRCodeKey` (qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` | Badge 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. > 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. ### 4.3 Starting a business project (`npm start`) A business project's (`sapit-base-template`) `npm start` runs the bundled script `refresh-sapit-base-template.ps1`: 1. 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`); 2. `npm install` to pull the latest published `sapit-ui-plus`; 3. run `npm run dev` automatically. > 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. > This command is normally needed only when the base project has been updated. ## 5. Business project integration ### 5.1 Install ```json { "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } } ``` ### 5.2 Entry `main.js` ```js import { createApp } from 'vue' import App from './App.vue' import config from './config/web-config' import appConfig from './config/app-config' import SapitUiPlus from 'sapit-ui-plus' import 'sapit-ui-plus/lib/css/style.css' async function init() { const pages = import.meta.glob('@/views/**/*.vue') const app = createApp(App) app.use(SapitUiPlus) await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages) app.mount('#app') } init() ``` - `config`: environment configuration (web-config); - `appConfig`: build-time configuration (login/home overrides, static routes, language packs) that **never enters config.json**; - `pages`: every business page, used by dynamic routing to match `hrefs`. ### 5.3 Login page / home override `app-config.js`: ```js export default { components: { login: () => import('@/views/login/index.vue'), home: () => import('@/views/home/index.vue') } } ``` When not configured, the base defaults are used (`pages/login.vue`, `todo.vue`). ### 5.4 Static pages `staticRoutes` ```js export default { staticRoutes: [ { path: '/help', name: 'Help', component: () => import('@/views/help/index.vue'), meta: { title: 'Help' } // hidden: not in the menu; public: no login required } ] } ``` `layout: false` / `raw: true` skips `BasicLayout`; a business route with the same `path` overrides the built-in one. ### 5.5 Business pages and menus Backend 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. ### 5.6 Internationalization / theme **Internationalization** - Dictionary file: `views//i18n.js`, a flat `{ '': 'English' }`; the namespace is the first folder after `views`. - Pages do not need `useI18n`: `$l('')` resolves against the page's own folder automatically. To force a namespace across folders use `this.useI18n('')` (Options API) or `window.useI18n('')` (`