@zy-frontend/business 1.0.146 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +184 -22
- package/dist/index.es.d.ts +1 -1
- package/dist/index.es.js +6300 -81257
- package/package.json +8 -6
package/README.md
CHANGED
|
@@ -1,45 +1,207 @@
|
|
|
1
|
-
# business
|
|
1
|
+
# @zy-frontend/business
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
基于 Vue 3 + TypeScript + Element Plus 的中后台业务组件库，提供检索、列表、图表、布局、评分等开箱即用的配置化组件，以及配套的 Hooks / Utils / Service 层。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 特性
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- **配置化驱动**：通过 JSON 风格的 props 描述表单/列表/图表/布局，少量代码完成复杂业务页面
|
|
8
|
+
- **TypeScript 全量类型**：所有组件、Props、Hooks 均带类型定义
|
|
9
|
+
- **全局上下文注入**：统一管理 `request`、`projectId`、`eventId`、`getDataStructure` 等，组件内部自动消费
|
|
8
10
|
|
|
9
|
-
##
|
|
11
|
+
## 安装
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
```sh
|
|
14
|
+
npm i @zy-frontend/business
|
|
15
|
+
# 或
|
|
16
|
+
pnpm add @zy-frontend/business
|
|
17
|
+
```
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
### Peer 依赖
|
|
14
20
|
|
|
15
|
-
|
|
21
|
+
本库将以下依赖视为 peer，需由消费方提供：
|
|
16
22
|
|
|
17
|
-
|
|
23
|
+
| 依赖 | 说明 |
|
|
24
|
+
| -------------------------------- | ----- |
|
|
25
|
+
| `vue` | ^3.5 |
|
|
26
|
+
| `element-plus` | ^2.13 |
|
|
27
|
+
| `axios` | ^1.7 |
|
|
28
|
+
| `@zy-frontend/element-plus-form` | ^2.0 |
|
|
18
29
|
|
|
19
|
-
|
|
20
|
-
npm install
|
|
21
|
-
```
|
|
30
|
+
> `echarts` / `exceljs` / `lodash-es` / `dayjs` 已 external，使用对应组件（如 `ZYChartList`、`ColumnCustomizableTable` 的导出功能）时需在消费方项目中安装。
|
|
22
31
|
|
|
23
|
-
|
|
32
|
+
## 快速开始
|
|
24
33
|
|
|
25
|
-
|
|
26
|
-
|
|
34
|
+
### 1. 注册组件库（可选）
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
// main.ts
|
|
38
|
+
import { createApp } from 'vue'
|
|
39
|
+
import ElementPlus from 'element-plus'
|
|
40
|
+
import 'element-plus/dist/index.css'
|
|
41
|
+
|
|
42
|
+
import { ZYGlobalProvider } from '@zy-frontend/business'
|
|
43
|
+
import '@zy-frontend/business/dist/style.css'
|
|
44
|
+
|
|
45
|
+
import App from './App.vue'
|
|
46
|
+
|
|
47
|
+
const app = createApp(App)
|
|
48
|
+
app.use(ElementPlus)
|
|
49
|
+
app.use(ZYGlobalProvider) // 仅注册全局组件，不自动注入配置
|
|
50
|
+
app.mount('#app')
|
|
27
51
|
```
|
|
28
52
|
|
|
29
|
-
|
|
53
|
+
> 注意：`app.use(ZYGlobalProvider)` 只是把组件注册到全局，**并不会真正注入全局配置**。你必须用 `<ZYGlobalProvider>` 包裹业务根节点（见下一步）才能完成注入。
|
|
30
54
|
|
|
31
|
-
|
|
32
|
-
|
|
55
|
+
### 2. 在根组件提供全局配置
|
|
56
|
+
|
|
57
|
+
```vue
|
|
58
|
+
<!-- App.vue -->
|
|
59
|
+
<script setup lang="ts">
|
|
60
|
+
import axios from 'axios'
|
|
61
|
+
import { ZYGlobalProvider } from '@zy-frontend/business'
|
|
62
|
+
|
|
63
|
+
const request = axios.create({ baseURL: '/api' })
|
|
64
|
+
|
|
65
|
+
// 静态值
|
|
66
|
+
const projectId = 100
|
|
67
|
+
const eventId = 1
|
|
68
|
+
|
|
69
|
+
// 或动态获取（任选其一）
|
|
70
|
+
// const getProjectId = () => store.state.projectId
|
|
71
|
+
</script>
|
|
72
|
+
|
|
73
|
+
<template>
|
|
74
|
+
<ZYGlobalProvider
|
|
75
|
+
:request="request"
|
|
76
|
+
:project-id="projectId"
|
|
77
|
+
:event-id="eventId"
|
|
78
|
+
:get-data-structure="getDataStructure"
|
|
79
|
+
>
|
|
80
|
+
<RouterView />
|
|
81
|
+
</ZYGlobalProvider>
|
|
82
|
+
</template>
|
|
33
83
|
```
|
|
34
84
|
|
|
35
|
-
###
|
|
85
|
+
### 3. 使用组件
|
|
36
86
|
|
|
37
|
-
```
|
|
38
|
-
|
|
87
|
+
```vue
|
|
88
|
+
<script setup lang="ts">
|
|
89
|
+
import { ZYTable, ZYSearchForm, ZYAdvancedSearch } from '@zy-frontend/business'
|
|
90
|
+
</script>
|
|
91
|
+
|
|
92
|
+
<template>
|
|
93
|
+
<ZYSearchForm :config="formConfig" @search="onSearch" />
|
|
94
|
+
<ZYTable :config="tableConfig" :request-fn="fetchList" />
|
|
95
|
+
</template>
|
|
39
96
|
```
|
|
40
97
|
|
|
41
|
-
|
|
98
|
+
## 组件
|
|
99
|
+
|
|
100
|
+
| 组件 | 说明 |
|
|
101
|
+
| ---------------------------------- | --------------------------------------------------------------------- |
|
|
102
|
+
| `ZYGlobalProvider` | 全局配置提供者，注入 request / projectId / eventId / getDataStructure |
|
|
103
|
+
| `ZYTable` / `ZYSimpleTable` | 配置化列表，支持分页、排序、操作列、自定义渲染 |
|
|
104
|
+
| `ZYSearchForm` | 配置化检索表单，支持展开/收起、字段选择器 |
|
|
105
|
+
| `ZYAdvancedSearch` | 高级检索，支持复杂条件树、字段选择、历史记录 |
|
|
106
|
+
| `ZYColumnCustomizableTable` | 自定义列表表格，支持列配置、导出模板 |
|
|
107
|
+
| `ZYChartList` / `ZYChart` | 配置化图表，基于 ECharts |
|
|
108
|
+
| `ZYLayout` / `ZYLayoutItem` | 配置化网格布局 |
|
|
109
|
+
| `ZYAnchorTabs` / `ZYAnchorTabItem` | 锚点定位垂直标签页 |
|
|
110
|
+
| `ZYSplitter` / `ZYSplitterPanel` | 拖拽分屏面板 |
|
|
111
|
+
| `ZYSortableFieldPicker` | 字段选择器，支持拖拽排序 |
|
|
112
|
+
| `ZYScoreTable` / `ZYScoreDialog` | 评分组件（GCS / ISS / AIS 等量表） |
|
|
113
|
+
| `ZYOverflowTooltip` | 文本溢出时自动 Tooltip 提示 |
|
|
114
|
+
| `ZYIconButton` | 带延迟显示 Tooltip 的图标按钮 |
|
|
115
|
+
|
|
116
|
+
## Hooks
|
|
117
|
+
|
|
118
|
+
### 全局上下文
|
|
119
|
+
|
|
120
|
+
| Hook | 说明 |
|
|
121
|
+
| -------------------- | ---------------------------------------------------------------- |
|
|
122
|
+
| `useGlobalConfig()` | 读取 `{ projectId, eventId }`（自动从 provide 链或全局单例获取） |
|
|
123
|
+
| `useGlobalRequest()` | 读取注入的 axios 实例 |
|
|
124
|
+
| `useGlobalStorage()` | 获取全局共享存储的 `dataStructure` / `searchConfig` 响应式引用 |
|
|
125
|
+
|
|
126
|
+
### 业务存储
|
|
127
|
+
|
|
128
|
+
| Hook | 说明 |
|
|
129
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
130
|
+
| `useDataStructureStore()` | 提供 `getDataStructure(params, options)`，含缓存 |
|
|
131
|
+
| `useSearchConfigStore()` | 提供 `getSearchConfigData` / `updateSearches` / `deleteSearches` / `clearSearchConfigCache`，内部串行异步队列 |
|
|
132
|
+
| `useCustomizedExport()` | 提供 `getExportTemplateList` |
|
|
133
|
+
|
|
134
|
+
### 工具 Hooks
|
|
135
|
+
|
|
136
|
+
| Hook | 说明 |
|
|
137
|
+
| ----------------------------------------------- | ------------------------------------------------ |
|
|
138
|
+
| `useElementSize(target)` | 监听元素尺寸变化，返回响应式 `{ width, height }` |
|
|
139
|
+
| `useAsyncQueue(fn)` / `useSeniorAsyncQueue(fn)` | 串行异步任务队列 |
|
|
140
|
+
|
|
141
|
+
## 工具函数（Utils）
|
|
142
|
+
|
|
143
|
+
| 函数 | 说明 |
|
|
144
|
+
| ------------------------------------------- | --------------------------------------------- |
|
|
145
|
+
| `withInstall(comp, extra?)` | 为 SFC 添加 `install` 方法 |
|
|
146
|
+
| `transferMapToOptions(map, isValueNumber?)` | `{ a: 'A' }` → `[{ value: 'a', label: 'A' }]` |
|
|
147
|
+
| `mergeRecursive(obj1, obj2)` | 递归合并对象（双数组拼接） |
|
|
148
|
+
| `encodeSearchKey(key)` | URL 特殊字符转义（`% ? # & =`） |
|
|
149
|
+
| `transferNumberToPx(value)` | `10` → `'10px'`，字符串原样返回 |
|
|
150
|
+
| `getTimestampStr()` | 当前时间戳字符串 |
|
|
151
|
+
|
|
152
|
+
## Service 层
|
|
153
|
+
|
|
154
|
+
内置一组与后端约定的接口封装，自动注入 `projectId` / `eventId`：
|
|
155
|
+
|
|
156
|
+
| 函数 | 用途 |
|
|
157
|
+
| ----------------------------------------------------------------------- | -------------------------- |
|
|
158
|
+
| `getSearchableFields` | 获取可检索字段（数据结构） |
|
|
159
|
+
| `getSearchConfig` | 获取用户检索表单配置 |
|
|
160
|
+
| `updateSearches` / `deleteSearches` | 增删用户自定义检索条件 |
|
|
161
|
+
| `updateColumns` / `deleteColumns` | 增删用户自定义列 |
|
|
162
|
+
| `getExportTemplateList` / `saveExportTemplate` / `deleteExportTemplate` | 导出模板管理 |
|
|
163
|
+
| `getQueryTemplateList` / `saveQueryTemplate` / `deleteQueryTemplate` | 高级检索模板管理 |
|
|
164
|
+
| `getFieldOptions` | 获取字段候选项（带分页） |
|
|
165
|
+
|
|
166
|
+
接口地址通过 `api` 常量统一管理，可按需覆盖。
|
|
167
|
+
|
|
168
|
+
## 全局配置 Props
|
|
169
|
+
|
|
170
|
+
`ZYGlobalProvider` / `provideGlobalConfig` 接收以下 props：
|
|
171
|
+
|
|
172
|
+
| Prop | 类型 | 说明 |
|
|
173
|
+
| ------------------ | ----------------------------------- | --------------------------------------------- |
|
|
174
|
+
| `request` | `AxiosInstance` | 全局请求实例（仅 `ZYGlobalProvider` 的 prop） |
|
|
175
|
+
| `projectId` | `string \| number` | 静态项目 ID |
|
|
176
|
+
| `eventId` | `string \| number` | 静态事件 ID |
|
|
177
|
+
| `getProjectId` | `() => string \| number` | 动态获取项目 ID（优先级低于 `projectId`） |
|
|
178
|
+
| `getEventId` | `() => string \| number` | 动态获取事件 ID |
|
|
179
|
+
| `getDataStructure` | `(args) => Promise<any[]> \| any[]` | 自定义数据结构获取函数 |
|
|
180
|
+
|
|
181
|
+
> `projectId` / `eventId` 的解析规则：优先使用静态值；静态值为空时回退到 getter；均未提供时回退到 `-1`。`0` 视为合法值。
|
|
182
|
+
|
|
183
|
+
## 开发
|
|
42
184
|
|
|
43
185
|
```sh
|
|
186
|
+
# 安装依赖（在仓库根目录）
|
|
187
|
+
pnpm install
|
|
188
|
+
|
|
189
|
+
# 进入包目录
|
|
190
|
+
cd packages/business
|
|
191
|
+
|
|
192
|
+
# 类型检查
|
|
193
|
+
npm run type-check
|
|
194
|
+
|
|
195
|
+
# 构建
|
|
196
|
+
npm run build
|
|
197
|
+
|
|
198
|
+
# 单元测试
|
|
199
|
+
npm run test:unit
|
|
200
|
+
|
|
201
|
+
# Lint
|
|
44
202
|
npm run lint
|
|
45
203
|
```
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT
|