# sapit-ui base framework guide and business usage
> Applies to: sapit-ui-framework (the base / sources), sapit-ui-plus (published artifact), sapit-base-template (business sample).
>
> This document is also the data source of the built-in `/docs` page and the `/components` page.
>
> Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.
---
## Contents
- [1. Overview](#docs-1Overview)
- [2. What the base provides](#docs-2Whatthebaseprovides)
- [3. Layout and height rules](#docs-3Layoutandheightrules)
- [4. Build and configuration](#docs-4Buildandconfiguration)
- [5. Business project integration](#docs-5Businessprojectintegration)
- [6. Caveats](#docs-6Caveats)
- [7. Global method quick reference](#docs-7Globalmethodquickreference)
- [8. Online documentation entry](#docs-8Onlinedocumentationentry)
---
## 1. Overview
### 1.1 The five pieces
| Project | Role | Description |
| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `sapit-ui-framework` | Base (sources) | Library project holding the built-in components and common dependencies, packed in Vite lib mode |
| `sapit-ui-plus` | Published artifact | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) |
| `sapit-base-template` | Business consumer | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency |
```text
sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template
```
### 1.2 Directory structure (base)
```text
sapit-ui-framework/
├─ packages/ # published content source (entry dependency graph)
│ ├─ index.js # library entry, exports registerGlobalConfig
│ ├─ components/ # built-in S* components
│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView
│ ├─ router/ # constant routes + dynamic routes + static routes + guards
│ ├─ store/ api/ utils/ locales/ static/ style/
│ └─ pages-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. ``, ``).
| 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` → ``, **not kebab-case**); the later one wins on conflict.
> `Table/index.jsx` is a `.jsx` file that `import.meta.glob` cannot match, so the base **registers it separately as the global `STable`** in `packages/index.js` (`` works without any import).
> All `@ant-design/icons-vue` icons are registered globally and exposed as `$icons`.
> Some helper components are internal only: `ModalHeader` (SModal), `CropperModal` (SCopperUpload), `CustomInput`/`SettingColumns`/`SettingFilter` (SSuperListLayout).
### 2.1.1 Choosing a layout component
| Scenario | Use |
| --------------------------------------- | -------------------------------------------------------------------------------------- |
| Title + buttons + custom content (no table / pagination / form) | `SSkeletonLayout` (see 2.16, ships with a title bar and permission-aware buttons) |
| Ordinary list page | `SListLayout` |
| Card list | `SListCardLayout` |
| 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 `
```
| props | Type | Default | Description |
| ------------ | --------------- | ---------------- | ------------------------------------------------------------------------ |
| `value` | Boolean | `false` | Visibility (`v-model:value`) |
| `title` | String | `Bulk import` | Modal title |
| `width` | String / Number | `1000` | Modal width |
| `uploadUrl` | String | `''` | Upload endpoint (full gateway address, e.g. `/monitor/DeviceInfo/Uploader`) |
| `columns` | Array | `[]` | Preview / result table columns `[{ title, dataIndex, width }]` |
| `apis` | Object | `{}` | The four import APIs (see below) |
| `typeSelect` | Object | `null` | `{ options, placeholder, loading }`; omit when no business parameter is needed |
| `extraKey` | String | `'deviceTypeId'` | Field name used to submit the `typeSelect` value |
| events | Description |
| -------------- | -------------------------------------------------- |
| `update:value` | Visibility change (`v-model`) |
| `reload` | List must be refreshed after a successful import / close |
| methods (via ref) | Description |
| ----------------- | ------------------------------------ |
| `show()` | Open the modal and reset its state |
API contract (all return a Promise; the component accepts both `{ code, data }` and plain data):
| API | Input | Output |
| --------------------- | ------------------------------ | ---------------------------------------------------- |
| `templateDownload` | `{ ...extraParams }` | `{ url }` (the component triggers the download) |
| `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` |
| `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` |
| `exportExceptionData` | `{ list, ...extra }` | `{ url }` |
| Upload (internal) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }` (later APIs receive fileName) |
> ⚠️ `SImportModal` is **three-step** (upload → preview/edit → result/exception export).
> If a business project has a **single-step** import component that imports as soon as a file is chosen (e.g. hy-monitor's `views/people/components/ImportModal.vue`, `views/basicData/components/ImportModal.vue`),
> the two differ in layout, API, events and the contract with the calling page, so **they must not be swapped for one another** — keep each implementation.
### 2.12 SDataRangeTreeSelect — data permission scope tree
Selects a data permission scope (organization / campus / unit); internally calls `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`.
```vue
```
Common props: `value` (array of ids) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup` (`'1'` organization, `'2'` campus, `'3'` unit; an array is allowed) / `showOnlyOrganization` / `treeSelectData` (pass an array to skip the request) / `isDataScopeFilter` / `autoSysConfig` / `defaultValue`.
events: `update:value`, `change` (both emit an **array of ids**).
> ⚠️ The template hard-codes `label-in-value` + `tree-check-strictly`, so antd requires `value` to be an array of `{ label, value }` objects.
> Therefore **echoing back a value must first convert ids with `getOfficeByIds(ids)`**; assigning raw id strings raises an `Invalid prop value` warning and the input shows bare numeric ids.
### 2.13 SExtendFieldsForm — dynamic extra field form
The backend delivers field configuration (`fillModeConfig` is a JSON string containing `showType` / `config`) and the front end renders from it.
```vue
```
| props | Type | Default | Description |
| -------------- | ------ | ------- | ---------------------------------------------------- |
| `data` | Array | `[]` | Field definitions (`fieldCode/fieldName/fillModeConfig`) |
| `type` | String | `'add'` | `add` / `edit` / `view` (`view` skips validation) |
| `defaultValue` | Array | `[]` | Values echoed in edit mode `[ { fieldCode, value } ]` |
| `cols` | Number | `2` | Columns per row (non-full-width fields take `100/cols%`) |
| `labelWidth` | String | `auto'` | Label width |
`showType` values that automatically take the whole row: `textarea`, `upload`, and `select` with `config.multiple`. Default values are converted per `showType`: `datePicker` → dayjs object, `number` → Number, multi-select `select` → comma-split array.
### 2.14 SChooseUser — user picker modal (with data permission)
Modal user picker: organization tree on the left, user list on the right (avatar / name / employee or student number + unit). The search area contains a **user-type filter** (all / staff / student / external), and it supports single or multiple selection, scroll paging, select-all / invert, and a selected list on the right in multi-select mode. **The modal closes automatically after confirming.**
How it differs from `SUserSelect` (the criteria for choosing between them):
| Aspect | `SUserSelect` | `SChooseUser` |
| ----------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Shape | Read-only input plus an integrated modal | Pure modal; visibility controlled by the business |
| Data permission | Tree / list APIs carry no data permission | Uses `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`, **filtered by the logged-in user's permission** |
| User type | No filter | Built-in staff / student / external filter |
| Value contract | `v-model:value` binds ids directly (string for single, array for multiple) | `v-model:value` controls visibility; `v-model:selectedIds`/`selectedId` bind selected ids; `@callback` emits the **list of selected objects** |
```vue
```
| props | Type | Default | Description |
| ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- |
| `value` | Boolean | `false` | Modal visibility (`v-model:value`) |
| `title` | String | `Select users` | Modal title |
| `multiple` | Boolean | `false` | Multiple selection (the selected list appears on the right) |
| `searchPlaceholder` | String | `Search by name, employee/student number or phone` | Search box placeholder |
| `required` | Boolean | `false` | When nothing is selected, confirming warns and does not close |
| `selectedIds` | Array | `[]` | Echoed id array for multi-select (`v-model:selectedIds`); `getBUseryIds` loads objects |
| `selectedId` | String | `''` | Echoed id for single select (`v-model:selectedId`); `getUserById` loads the object |
| events | Description |
| -------------------- | ------------------------------------------------------------------------ |
| `update:value` | Modal closed (both confirm and cancel set it to `false`, no manual close needed) |
| `update:selectedIds` | Two-way binding of the selected id array |
| `update:selectedId` | Selected id in single-select mode |
| `callback` | On confirm emits the selected objects **array**; nothing on close |
> ⚠️ All APIs live in the base `packages/api/common.js` (`findUsersWithAuth` = `/user/users/authorized`, etc.), so the business passes none; an empty tree/list in a backend-less preview environment is expected. In the list, `userid` shows `loginName` (employee / student number).
### 2.15 SBelowChoosePosition — position picker modal
Modal **position** picker (originally from the business project's `/components/BelowChoosePosition`, now part of the base): the left tree loads the whole tree of "the root node and every unit below it" in one call (`getBelowUnit`, scope determined by `rootId`), while the right list queries positions (`findJobs`); single and multiple selection are supported.
How it differs from the other base selectors: `SOfficeSelect`/`SUserSelect` query organizations/users with a lazily loaded left tree, whereas this component queries **positions** with a fully loaded tree. **It does not close automatically after confirming**; the business must close it in `callback` (same behaviour as the source project).
```vue
```
The props match `SChooseUser` (`title` defaults to `Select position`, `searchPlaceholder` to `Search by position name or code`), plus one component-specific prop:
| props | Type | Default | Description |
| -------- | ------ | ------- | -------------------------------------------------------------------------- |
| `rootId` | String | `''` | Left tree root id, which defines the data scope; changing it reloads the tree, `'-1'` is used when omitted |
| methods (via ref) | Description |
| ---------------------- | ------------------------------ |
| `initLeftTreeData(id)` | Manually reload the left tree |
| events | Description |
| -------------------- | -------------------------------------------------------------------------- |
| `update:value` | Set to `false` only on cancel; **confirm does not close the modal** |
| `update:selectedIds` | Two-way binding of the selected position ids (echo uses `getPositionByIds`) |
| `update:selectedId` | Single-select id (echo uses `getPositionById`) |
| `callback` | Confirm emits `{ selectedList }` / `{ selected }`; close emits `false` |
> ⚠️ The `callback` payload shape differs from `SChooseUser` (an object `{ selectedList }` versus an array) and the close-on-confirm behaviour is the opposite, so the two callbacks are not interchangeable.
---
### 2.16 SSkeletonLayout — skeleton layout (title + button group + content)
> Added 2026-10-28. A page-level "title bar + action buttons + content area" shell. Same tier as `SListLayout` / `SFormLayout` but lighter: **no table, no form, no pagination** — the content area is entirely up to the slot.
```vue