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
/docspage and the/componentspage.Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.
| 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 |
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template
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-components/ # 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
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>).
| Category | Components |
|---|---|
| Layout | SSkeletonLayout (skeleton layout: title + button group + content, see 2.16), SListLayout, SListCardLayout, SListTableTreeLayout, SSuperListLayout, SFormLayout, SPanelLayout, SCollapses/SCollapsesItem, SDrawer |
| Overlay | SModal, SModalTemplate, ModalHeader, SIconModal, SImportModal (bulk import, see 2.11) |
| Form / filter | SForm, SFormItem, SExtendFieldsForm/SExtendFieldsFormItem (dynamic extra fields), SFilterWrap, SFilterItem, 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 picker) |
| Upload | SFileUpload, SDraggerUpload, SCopperUpload, CropperModal |
| Display / others | 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$utilsmethod).Registration rule:
components/**/*.vueis registered globally by file name (SForm.vue→<SForm>, not kebab-case); the later one wins on conflict.Table/index.jsxis a.jsxfile thatimport.meta.globcannot match, so the base registers it separately as the globalSTableinpackages/index.js(<s-table>works without any import). All@ant-design/icons-vueicons are registered globally and exposed as$icons. Some helper components are internal only:ModalHeader(SModal),CropperModal(SCopperUpload),CustomInput/SettingColumns/SettingFilter(SSuperListLayout).
| 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 |
| List + left tree | SListTableTreeLayout (the left tree container class must be .side.s-side-tree, see 3.5) |
| List with advanced search / table | SSuperListLayout |
| 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) |
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 <script setup> scripts you must call window.$l('xx') (setup has no this) |
$theme / $staticRoutes / $pinia |
Theme object / static route list / user store instance |
$modal / $message / $notice / $confirm |
antd Modal / message / notification / Modal.confirm (list component button api branch calls this.$confirm) |
$push(path, query) / $open(...) |
In-app navigation / new window (automatically prefixes VITE_APP_BASE_URL) |
$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 |
packages/layouts/index.js: BasicLayout (header + side menu + content), BlankLayout, UserLayout (login), RouteView, PageView.
The height chain of BasicLayout (business layout components must match it, see chapter 3):
.basic-layout-common (100vh)
→ .ant-layout
→ .main-content
→ .container (height = mainHeight = clientHeight - headerHeight)
└─ minus footerHeight(56) when the footer is shown
→ router-view (height = contentHeight, overflow: hidden auto)
→ business layout component (.list-layout / .form-layout, flex:1)
mainHeight/contentHeightare computed from the realheader.offsetHeight(not a hard-coded 58) so the layout cannot disagree with the actual rendering and produce overflow scrollbars.
Constant routes (packages/router/index.js):
| Path | Description |
|---|---|
/login/index |
Login page (base default, can be overridden by the business, see 5.3) |
/workplace/index |
Default home (VITE_APP_DEFAULT_PATH, overridable) |
/workbench/index, /message/index |
Workbench / messages |
/docs, /components |
Built-in docs / component pages (public = no login, hidden = not in the menu) |
/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 |
Redirect rules, query parameters, wording and color overrides for the error pages are documented in 2.17 Error pages.
Static routes (staticRoutes, independent of backend menus): see 5.4. The base ships /docs and /components.
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).
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).
packages/store/user.js (useUserStore): state user/menus/permissions/clients/dynamicRouter/menuOpenKeys; actions Info() (fetch and write to localStorage), setDynamicRouter(), setMenuOpenKeys(); persisted in localStorage.
$utils)| Module | Description |
|---|---|
$utils.env |
Environment configuration object |
$utils.ls |
Local storage (namespace VITE_APP_SYS_SERVER_NAME) |
$utils.http |
axios instance (token/client-id injection, response unwrapping, login timeout, file download) |
parseAppUrl / innerRedirect etc. |
Build in-app URLs with the base (sub-path aware); external http(s) URLs are kept as-is |
messageFormat(str, values) |
{0} / {name} placeholder substitution (confirm dialogs etc.) |
filterSelectOption(iv, opt) |
antd4-ready :filterOption (reads option.label / option.value) |
randomDrawerPlacement() |
Randomly returns left / right / top / bottom (kept from the source project) |
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 |
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')" /> |
hasAction(name) |
Functional button-level permission check, same source as v-action; for v-if OR / AND logic and disabled computation |
| Others | Type checks, dates, arrays, url, dom, debounce/throttle, money, phone validation, etc. |
⚠️ Type checks are not format validation:
$utils.isNumber/isInt/isDateuseObject.prototype.toString($utils.isNumber('123')is alwaysfalse). They are not string-format validators; a business-side regex version with the same name must not be replaced by them.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.
v-action:xxx is the button-level permission directive: <a-button v-action="'add'">Add</a-button>.
$utils.hasAction(actionName) — the directive and the function share one decision pathpermission (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_KEYString(button_code) === String(actionName), exact equality (add no longer matches batchAdd)<a-button v-if="$utils.hasAction('add') || $utils.hasAction('edit')">A 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:
// src/views/user/i18n.js -> namespace user
export default {
'<source text>': 'Cancel'
}
The 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.
Register the namespace inside the page, then call $l('<source text>') directly — never $l('user.<source text>'):
export default {
created() {
this.useI18n('user') // Options API
}
}
// also works inside <script setup>
const { $l } = useI18n('user')
Lookup 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.
| Call site | Usage | Namespace |
|---|---|---|
Template / inside a component, this.$l(...) |
{{ $l('<source text>') }} |
yes, the one registered via useI18n first |
| Plain JS outside components (api / utils) | window.$l('<source text>') |
no, global dictionary only |
In 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.
Definitions 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.
How it takes effect:
a-config-provider tokens (colorPrimary/colorLink).:root as --s-color, --s-light-color, --s-dark-color, --s-border-color, --s-bg-color; the utility classes .s-theme-bg, .s-theme-color, .s-theme-border, .s-theme-border-top, .s-theme-icon-bg are built in.theme-<VITE_APP_THEME_VALUE> (e.g. theme-blue).#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 (carrying the antd Menu tokens and an isLightBg flag).The menu is light by default (the blue theme yields #e8ecf3 for the top level), and all four backgrounds come from one set of parameters, so tuning one changes the whole menu. The full palette, config reference and measured values per theme live in 2.18 Menu palette.
Below 50% lightness the palette flips to "dark background + light text" automatically, with a WCAG contrast ratio solved to stay >= 4.6 — no manual text tuning needed. The side menu, the top menu (
VITE_APP_MENU_BAR: 'top'), the logo variant and the header text color all share this single decision.
.my-box {
color: var(--s-color);
background: var(--s-bg-color);
}
Adding a theme: append a set to the base
VITE_APP_THEME, select it with the businessVITE_APP_THEME_VALUE, and antd plusvar(--s-*)follow automatically.
packages/api: login.js (login, getCode, verify, rsaPublicKey, getLoginConfig, ...), common.js, upload.js, workbench.js.packages/pages-components: login.vue, login-common/LoginForm.vue, workbench.vue, todo.vue, message.vue, 403/404/500.vue, docs.vue, components-doc.vue.packages/static/*, 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./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.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).VITE_APP_CLIENT_ID must equal the client registered in the auth center; the API gateway uses VITE_APP_PORTAL_SERVER_NAME.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:
import ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'
ssoPlugin()
In 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.
⚠️
redirect_urisupports the{code}placeholder; without the placeholder the jump is raw and the code is not exchanged. The platform standard requires?code={code}— keep that in the portal client'sredirectUri, do not "optimize" the placeholder away.
Three-step import: upload file → data preview (rows editable / deletable) → import result (with exception export). File limits: .xls/.xlsx, ≤ 500KB.
<s-import-modal
ref="importModalRef"
:upload-url="IMPORT_UPLOAD_URL"
:columns="importColumns"
:apis="importApis"
:type-select="importTypeSelect"
@reload="handChange"
/>
<script setup>
importModalRef.value.show() // open the modal (it resets its own state)
const importApis = { templateDownload, importPreview, importData, exportExceptionData }
const importColumns = [{ title: 'Device SN', dataIndex: 'sn', width: 150 }]
// optional: a business-parameter dropdown passed with the import; its value is submitted with every API call via extraKey
const importTypeSelect = computed(() => ({
options: [{ label: 'Camera', value: '1' }],
placeholder: 'Select device category'
}))
</script>
| 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) |
⚠️
SImportModalis 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'sviews/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.
Selects a data permission scope (organization / campus / unit); internally calls findOfficeList / getOfficeByIds / getSysConfigByCode('dataScope').
<s-data-range-tree-select v-model:value="ids" :auto-sys-config="true" />
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 requiresvalueto be an array of{ label, value }objects. Therefore echoing back a value must first convert ids withgetOfficeByIds(ids); assigning raw id strings raises anInvalid prop valuewarning and the input shows bare numeric ids.
The backend delivers field configuration (fillModeConfig is a JSON string containing showType / config) and the front end renders from it.
<s-extend-fields-form ref="extRef" :data="fields" :default-value="values" type="edit" :cols="2" />
<script setup>
// the ref exposes three methods
extRef.value.validate() // Promise<boolean>
extRef.value.clearValidate()
extRef.value.getModel() // [{ fieldCode, value }] (object values are already JSON.stringify'd)
</script>
| 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.
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 |
<s-choose-user
v-model:value="userScopeVisible"
v-model:selectedIds="userScopeIds"
:multiple="true"
@callback="userScopeCallback"
/>
<script setup>
// confirm (single or multiple): payload = [{ id, name, cover, userid, company, department }] (a single pick is a one-element array)
// cancel / close: payload = undefined
const userScopeCallback = (payload) => {
if (payload) userNames.value = payload.map((u) => u.name).join(',')
userScopeVisible.value = false
}
</script>
| 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,useridshowsloginName(employee / student number).
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).
<s-below-choose-position
v-model:value="visible"
v-model:selectedIds="positionIds"
multiple
:root-id="campusId"
@callback="onCallback"
/>
<script setup>
// confirm (multiple): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }
// confirm (single): payload = { selected: { id, name, ... } }
// cancel / close: payload = false
const onCallback = (payload) => {
if (payload && payload.selectedList) {
names.value = payload.selectedList.map((i) => i.name).join(',')
}
visible.value = false // the component does not close on confirm, so close it manually
}
</script>
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
callbackpayload shape differs fromSChooseUser(an object{ selectedList }versus an array) and the close-on-confirm behaviour is the opposite, so the two callbacks are not interchangeable.
Added 2026-10-28. A page-level "title bar + action buttons + content area" shell. Same tier as
SListLayout/SFormLayoutbut lighter: no table, no form, no pagination — the content area is entirely up to the slot.
<s-skeleton-layout
:title="$l('Collection jobs')"
:buttons="[
{ key: 'add', name: 'Add', icon: true },
{ key: 'remove', name: 'Delete', disabled: true },
{ key: 'export', name: 'Export', icon: 'DownloadOutlined' }
]"
bg-color="#fff"
@btnCallback="onBtnClick"
>
<div class="my-content">...</div>
<template #otherBtns><a-button>Custom</a-button></template>
<template #other>Footer content</template>
</s-skeleton-layout>
| props | Type | Default | Description |
|---|---|---|---|
title |
String | — | Required title bar text |
buttons |
Array | [] |
Button config array, see below |
bgColor |
String | '' |
Root background colour |
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 barflex:0 0 60px, content areaflex:1 1 auto; min-height:0; overflow:hidden auto, bottom slotflex: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
BasicLayoutalready rendersrouter-viewwith:style="{ height: contentHeight + 'px' }", which falls through to the page root component, so usually nothing extra is needed; a customheight:autowrapper must be given a definite height.The old
initLayoutHeight()method has been removed, andlayoutHeightis no longer exposed (the previous implementation wasparentNode.offsetHeight - 76, computed only once onmounted).
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-components/403.vue |
API 403 (no permission), API 301 (address changed), page without permission | Orange #fa8c16 |
/404 |
pages-components/404.vue |
No route matched (catch-all /:pathMatch(.*)*), API 404 |
Primary color var(--s-color) |
/500 |
pages-components/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=<api>&status=301&from=<page> |
| 403 | Go to the 403 page with the "no API permission" wording | /403?api=<api>&status=403&from=<page> |
| 404 | Go to the 404 page with the "API does not exist" wording | /404?api=<api>&status=404&from=<page> |
| 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):
// 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:
packages/pages-components/i18n.js, namespace pages-components).--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.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 thegetSystemIconand message-count requests. If those are auxiliary endpoints that can fail on their own, give themskipErrorPage: true; otherwise a 403 can bounce to the 404 page.
Menu colors are not hard-coded in stylesheets: on startup packages/utils/menu-theme.js derives the whole palette from the primary color, emits solid #rrggbb only (no rgba / alpha), writes it to :root CSS variables and exposes it as window.$menuTheme. Change the primary color or a parameter and all four backgrounds move together.
| Part | CSS variable | Derivation |
|---|---|---|
| Top-level background | --s-menu-bg |
Primary hue + capped saturation + configured lightness |
| Submenu panel | --s-menu-sub-bg |
Same hue, one step lighter than the top level |
| Hovered item | --s-menu-hover-bg |
Same hue, 6 lightness points darker than the top level |
| Selected item | --s-menu-active-bg |
Primary blended with white, ratio driven by VITE_APP_MENU_BG_ACTIVE_MIX |
| Normal text | --s-menu-text |
Solved against the background for a contrast ratio >= 4.6 |
| Hover / selected text | --s-menu-text-hover, --s-menu-text-active |
Same rule |
Config (defaults in packages/config/web-config.js; overridable from the business .env or the deployed config.json):
| Config | Default | Description |
|---|---|---|
VITE_APP_MENU_BG |
theme |
theme follows the primary color / dark = antd #001529 / #RRGGBB uses that color |
VITE_APP_MENU_BG_LIGHTNESS |
93 |
Top-level lightness 0-100: higher is lighter; below 50 it flips to a dark background with light text |
VITE_APP_MENU_BG_SATURATION |
30 |
Max saturation 0-100: lower is closer to grey, 0 gives pure grey |
VITE_APP_MENU_BG_ACTIVE_MIX |
16 |
Share of the primary color in the selected background, 0-100 |
VITE_APP_MENU_THEME |
dark |
Menu appearance; the text color actually follows the background luminance, not this value alone |
VITE_APP_MENU_BAR |
left |
left sidebar / top top bar; both share the same palette |
Per-part color overrides (for when a derived color is not what you want; leave empty to keep deriving, regardless of what VITE_APP_MENU_BG is set to — valid for theme / dark / custom colors alike):
| Config | Default | Part overridden | CSS variable |
|---|---|---|---|
VITE_APP_MENU_SUB_BG |
empty | Submenu panel background | --s-menu-sub-bg |
VITE_APP_MENU_HOVER_BG |
empty | Hovered item background | --s-menu-hover-bg |
VITE_APP_MENU_ACTIVE_BG |
empty | Selected item background | --s-menu-active-bg |
VITE_APP_MENU_TEXT |
empty | Normal text | --s-menu-text |
VITE_APP_MENU_TEXT_HOVER |
empty | Hover text | --s-menu-text-hover |
VITE_APP_MENU_TEXT_ACTIVE |
empty | Selected text | --s-menu-text-active, --s-menu-active-text |
VITE_APP_MENU_GROUP_TITLE |
empty | Group title text | groupTitle in the returned object |
#RGB / #RRGGBB / rgb() / rgba() and are normalised to solid #rrggbb — an rgba() input has its alpha dropped, keeping the palette alpha-free.[menu] VITE_APP_MENU_XXX ... warning and is ignored; the remaining overrides still apply, so one typo cannot break the whole menu.Menu tokens and the :root CSS variables are produced, so tokens, CSS variables and components all see the final values.Default palettes per theme (lightness 93 / saturation 30 / active mix 16, measured):
| Theme | Top-level | Submenu | Hover | Selected | Text |
|---|---|---|---|---|---|
| blue | #e8ecf3 |
#f5f7fa |
#d4dce8 |
#dae9ff |
#344051 |
| green | #ebf3e8 |
#f7faf5 |
#dbe8d4 |
#e3f6da |
#3d5134 |
| orange | #f3ede8 |
#faf7f5 |
#e8ded4 |
#feedda |
#514334 |
| red | #f3e8e8 |
#faf5f5 |
#e8d4d5 |
#fddcdd |
#513435 |
| purple | #ece8f3 |
#f7f5fa |
#dcd4e8 |
#e8def8 |
#403451 |
| cyan | #e8f3f3 |
#f5fafa |
#d4e8e8 |
#d9f5f5 |
#345151 |
Common tweaks:
// business web-config.js / deployed config.json
VITE_APP_MENU_BG_LIGHTNESS: 97, // 1) lighter (100 is near white)
VITE_APP_MENU_BG_SATURATION: 0, // 2) drop the tint entirely, pure grey
VITE_APP_MENU_BG_ACTIVE_MIX: 30, // 3) a more prominent selected item
VITE_APP_MENU_BG: 'dark', // 4) back to the classic antd #001529
VITE_APP_MENU_BG: '#213045' // 5) pin a custom color, no longer theme-driven
// 6) custom background + a fully custom palette: give the colors you do not want derived
VITE_APP_MENU_BG: '#213045',
VITE_APP_MENU_SUB_BG: '#1b2637',
VITE_APP_MENU_HOVER_BG: '#2a3b52',
VITE_APP_MENU_ACTIVE_BG: '#2b6cd4',
VITE_APP_MENU_TEXT: '#c9d4e2',
VITE_APP_MENU_TEXT_HOVER: '#ffffff',
VITE_APP_MENU_TEXT_ACTIVE: '#ffffff',
VITE_APP_MENU_GROUP_TITLE: '#8fa3bd'
Overriding only one or two parts is fine (for example only
VITE_APP_MENU_TEXT, the rest stays derived); an empty string, a missing key or an invalid value all mean "do not override".Notes
- With
VITE_APP_MENU_BG: '#RRGGBB'the submenu, hover, selected and text colors are still derived from that color, so a new background never leaves unreadable text; if a derived color is not what you want, override it with the 7VITE_APP_MENU_XXXkeys above — overrides always win.- Below 50 lightness the palette flips to dark: text turns light, the logo switches to its light variant and the header text turns white. The decision comes from
window.$menuTheme.isLightBg, notVITE_APP_MENU_THEME.- Do not hard-code menu colors such as
#001529orrgba(255,255,255,.1)in business styles — usevar(--s-menu-*), otherwise a theme switch breaks the look..menu-wrap .ant-menu.ant-menu-darkalready backs the top-level, submenu, hover and selected nodes with these variables (the parts antd 4.2.6 Menu tokens miss).
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.
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):
// ❌ 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:
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:
calcXxxHeight() per layout, never a magic number per pageResizeObserver on the parent container, not just window.resize$parent.$el: it breaks as soon as the parent DOM changes — use a ref on your own containerStill 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).
STable's body gets its remaining height through flex, and a single missing level in the chain prevents the fill:
.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:
.table-wrapper must not be missed — it is STable's root node; measurement shows the body will not fill without it;max-height written by scroll.y must be overridden with none !important, otherwise it fights flex;margin-bottom: 0, otherwise a permanent margin separates it from the container edge;:deep(.ant-table-container){margin-left:10px}, never padding-left (it distorts the body width calculation)..tools header bar is uniformly 60pxEvery layout's .tools (title + button bar) is:
.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
.toolsheight ever changes, the subtrahend in every layout'sinitTable()(e.g.- 76) must change with it, otherwise every list page in the product skews at once.
.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:
.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;
}
.s-side-tree)The .side of SListLayout / SListTableTreeLayout / SListCardLayout all carry padding: 10px 0, so the tree container height must equal ".side box height − top/bottom padding", 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:
<s-tree>: the root is .s-tree-common, height:100%;<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.⚠️ Branch ② must start from
.s-side-treewith>, it must not be written as a descendant selector —STreealso renders.ant-treeinternally and a descendant selector would hit branch ①.
STree's height prop default must be undefined (never a hard-coded 300):
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:
/* 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-titleis a generic class name, so the global rule is scoped to.ant-tree-title > .node-titleand cannot leak into business code.
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 <a-tree> 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 |
rgba(0,0,0,.04) |
Row hover background |
--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:
/* 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:
--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.--x: background:red).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.
// 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.
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 byVITE_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"].
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 <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.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 |
Message push socket address; 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 |
VITE_APP_LANG_ENABLE |
false |
Whether internationalization is enabled |
VITE_APP_MENU_BAR |
left |
Menu layout: left / top |
VITE_APP_MENU_THEME |
dark |
Menu theme: dark / light |
VITE_APP_MENU_BG |
theme |
Menu background: theme follows the primary color / dark = #001529 / #RRGGBB custom |
VITE_APP_MENU_BG_LIGHTNESS |
93 |
Background lightness 0-100: higher is lighter |
VITE_APP_MENU_BG_SATURATION |
30 |
Max saturation of the menu palette 0-100 |
VITE_APP_MENU_BG_ACTIVE_MIX |
16 |
Share of the primary color in the selected background 0-100 |
VITE_APP_MENU_SUB_BG |
empty | Submenu panel background; empty = derived from the primary color (see 2.18) |
VITE_APP_MENU_HOVER_BG |
empty | Hovered item background; empty = derived |
VITE_APP_MENU_ACTIVE_BG |
empty | Selected item background; empty = derived |
VITE_APP_MENU_TEXT |
empty | Normal text color; empty = derived from the background |
VITE_APP_MENU_TEXT_HOVER |
empty | Hover text color; empty = derived from the background |
VITE_APP_MENU_TEXT_ACTIVE |
empty | Selected text color; empty = derived from the background |
VITE_APP_MENU_GROUP_TITLE |
empty | Group title color; empty = derived from the background |
How the top-right message badge counts: on entering the system it calls message/center/counts for totalCount, and afterwards every wsEvent pushed over the socket triggers a refetch. The socket connection is a singleton (packages/utils/message-socket.js) that emits sendUserId with the user id once connected, and the backend pushes per user. The business registers nothing extra — just point VITE_APP_SOCKET_URL / VITE_APP_SOCKET_PATH at the message service.
npm start)A business project's (sapit-base-template) npm start runs the bundled script refresh-sapit-base-template.ps1:
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);npm install to pull the latest published sapit-ui-plus;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;-NoStartonly updates without starting. This command is normally needed only when the base project has been updated.
{ "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } }
main.jsimport { 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.app-config.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-components/login.vue, todo.vue).
staticRoutesexport 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.
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.
views/<module>/i18n.js (flat { '<source text>': 'English' }) and call this.useI18n('<module>') in the page's created hook, then use $l('<source text>') directly. The business's own i18n.js files are aggregated in the business main.js and passed to $registerGlobalConfig({ locales }), which merges them with the base (business wins on duplicates).VITE_APP_THEME_VALUE; style with var(--s-*) or .s-theme-*./monitor/).env: VITE_APP_BASE_URL=/monitor/;vite.config.js: base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/';$push/$open, redirectLogin and parseAppUrl all read that value and prefix automatically;location /monitor/ {
alias /home/project/tmp/dist/;
index index.html;
try_files $uri $uri/ /monitor/index.html;
}
location = /monitor/config.json {
alias /home/project/tmp/dist/config.json;
add_header Cache-Control "no-store";
}
createWebHistorybase, the Vitebaseand everywindow.locationjump must all be/monitor/(with the trailing slash).
<template>
<s-list-layout :columns="columns" :loadData="page" title="Example" />
<s-user-select v-model:value="ids" />
<a-button v-action="'add'">Add</a-button>
</template>
After 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.
The 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).
| Dependency | Version | Purpose |
|---|---|---|
dayjs |
^1.11.12 | Date formatting (recommended, also used inside $utils) |
axios |
^1.7.3 | Requests (wrapped as window.$utils.http, rarely used directly) |
qs |
^6.13.0 | Parameter serialization (stringify) |
lodash.get / lodash.clonedeep |
^4.4.2 / ^4.5.0 | Safe access / deep clone |
crypto-js |
^4.2.0 | Encryption / decryption |
js-base64 |
^3.7.2 | Base64 encode/decode |
jsencrypt |
^3.3.2 | RSA encryption |
moment |
^2.30.1 | Dates (legacy compatibility; use dayjs for new code) |
html2canvas |
^1.4.1 | Page screenshots |
nprogress |
^0.2.0 | Top loading progress bar |
@vueuse/core |
^11.0.3 | Composition utilities |
vue-cropper |
^1.1.4 | Image cropping (used by SCopperUpload) |
vuedraggable |
^4.1.0 | Drag-and-drop sorting |
v-clipboard |
^3.0.0-next.1 | Copy to clipboard (v-clipboard directive) |
vue-ls |
^4.2.0 | localStorage wrapper (already exposed as $utils.ls) |
jodit |
3.24.7 | Rich text editor (SEditor) |
less / less-loader |
^4.2.0 / ^12.2.0 | Style compilation |
vite-plugin-html / vite-plugin-generate-file |
^3.2.2 / ^0.2.0 | Build plugins (generate config.json etc.) |
@ant-design/icons-vue |
follows ant-design-vue | Icons, all registered globally as components |
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):
| Dependency | Version |
|---|---|
vue |
^3.4.29 |
vue-router |
^4.3.3 |
pinia |
^2.1.7 |
vue-i18n |
^9.14.0 |
ant-design-vue |
4.x |
Usage:
import dayjs from 'dayjs'just works; but do not install a second copy ofvue/ant-design-vue/piniawith a different major version in the business — the base version wins.
| Name | Description |
|---|---|
$utils |
Utilities: $utils.http (requests), $utils.ls (local storage), $utils.env (config), etc. |
$message / $modal / $notice |
ant-design-vue message / Modal / notification |
$push / $open |
In-app navigation / new window (deployment base prefixed automatically) |
$l |
i18n lookup ($l('<source text>')) |
$theme |
Current theme variables; CSS variables such as --s-color |
$icons |
All antd icon components |
$socket / $filter / $pinia / $i18n |
websocket / filters / user store / i18n instance |
env |
Same as $utils.env |
$staticRoutes |
Static page routes (including business-defined ones) |
npm run build + push + reinstalling dependencies in the business; the base's own dev server reflects changes immediately.package-lock.json, yarn.lock and node_modules/.package-lock.json before updating.VITE_APP_BASE_URL and the Vite base identical and trailing-slashed.SForm.vue → <SForm>, not kebab-case); the later one wins on conflict.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).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: # the base dist is exactly the npm package content (the build script copies package.json + docs + vite-plugins into dist)
cp -r <base>/dist/lib <base>/dist/docs <base>/dist/vite-plugins <base>/dist/package.json <business>/node_modules/sapit-ui-plus/
cp -r <base>/packages/sso <base>/packages/static <business>/node_modules/sapit-ui-plus/
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).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.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:
npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com
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.
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.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.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}.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).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='').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./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:this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })
| Call | Purpose |
|---|---|
$l('<source text>'[, key]) |
Internationalization |
$push(path, query) / $open(path, query) |
Navigate / open a new window (base prefixed) |
$message.* / $modal.* / $notice.* / $confirm(...) |
Toast / modal / notification / confirm dialog |
this.$utils.ls.get/set/clear |
Local storage |
this.$utils.http(config) |
Send a request (POST by default) |
$filter.dateFormat(v, fmt) |
Date formatting |
v-action:code |
Button-level permission (exact button_code match) |
$utils.hasAction(code) |
Button-level permission (functional, supports OR / AND) |
$utils.iconOf('info-circle') |
Legacy antd v1 type name → icon component |
$utils.messageFormat(str, values) |
{0} / {name} placeholder substitution |
$utils.filterSelectOption(iv, opt) |
antd4-ready select filter |
$utils.randomDrawerPlacement() |
Random drawer direction |
$utils.getTableHeight() |
Legacy list table height (window − search − offset) |
var(--s-color) / .s-theme-color |
Theme color (CSS variable / utility class) |
| Address | Content |
|---|---|
<base>/docs |
This guide |
<base>/components |
s components (built-in components: left menu + preview + source) |