sapit-ui-base-guide.en.md 85 KB

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

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
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template

1.2 Directory structure (base)

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

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. <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 $utils method).

Registration rule: components/**/*.vue is registered globally by file name (SForm.vue → <SForm>, 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 (<s-table> 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
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)

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 <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

2.3 Layouts

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 / contentHeight are computed from the real header.offsetHeight (not a hard-coded 58) so the layout cannot disagree with the actual rendering and produce overflow scrollbars.

2.4 Routes

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).

2.5 State management (pinia)

packages/store/user.js (useUserStore): state user/menus/permissions/clients/dynamicRouter/menuOpenKeys; actions Info() (fetch and write to localStorage), setDynamicRouter(), setMenuOpenKeys(); persisted in localStorage.

2.6 Utilities ($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)
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 / isDate use Object.prototype.toString ($utils.isNumber('123') is always false). They are not string-format validators; a business-side regex version with the same name must not be replaced by them.

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>.

  • It delegates to $utils.hasAction(actionName) — the directive and the function share one decision path
  • Source priority: permission (singular, the current route's button array written by the router/index.js guard) → falls back to permissions (plural, the full route → buttons map written by store/user.js) + CURRENT_ROUTER_KEY
  • Matching rule: String(button_code) === String(actionName), exact equality (add no longer matches batchAdd)
  • Functional usage: <a-button v-if="$utils.hasAction('add') || $utils.hasAction('edit')">

2.7 Internationalization

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.

2.8 Theme

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:

  1. antd: a-config-provider tokens (colorPrimary/colorLink).
  2. CSS variables: on startup the selected theme is written to :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.
  3. body class: theme-<VITE_APP_THEME_VALUE> (e.g. theme-blue).
  4. Menu palette: on startup the whole menu palette (top-level background / submenu background / hover / selected / text) is derived from the primary color and emitted as solid #rrggbb only — no alpha. It is written to :root as --s-menu-bg, --s-menu-sub-bg, --s-menu-text, --s-menu-text-hover, --s-menu-text-active, --s-menu-hover-bg, --s-menu-active-bg, --s-menu-active-text, plus window.$menuTheme (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 business VITE_APP_THEME_VALUE, and antd plus var(--s-*) follow automatically.

2.9 API / page components / others

  • 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.
  • Static assets live in packages/static/*, styles in packages/style/*; antd icons, axios, dayjs, moment, pinia, vue-router, vue-i18n, jodit, vue-cropper, vuedraggable, html2canvas, crypto-js, jsencrypt, nprogress, qs, lodash.* and more are already bundled.

2.10 Login / SSO

  • Login page /login/index: account + password. Once failures reach the getLoginConfig policy (enabled + codeThreshold), an image captcha appears (/user/verify); verificationCode is submitted as plain text together with verificationCodeId.
  • SSO callback: when the URL carries a code, the guard calls getCode(code) to exchange it for a token → stores it via $utils.ls → strips the code and does a full page reload (same as the reference project).
  • Related configuration: 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_uri supports 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's redirectUri, do not "optimize" the placeholder away.

2.11 SImportModal — generic bulk import modal

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)

⚠️ 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').

<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 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.

<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.

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
<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, 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).

<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 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.

<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 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-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:

  • All wording lives in i18n entries (packages/pages-components/i18n.js, namespace pages-components).
  • 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)

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
  • Values accept #RGB / #RRGGBB / rgb() / rgba() and are normalised to solid #rrggbb — an rgba() input has its alpha dropped, keeping the palette alpha-free.
  • An invalid value logs a [menu] VITE_APP_MENU_XXX ... warning and is ignored; the remaining overrides still apply, so one typo cannot break the whole menu.
  • Overrides are applied before the antd 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

  1. 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 7 VITE_APP_MENU_XXX keys above — overrides always win.
  2. 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, not VITE_APP_MENU_THEME.
  3. Do not hard-code menu colors such as #001529 or rgba(255,255,255,.1) in business styles — use var(--s-menu-*), otherwise a theme switch breaks the look.
  4. .menu-wrap .ant-menu.ant-menu-dark already backs the top-level, submenu, hover and selected nodes with these variables (the parts antd 4.2.6 Menu tokens miss).

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):

// ❌ 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:

.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:

.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:

.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;
}

3.5 Uniform left tree container height (.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:

  • ① a standard <s-tree>: the root is .s-tree-common, height:100%;
  • ② a native <a-spin><a-tree>: each level is stretched (.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder) and .ant-tree-list-holder takes overflow-y:auto.

⚠️ 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):

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-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 <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:

  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.

// 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

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

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.

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

{ "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } }

5.2 Entry main.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:

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).

5.4 Static pages staticRoutes

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

  • i18n: put 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).
  • theme: only change VITE_APP_THEME_VALUE; style with var(--s-*) or .s-theme-*.

5.7 Sub-path deployment (example /monitor/)

  1. .env: VITE_APP_BASE_URL=/monitor/;
  2. business vite.config.js: base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/';
  3. the base router base, $push/$open, redirectLogin and parseAppUrl all read that value and prefix automatically;
  4. nginx:
location /monitor/ {
    alias /home/project/tmp/dist/;
    index index.html;
    try_files $uri $uri/ /monitor/index.html;
}
location = /monitor/config.json {
    alias /home/project/tmp/dist/config.json;
    add_header Cache-Control "no-store";
}

createWebHistory base, the Vite base and every window.location jump must all be /monitor/ (with the trailing slash).

5.8 Using components and permissions

<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.


5.9 Built-in dependencies (ready to use in a business project)

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 of vue/ant-design-vue/pinia with a different major version in the business — the base version wins.

5.10 Global injection (no import needed)

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)

6. Caveats

6.1 On the business side

  1. Dependencies are prebuilt artifacts: a base change only takes effect after npm run build + push + reinstalling dependencies in the business; the base's own dev server reflects changes immediately.
  2. Lock files pin the old commit: delete package-lock.json, yarn.lock and node_modules/.package-lock.json before updating.
  3. Sub-path: keep VITE_APP_BASE_URL and the Vite base identical and trailing-slashed.
  4. Global component naming: registered by file name (SForm.vue → <SForm>, not kebab-case); the later one wins on conflict.
  5. Theme / i18n: defined in the base; the business only selects a theme and writes copy.
  6. Deep imports into base internals are not allowed: the lib output has a single entry, lib/js/index.js, and internal modules are rolled into chunks. To expose a capability to the business, attach it as a global property (like $utils / $modal).
  7. Feature parity: whatever the reference (old Vue2) project has, we have; do not "helpfully" add what it does not have. Confirm the reference implementation before adding a feature.

6.2 Development / build

  1. Never run two vite build at the same time: it reports Rollup failed to resolve import "sapit-ui-plus", which is a false cache-conflict error; rerun serially and it recovers. If it persists serially, check whether node_modules/sapit-ui-plus was emptied (npm reinstall often clears it) — restore it with:
   # 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/
  1. 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).
  2. Never run two base builds or two business installs concurrently, to avoid cache contamination.
  3. 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.
  4. 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.

    1. The npm package must contain a root-level static/: the lib build does not rewrite new URL('../../static/...', import.meta.url), and at runtime it resolves from lib/js/*.js to static/ at the package root. Without it every login-page image 404s in the business dev server while the base's own dev and production are fine — extremely misleading.
    2. Images in the lib build: Vite forces every asset inline for build.lib, so the output can contain MB-sized base64 data URIs (beyond Chrome's URL limit). closeBundle in vite-plugins/sso-plugin extracts data URIs larger than 100KB into real files under lib/img/; always reference source assets through import.

    6.3 Business dictionary / form conventions (hy-monitor)

    1. Always bind dropdown values and copy to the dictionary item's value (the dictionary value), never its id (primary key). Fetch several dictionaries at once with mapByDictTypes('a','b') and read the result with underscores converted to camelCase (recycle_status → res.recycleStatus); each item is {label, value, id}.
    2. An a-select placeholder only shows when the value is undefined/null; an empty string '' counts as an existing value. Initialize every dropdown-like field (search parameters, form fields) to undefined and never '' (multi-select binding to [] is fine).
    3. Time range parameters are always millisecond timestamps (dayjs(x).valueOf()), not unix seconds. Basis: the reference DateRange onChange emits date.map(o => dayjs(o).valueOf()) and useFormValues.fieldMapToTime passes values through by default (format='').
    4. Do not add catch to API requests (errors are reported by the global interceptor). Three kinds of catch must stay: ① the form validation chain .catch(() => {}); ② try { await validate() } catch { return }; ③ tolerant JSON.parse.
    5. API failures navigate to the built-in error pages: HTTP 403 (301 included) → /403, 404 → /404, swapped inside the content-area router-view (sidebar and header stay, the shell is never replaced) with no notification stacked on top. The URL carries ?api=<endpoint>&status=<original status>, so the page switches to the API wording (403 "no permission for this API", 301 "API endpoint moved", 404 "API not found") and shows the endpoint; without ?api= it stays on the page wording (no page permission / page not found). 5xx does not navigate — it keeps the normal notification (/500 stays available by direct URL). Background polling and other auxiliary requests can pass { skipErrorPage: true } to keep the current page:
    this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })
    

7. Global method quick reference

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
var(--s-color) / .s-theme-color Theme color (CSS variable / utility class)

8. Online documentation entry

Address Content
<base>/docs This guide
<base>/components s components (built-in components: left menu + preview + source)