@qin-ui/element-plus-pro 1.0.3 → 1.0.5
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/AI-CONTEXT.md +37 -0
- package/README.md +324 -28
- package/api.json +222 -0
- package/es/component-provider/index-Bmx9Q9Q-.js +220 -0
- package/es/component-provider/index.js +2 -218
- package/es/core/{index-DVXUNE-L.js → index-C0Pbv44C.js} +28 -28
- package/es/element-plus-pro.css +10 -10
- package/es/form/{index-CWHWUZhj.js → index-D8btGgqa.js} +73 -79
- package/es/form/index.js +8 -15
- package/es/index.d.ts +672 -129
- package/es/index.js +23 -21
- package/es/table/index.js +8 -7
- package/package.json +5 -2
package/AI-CONTEXT.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# @qin-ui/element-plus-pro
|
|
2
|
+
|
|
3
|
+
> 基于 Element Plus 的配置驱动表单和表格组件库。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @qin-ui/element-plus-pro element-plus vue
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 核心导出
|
|
12
|
+
|
|
13
|
+
### 组件
|
|
14
|
+
|
|
15
|
+
- `ProForm` - 配置驱动表单组件
|
|
16
|
+
- `ProTable` - 配置驱动表格组件
|
|
17
|
+
- `ProComponentProvider` - 全局配置提供者
|
|
18
|
+
|
|
19
|
+
### Hooks
|
|
20
|
+
|
|
21
|
+
- `useForm<D>()` - 创建表单实例
|
|
22
|
+
- `useFields<D>()` - 字段配置管理
|
|
23
|
+
- `useFormRef()` - 表单组件引用
|
|
24
|
+
- `useTable<D, T>()` - 创建表格实例
|
|
25
|
+
|
|
26
|
+
## 字段配置（Field）
|
|
27
|
+
|
|
28
|
+
每个字段支持：`path`, `label`, `component`, `hidden`, `disabled`, `rules`, `valueFormatter`, `fields`, `grid`, `slots`, `componentStyle`, `componentClass`, `componentContainer`, `formItemStyle`, `formItemClass`, `formItemContainer`, `modelProp`
|
|
29
|
+
|
|
30
|
+
内置组件：input, textarea, input-search, input-password, input-number, select, cascader, date-picker, range-picker, time-picker, checkbox-group, radio-group, switch, slider, tree-select, transfer, custom
|
|
31
|
+
|
|
32
|
+
## 表格列配置（Column）
|
|
33
|
+
|
|
34
|
+
- `dataIndex` - 数据路径（优先使用）
|
|
35
|
+
- `key` - 列标识（dataIndex 不满足时使用）
|
|
36
|
+
- `hidden` - 是否隐藏
|
|
37
|
+
- 所有 Element Plus TableColumn 属性
|
package/README.md
CHANGED
|
@@ -1,77 +1,373 @@
|
|
|
1
1
|
# @qin-ui/element-plus-pro
|
|
2
2
|
|
|
3
|
-
基于 Element Plus
|
|
3
|
+
> 基于 **Element Plus** 和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm` 和 `ProTable`，助您摆脱繁琐的模板代码，极速搭建现代化桌面端中后台应用。
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
-
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://img.shields.io/badge/Element%20Plus-2.x-blue" alt="Element Plus" />
|
|
7
|
+
<img src="https://img.shields.io/badge/Vue-3.5%2B-brightgreen" alt="Vue 3.5+" />
|
|
8
|
+
<img src="https://img.shields.io/badge/TypeScript-5.x-blue" alt="TypeScript" />
|
|
9
|
+
<img src="https://img.shields.io/badge/License-MIT-green" alt="MIT" />
|
|
10
|
+
</p>
|
|
10
11
|
|
|
11
|
-
##
|
|
12
|
+
## 📝 [使用示例和文档详细内容](https://dufan3715.github.io/pro-components/)
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## ✨ 核心特性
|
|
17
|
+
|
|
18
|
+
- 🛡️ **极简设计**：基于 Element Plus 构建，原生支持 Vue 3.5+。
|
|
19
|
+
- ⚙️ **Schema 驱动**：支持通过简单的 JSON Schema 配置直接渲染表单和表格，大幅削减模版代码。
|
|
20
|
+
- 🔄 **语义对齐**：针对 Element Plus 深度定制，数据源语义统一为 `data`（不再使用 `dataSource`），默认 `modelProp` 统一为 `modelValue`。
|
|
21
|
+
- 🧩 **极致扩展**：原生支持自定义渲染组件与插槽定制，提供 `ProComponentProvider` 进行全局默认属性覆盖。
|
|
22
|
+
- 📐 **强类型推导**：基于 TypeScript 提供完备的强类型推导和自动补全，开发体验极致流畅。
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 📦 安装
|
|
27
|
+
|
|
28
|
+
确保您的项目中已安装 `element-plus` 和 `vue`：
|
|
12
29
|
|
|
13
30
|
```bash
|
|
14
31
|
pnpm add @qin-ui/element-plus-pro element-plus
|
|
15
32
|
```
|
|
16
33
|
|
|
17
|
-
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 🚀 快速开始
|
|
37
|
+
|
|
38
|
+
### 1. 全局配置与注册
|
|
18
39
|
|
|
19
40
|
```ts
|
|
20
41
|
import { createApp } from 'vue';
|
|
21
42
|
import ElementPlus from 'element-plus';
|
|
22
43
|
import 'element-plus/dist/index.css';
|
|
44
|
+
import ElementPlusPro from '@qin-ui/element-plus-pro';
|
|
23
45
|
import App from './App.vue';
|
|
24
46
|
|
|
25
47
|
const app = createApp(App);
|
|
26
48
|
app.use(ElementPlus);
|
|
49
|
+
app.use(ElementPlusPro); // 全局注册 ProForm, ProTable 和 ProComponentProvider
|
|
27
50
|
app.mount('#app');
|
|
28
51
|
```
|
|
29
52
|
|
|
53
|
+
### 2. 基础表单使用示例
|
|
54
|
+
|
|
55
|
+
```vue
|
|
56
|
+
<script setup lang="ts">
|
|
57
|
+
import { ProForm, useForm } from '@qin-ui/element-plus-pro';
|
|
58
|
+
|
|
59
|
+
interface UserForm {
|
|
60
|
+
username: string;
|
|
61
|
+
age: number;
|
|
62
|
+
role: string;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// 创建类型安全的表单实例
|
|
66
|
+
const form = useForm<UserForm>(
|
|
67
|
+
{ username: '', age: 18, role: 'user' }, // 初始数据
|
|
68
|
+
[
|
|
69
|
+
{
|
|
70
|
+
path: 'username',
|
|
71
|
+
label: '用户名',
|
|
72
|
+
component: 'input',
|
|
73
|
+
rules: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
path: 'age',
|
|
77
|
+
label: '年龄',
|
|
78
|
+
component: 'input-number',
|
|
79
|
+
min: 1,
|
|
80
|
+
max: 120,
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
path: 'role',
|
|
84
|
+
label: '角色',
|
|
85
|
+
component: 'select',
|
|
86
|
+
options: [
|
|
87
|
+
{ label: '管理员', value: 'admin' },
|
|
88
|
+
{ label: '普通用户', value: 'user' },
|
|
89
|
+
],
|
|
90
|
+
},
|
|
91
|
+
]
|
|
92
|
+
);
|
|
93
|
+
|
|
94
|
+
const handleSubmit = async () => {
|
|
95
|
+
try {
|
|
96
|
+
await form.formRef.value?.validate();
|
|
97
|
+
console.log('提交的数据：', form.formData);
|
|
98
|
+
} catch (error) {
|
|
99
|
+
console.error('校验失败：', error);
|
|
100
|
+
}
|
|
101
|
+
};
|
|
102
|
+
</script>
|
|
103
|
+
|
|
104
|
+
<template>
|
|
105
|
+
<div style="padding: 24px; max-width: 600px;">
|
|
106
|
+
<ProForm :form="form" />
|
|
107
|
+
<el-button type="primary" style="margin-top: 16px;" @click="handleSubmit">
|
|
108
|
+
提交表单
|
|
109
|
+
</el-button>
|
|
110
|
+
</div>
|
|
111
|
+
</template>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### 3. 基础表格使用示例
|
|
115
|
+
|
|
30
116
|
```vue
|
|
31
117
|
<script setup lang="ts">
|
|
32
118
|
import { ProTable, useTable } from '@qin-ui/element-plus-pro';
|
|
33
119
|
|
|
34
|
-
|
|
120
|
+
interface UserRow {
|
|
121
|
+
id: number;
|
|
122
|
+
name: string;
|
|
123
|
+
age: number;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// 使用适配 Element Plus 的 useTable 实例
|
|
127
|
+
const table = useTable<any, UserRow>({
|
|
35
128
|
columns: [
|
|
129
|
+
{ prop: 'id', label: 'ID', width: 80 },
|
|
36
130
|
{ prop: 'name', label: '姓名' },
|
|
37
131
|
{ prop: 'age', label: '年龄' },
|
|
38
132
|
],
|
|
133
|
+
data: [
|
|
134
|
+
{ id: 1, name: '张三', age: 25 },
|
|
135
|
+
{ id: 2, name: '李四', age: 30 },
|
|
136
|
+
],
|
|
39
137
|
});
|
|
40
138
|
</script>
|
|
41
139
|
|
|
42
140
|
<template>
|
|
43
|
-
<
|
|
141
|
+
<div style="padding: 24px;">
|
|
142
|
+
<ProTable :table="table" />
|
|
143
|
+
</div>
|
|
44
144
|
</template>
|
|
45
145
|
```
|
|
46
146
|
|
|
47
|
-
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## 📚 组件 API 说明
|
|
150
|
+
|
|
151
|
+
### 1. ProComponentProvider
|
|
152
|
+
|
|
153
|
+
作为全局或局部范围的上下文配置器，通过传入 `component-vars` 属性来统一覆盖子组件的默认配置。
|
|
154
|
+
|
|
155
|
+
#### Props
|
|
156
|
+
|
|
157
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
158
|
+
| :--------------- | :-------------------------------------- | :-------------- | :----- |
|
|
159
|
+
| `component-vars` | 需要全局 provide 给子组件的默认属性配置 | `ComponentVars` | - |
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
### 2. ProForm
|
|
164
|
+
|
|
165
|
+
基于 Element Plus Form 深度封装的高级表单组件。
|
|
166
|
+
|
|
167
|
+
#### Props
|
|
168
|
+
|
|
169
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
170
|
+
| :----- | :------------------------------------------------------- | :--------------------- | :------ |
|
|
171
|
+
| `form` | 由 `useForm` 返回的表单实例 | `Form` | - |
|
|
172
|
+
| `grid` | 是否启用栅格网格布局 | `boolean \| GridProps` | `false` |
|
|
173
|
+
| `...` | 其余属性均继承自 Element Plus `el-form` 组件的原生 Props | `FormProps` | - |
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
### 3. ProTable
|
|
178
|
+
|
|
179
|
+
基于 Element Plus Table 深度封装的高级表格组件。
|
|
180
|
+
|
|
181
|
+
#### Props
|
|
182
|
+
|
|
183
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
184
|
+
| :----------------- | :---------------------------------------------------- | :------------------------------------- | :------ |
|
|
185
|
+
| `table` | 由 `useTable` 返回的表格实例 | `Table` | - |
|
|
186
|
+
| `search` | 触发表格查询的回调函数，需返回 Promise | `(params: any) => Promise<any> \| any` | - |
|
|
187
|
+
| `addIndexColumn` | 是否自动在表格首列插入序号列 | `boolean` | `false` |
|
|
188
|
+
| `immediateSearch` | 表格挂载时（onMounted）是否立即触发一次 `search` 查询 | `boolean` | `false` |
|
|
189
|
+
| `control` | 是否展示尺寸调节和列动态配置控制栏 | `boolean` | `true` |
|
|
190
|
+
| `searchFormConfig` | 查询表单的布局配置参数 | `SearchFormConfig` | - |
|
|
191
|
+
| `tableContainer` | 表格的外部包裹容器，默认为 false | `Component \| false` | - |
|
|
192
|
+
| `...` | 其余参数继承自 Element Plus `el-table` 的原生属性 | `TableProps` | - |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## ⚙️ 核心 Hooks 说明
|
|
197
|
+
|
|
198
|
+
### 1. `useForm`
|
|
199
|
+
|
|
200
|
+
用于创建和管理表单实例，组合了表单数据、字段规则和 ref 控制。
|
|
201
|
+
|
|
202
|
+
#### 入参定义
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
const form = useForm<D>(initFormData?, initFields?, root?)
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
#### 返回值 (Form 实例)
|
|
209
|
+
|
|
210
|
+
| 属性/方法 | 说明 | 类型 |
|
|
211
|
+
| :----------------------------- | :------------------------------------------------------------ | :------------------------------- |
|
|
212
|
+
| `formData` | 响应式表单数据对象（由 reactive 包装） | `Reactive<D>` |
|
|
213
|
+
| `fields` | 响应式表单字段配置数组引用 | `Ref<Field[]>` |
|
|
214
|
+
| `formRef` | 底层 Element Plus `el-form` 的组件引用实例 | `Ref<FormInstance \| undefined>` |
|
|
215
|
+
| `getFormData(path)` | 安全获取指定字段路径的数据值 | `(path) => any` |
|
|
216
|
+
| `setFormData(path, val)` | 安全更新指定路径的值，支持批量对象或函数式更新 | `(path, val) => void` |
|
|
217
|
+
| `getField(path, opts?)` | 获取指定 path 的字段配置，支持 `{ all: true }` 获取所有匹配项 | `(path, opts) => Field` |
|
|
218
|
+
| `setField(path, patch, opts?)` | 增量更新指定字段的配置参数，支持 merge 或 rewrite 更新 | `(path, patch, opts) => void` |
|
|
219
|
+
| `deleteField(path)` | 从配置数组中删除特定 path 的表单字段配置 | `(path) => void` |
|
|
220
|
+
| `appendField(path, field)` | 在特定的字段 path 后面，动态追加一个新的表单字段配置 | `(path, field) => void` |
|
|
221
|
+
| `prependField(path, field)` | 在特定的字段 path 前面，动态插入一个新的表单字段配置 | `(path, field) => void` |
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
### 2. `useTable`
|
|
226
|
+
|
|
227
|
+
用于创建和管理表格实例，深度融合 Element Plus 的 API 设计。
|
|
228
|
+
|
|
229
|
+
#### 入参参数
|
|
230
|
+
|
|
231
|
+
```ts
|
|
232
|
+
const table = useTable<D, T>({
|
|
233
|
+
columns: [], // 初始列配置
|
|
234
|
+
data: [], // Element Plus 数据源（与 core 的 dataSource 对应）
|
|
235
|
+
pageParam: {}, // 分页参数配置
|
|
236
|
+
searchParam: {}, // 搜索栏初始数据
|
|
237
|
+
searchFields: [], // 搜索栏字段 Schema 配置
|
|
238
|
+
});
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
#### 返回值 (Table 实例)
|
|
242
|
+
|
|
243
|
+
| 属性/方法 | 说明 | 类型 |
|
|
244
|
+
| :------------------------ | :---------------------------------------------------------- | :--------------------- |
|
|
245
|
+
| `columns` | 响应式表格列配置数组 | `Ref<Column[]>` |
|
|
246
|
+
| `data` | **响应式表格数据源（已重命名为 data 以适配 Element Plus）** | `Ref<T[]>` |
|
|
247
|
+
| `pageParam` | 响应式分页参数对象（包含 `current`, `pageSize`, `total`） | `Reactive<PageParam>` |
|
|
248
|
+
| `searchForm` | 搜索栏表单关联的 `useForm` 实例，提供完美的表单操作 API | `Form<D>` |
|
|
249
|
+
| `setColumn(key, patch)` | 合并或重置修改指定 key 的列配置属性（如 width、label 等） | `(key, patch) => void` |
|
|
250
|
+
| `deleteColumn(key)` | 动态移除某一个指定 key 对应的表格列配置 | `(key) => void` |
|
|
251
|
+
| `appendColumn(key, col)` | 在某一个列的后方动态追加配置列 | `(key, col) => void` |
|
|
252
|
+
| `prependColumn(key, col)` | 在某一个列的前方动态插入配置列 | `(key, col) => void` |
|
|
253
|
+
| `setPageParam(param)` | 增量设置当前分页参数值，支持传入对象或更新函数 | `(param) => void` |
|
|
254
|
+
| `resetQueryParams()` | 重置搜索参数，并恢复分页至第 1 页 | `() => void` |
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## 📄 表格列配置（`Column`）说明
|
|
259
|
+
|
|
260
|
+
列配置采用 Element Plus 原生协议为主，极易上手：
|
|
261
|
+
|
|
262
|
+
- **原生列属性支持**：`prop`、`label`、`width`、`fixed`、`align`、`sortable`、`filters`、`filterMethod`、`children` 等
|
|
263
|
+
- **原生格式化支持**：`formatter`
|
|
264
|
+
- **Pro 级扩展属性**：
|
|
265
|
+
- `hidden` (是否隐藏列，支持响应式)
|
|
266
|
+
- `render(scope)` (自定义渲染插槽，接收行参数)
|
|
267
|
+
|
|
268
|
+
> [!TIP]
|
|
269
|
+
> 渲染优先级为：`render(scope)` > `formatter`。
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## 📄 表单字段配置（`Field`）说明
|
|
48
274
|
|
|
49
|
-
|
|
275
|
+
### 公共基础属性
|
|
50
276
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
277
|
+
| 属性名 | 说明 | 类型 | 默认值 |
|
|
278
|
+
| :------------------- | :---------------------------------------------------------------------------- | :---------------------------- | :------------- |
|
|
279
|
+
| `path` | 字段标识，需对应数据对象 `formData` 的 key，支持多级嵌套，例如 `address.city` | `string` | - |
|
|
280
|
+
| `label` | 字段中文标签，支持字符串或直接传入 VNode 组件进行自定义 | `string \| Component \| Slot` | - |
|
|
281
|
+
| `component` | 调用的表单项组件的类型，支持内置类型键名或直接传入自定义 Vue 组件 | `string \| Component` | `'input'` |
|
|
282
|
+
| `hidden` | 字段是否被隐藏（在 DOM 中不渲染），支持 Ref/Computed 响应式 | `boolean \| Ref<boolean>` | `false` |
|
|
283
|
+
| `disabled` | 组件的禁用状态，支持 Ref/Computed 响应式 | `boolean \| Ref<boolean>` | `false` |
|
|
284
|
+
| `rules` | 字段数据校验规则，遵循 Element Plus 表单校验格式 | `Rule[]` | - |
|
|
285
|
+
| `span` | 栅格占位宽度（在 ProForm 开启 `grid` 后有效） | `number` | - |
|
|
286
|
+
| `formItemStyle` | 挂载在外部 `el-form-item` 节点上的额外 CSS 样式属性 | `CSSProperties` | - |
|
|
287
|
+
| `formItemClass` | 挂载在外部 `el-form-item` 节点上的自定义类名 | `string` | - |
|
|
288
|
+
| `formItemContainer` | 针对该表单项的最外层 DOM 包裹组件 | `Component` | - |
|
|
289
|
+
| `formItemDataAttrs` | 附加在 `el-form-item` DOM 节点上的自定义 data 属性 | `Record<string, string>` | - |
|
|
290
|
+
| `componentStyle` | 直接传递给内部表单输入组件的额外 CSS 样式属性 | `CSSProperties` | - |
|
|
291
|
+
| `componentClass` | 直接传递给内部表单输入组件的自定义类名 | `string` | - |
|
|
292
|
+
| `componentContainer` | 针对表单输入组件的包裹组件 | `Component` | - |
|
|
293
|
+
| `componentDataAttrs` | 附加在内部输入组件 DOM 节点上的自定义 data 属性 | `Record<string, string>` | - |
|
|
294
|
+
| `valueFormatter` | 字段值转换处理器，可在输入更新或提取数据时做 get/set 转换 | `ValueFormatter` | - |
|
|
295
|
+
| `modelProp` | 双向绑定的数据属性名称（默认为 `modelValue`） | `string` | `'modelValue'` |
|
|
296
|
+
| `fields` | 嵌套子表单项的 Schema 数组配置 | `Field[]` | - |
|
|
297
|
+
| `grid` | 针对当前嵌套子表单项所使用的网格布局参数（仅当有 `fields` 时有效） | `boolean \| GridProps` | - |
|
|
54
298
|
|
|
55
|
-
|
|
299
|
+
---
|
|
56
300
|
|
|
57
|
-
|
|
301
|
+
### 内置组件映射（`component` 可选值）
|
|
58
302
|
|
|
59
|
-
|
|
303
|
+
您可以在 `component` 属性中填入以下预设键名来自动调用内置的 Element Plus 组件：
|
|
60
304
|
|
|
61
|
-
|
|
305
|
+
| 内置键名 | 渲染对应的 Element Plus 组件 |
|
|
306
|
+
| :----------------- | :--------------------------------------------------------------- |
|
|
307
|
+
| `'input'` | `el-input` 文本输入框（可搭配 `type: 'textarea' \| 'password'`） |
|
|
308
|
+
| `'input-number'` | `el-input-number` 数字输入框 |
|
|
309
|
+
| `'autocomplete'` | `el-autocomplete` 自动完成 |
|
|
310
|
+
| `'select'` | `el-select` 下拉选择器 |
|
|
311
|
+
| `'cascader'` | `el-cascader` 级联选择器 |
|
|
312
|
+
| `'date-picker'` | `el-date-picker` 日期选择器（支持多种 `type` 属性） |
|
|
313
|
+
| `'time-picker'` | `el-time-picker` 时间选择器 |
|
|
314
|
+
| `'time-select'` | `el-time-select` 时间选择下拉框 |
|
|
315
|
+
| `'checkbox-group'` | `el-checkbox-group` 复选框组 |
|
|
316
|
+
| `'radio-group'` | `el-radio-group` 单选按钮组 |
|
|
317
|
+
| `'switch'` | `el-switch` 开关切换器 |
|
|
318
|
+
| `'slider'` | `el-slider` 滑动条 |
|
|
319
|
+
| `'tree-select'` | `el-tree-select` 树形选择器 |
|
|
320
|
+
| `'transfer'` | `el-transfer` 穿梭框 |
|
|
321
|
+
| `'custom'` | 完全渲染自定义组件 |
|
|
62
322
|
|
|
63
|
-
|
|
64
|
-
- `input-number`
|
|
65
|
-
- `autocomplete`
|
|
66
|
-
- `select` / `cascader`
|
|
67
|
-
- `date-picker`（可配合 `type: 'date' | 'dates' | 'daterange' | 'datetimerange'` 等）
|
|
68
|
-
- `time-picker` / `time-select`
|
|
69
|
-
- `checkbox-group` / `radio-group`
|
|
70
|
-
- `switch` / `slider` / `tree-select` / `transfer`
|
|
323
|
+
---
|
|
71
324
|
|
|
72
|
-
|
|
325
|
+
## 🧩 扩展注册您的自定义组件
|
|
326
|
+
|
|
327
|
+
### 步骤 1：利用 ComponentProvider 全局注册
|
|
328
|
+
|
|
329
|
+
```vue
|
|
330
|
+
<script setup lang="ts">
|
|
331
|
+
import { ProComponentProvider } from '@qin-ui/element-plus-pro';
|
|
332
|
+
import MyCustomWidget from './components/MyCustomWidget.vue';
|
|
333
|
+
|
|
334
|
+
const componentMap = {
|
|
335
|
+
'my-widget': MyCustomWidget,
|
|
336
|
+
};
|
|
337
|
+
</script>
|
|
338
|
+
|
|
339
|
+
<template>
|
|
340
|
+
<ProComponentProvider :component-map="componentMap">
|
|
341
|
+
<RouterView />
|
|
342
|
+
</ProComponentProvider>
|
|
343
|
+
</template>
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
### 步骤 2：追加 TypeScript 全局声明获取强类型补全
|
|
347
|
+
|
|
348
|
+
在项目任意 `.d.ts` 类型文件中写入以下代码：
|
|
349
|
+
|
|
350
|
+
```ts
|
|
351
|
+
declare module '@qin-ui/element-plus-pro' {
|
|
352
|
+
interface ComponentMap {
|
|
353
|
+
'my-widget': typeof MyCustomWidget;
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
---
|
|
73
359
|
|
|
74
360
|
## Peer Dependencies
|
|
75
361
|
|
|
76
362
|
- `vue` `^3.5.0`
|
|
77
363
|
- `element-plus` `^2.13.6`
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## 🤝 贡献与反馈
|
|
368
|
+
|
|
369
|
+
如有任何问题，欢迎通过 [GitHub Issues](https://github.com/dufan3715/pro-components/issues) 提交反馈。
|
|
370
|
+
|
|
371
|
+
## 📄 开源许可证
|
|
372
|
+
|
|
373
|
+
基于 [MIT](LICENSE) 开源许可证。
|
package/api.json
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
{
|
|
2
|
+
"generatedAt": "2026-06-04T09:03:47.369Z",
|
|
3
|
+
"name": "@qin-ui/element-plus-pro",
|
|
4
|
+
"api": [
|
|
5
|
+
{
|
|
6
|
+
"name": "ProComponentProvider",
|
|
7
|
+
"type": "component",
|
|
8
|
+
"package": "@qin-ui/element-plus-pro",
|
|
9
|
+
"signature": "<ProComponentProvider>",
|
|
10
|
+
"description": "@qin-ui/element-plus-pro 全局配置提供者组件\n用于在组件树的顶层配置所有子组件的全局默认属性。",
|
|
11
|
+
"examples": [
|
|
12
|
+
"```vue\n<ProComponentProvider\n:componentVars=\"{ 'input': { placeholder: '请输入' } }\"\n>\n<ProForm :form=\"form\" :fields=\"fields\" />\n</ProComponentProvider>\n```"
|
|
13
|
+
]
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"name": "ProForm",
|
|
17
|
+
"type": "component",
|
|
18
|
+
"package": "@qin-ui/element-plus-pro",
|
|
19
|
+
"signature": "<ProForm>",
|
|
20
|
+
"description": "@qin-ui/element-plus-pro 配置驱动表单组件\n通过配置驱动的方式快速构建表单，支持：\n- 字段联动、嵌套字段、自定义组件、网格布局",
|
|
21
|
+
"typeParams": [
|
|
22
|
+
{
|
|
23
|
+
"name": "F"
|
|
24
|
+
}
|
|
25
|
+
]
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"name": "ContainerFragment",
|
|
29
|
+
"type": "component",
|
|
30
|
+
"package": "@qin-ui/element-plus-pro",
|
|
31
|
+
"signature": "<ContainerFragment>",
|
|
32
|
+
"description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"name": "SlotComponent",
|
|
36
|
+
"type": "component",
|
|
37
|
+
"package": "@qin-ui/element-plus-pro",
|
|
38
|
+
"signature": "<SlotComponent>",
|
|
39
|
+
"description": "插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。"
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
"name": "ComponentMap",
|
|
43
|
+
"type": "interface",
|
|
44
|
+
"package": "@qin-ui/element-plus-pro",
|
|
45
|
+
"signature": "export interface ComponentMap {}",
|
|
46
|
+
"description": "组件映射扩展接口\n暴露给外部扩充自定义组件类型的接口。\n用户可通过 TypeScript 的声明合并（module augmentation）添加自定义组件。",
|
|
47
|
+
"examples": [
|
|
48
|
+
"```ts\ndeclare module '@qin-ui/element-plus-pro' {\ninterface ComponentMap {\n'my-custom-input': typeof MyCustomInput;\n}\n}\n```"
|
|
49
|
+
]
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"name": "ComponentName",
|
|
53
|
+
"type": "type",
|
|
54
|
+
"package": "@qin-ui/element-plus-pro",
|
|
55
|
+
"signature": "export type ComponentName =\n | keyof BaseComponentMap\n | keyof ComponentMap\n | 'custom';",
|
|
56
|
+
"description": "组件名称联合类型\n所有支持的组件名称"
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
"name": "useFormData",
|
|
60
|
+
"type": "function",
|
|
61
|
+
"package": "@qin-ui/element-plus-pro",
|
|
62
|
+
"signature": "export const useFormData = <D extends Data = Data>(\n initFormData?: ExtendWithAny<DeepPartial<D>>\n) =>",
|
|
63
|
+
"description": "表单数据处理 Hook\n提供响应式表单数据的管理能力，支持：\n- 响应式数据存储（基于 Vue reactive）\n- 深层路径读写（支持点号分隔，如 'address.city'）\n- 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）\n- 父子表单自动注入（非根表单会从注入中获取数据）",
|
|
64
|
+
"returns": "{Function} .setFormData(path, value) - 设置指定路径的数据",
|
|
65
|
+
"typeParams": [
|
|
66
|
+
{
|
|
67
|
+
"name": "D"
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
"examples": [
|
|
71
|
+
"```ts\ninterface User { name: string; age: number; address: { city: string } }\n\nconst { formData, getFormData, setFormData } = useFormData<User>({\nname: '张三',\naddress: { city: '北京' }\n})\n\n// 读取\ngetFormData('name') // '张三'\ngetFormData('address.city') // '北京'\nformData.name // '张三'（响应式）\n\n// 设置\nsetFormData('name', '李四')\nsetFormData('address.city', '上海')\nsetFormData({ name: '王五', age: 30 }) // 批量覆盖\nsetFormData(prev => ({ ...prev, name: '赵六' })) // 函数式更新\n```"
|
|
72
|
+
]
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"name": "useFields",
|
|
76
|
+
"type": "function",
|
|
77
|
+
"package": "@qin-ui/element-plus-pro",
|
|
78
|
+
"signature": "export const useFields = _useFields as",
|
|
79
|
+
"description": "类型安全的 re-export。将 core useFields 的泛型参数绑定为本地类型：\n- 字段类型 F → Field<ComponentName, D>（支持 Element Plus 组件类型推导）\n- FormItem 实例 → Element Plus 的 FormItemInstance",
|
|
80
|
+
"typeParams": [
|
|
81
|
+
{
|
|
82
|
+
"name": "D"
|
|
83
|
+
}
|
|
84
|
+
],
|
|
85
|
+
"examples": [
|
|
86
|
+
"```ts\ninterface User { name: string; age: number }\n\nconst { fields, getField, setField } = useFields<User>([\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n])\n```"
|
|
87
|
+
]
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"name": "UseFields",
|
|
91
|
+
"type": "type",
|
|
92
|
+
"package": "@qin-ui/element-plus-pro",
|
|
93
|
+
"signature": "export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;",
|
|
94
|
+
"description": "useFields 返回值类型，固定为本地 Fields<D>"
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"name": "Form",
|
|
98
|
+
"type": "type",
|
|
99
|
+
"package": "@qin-ui/element-plus-pro",
|
|
100
|
+
"signature": "export type Form<\n D extends Data = Data,\n F extends Field<ComponentName, D> = Field<ComponentName, D>,\n> = _Form<D, F, FormInstance>;",
|
|
101
|
+
"description": "在 core Form 类型的基础上：\n1. 将字段类型 F 默认绑定为本地 Field<ComponentName, D>，支持 Element Plus 所有内置组件类型\n2. 将底层表单实例 I 绑定为 Element Plus 的 FormInstance，使 formRef 获得完整的类型提示",
|
|
102
|
+
"typeParams": [
|
|
103
|
+
{
|
|
104
|
+
"name": "D"
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"name": "F"
|
|
108
|
+
}
|
|
109
|
+
]
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
"name": "useForm",
|
|
113
|
+
"type": "function",
|
|
114
|
+
"package": "@qin-ui/element-plus-pro",
|
|
115
|
+
"signature": "export const useForm = _useForm as",
|
|
116
|
+
"description": "创建 @qin-ui/element-plus-pro 表单实例的 Hook\n类型安全的 re-export。将 core useForm 的泛型参数绑定为本地类型：\n- 字段类型 F → Field<ComponentName, D>（支持 Element Plus 组件类型推导）\n- 表单实例 → Element Plus 的 FormInstance",
|
|
117
|
+
"typeParams": [
|
|
118
|
+
{
|
|
119
|
+
"name": "D"
|
|
120
|
+
}
|
|
121
|
+
],
|
|
122
|
+
"examples": [
|
|
123
|
+
"```ts\ninterface User { name: string; age: number }\n\nconst form = useForm<User>(\n{ name: '张三', age: 25 },\n[\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n]\n)\n```"
|
|
124
|
+
]
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
"name": "useFormRef",
|
|
128
|
+
"type": "function",
|
|
129
|
+
"package": "@qin-ui/element-plus-pro",
|
|
130
|
+
"signature": "export const useFormRef = _useFormRef as",
|
|
131
|
+
"description": "类型安全的 re-export。将 core useFormRef 的泛型参数绑定为 Element Plus 的 FormInstance，\n使 formRef 获取到完整的 Element Plus Form 组件 API 类型提示。",
|
|
132
|
+
"returns": "{Function} .setFormRef(inst) - 设置表单组件实例",
|
|
133
|
+
"examples": [
|
|
134
|
+
"```ts\nconst { formRef, setFormRef } = useFormRef()\nawait formRef.value?.validate()\nformRef.value?.resetFields()\n```"
|
|
135
|
+
]
|
|
136
|
+
},
|
|
137
|
+
{
|
|
138
|
+
"name": "Field",
|
|
139
|
+
"type": "type",
|
|
140
|
+
"package": "@qin-ui/element-plus-pro",
|
|
141
|
+
"signature": "export type Field<\n C extends ComponentName = ComponentName,\n D extends Data = Data,\n> =\n | (FieldTypeMap<D>[C] &",
|
|
142
|
+
"description": "字段配置类型，包含所有字段属性和响应式支持",
|
|
143
|
+
"typeParams": [
|
|
144
|
+
{
|
|
145
|
+
"name": "D"
|
|
146
|
+
}
|
|
147
|
+
]
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
"name": "Fields",
|
|
151
|
+
"type": "type",
|
|
152
|
+
"package": "@qin-ui/element-plus-pro",
|
|
153
|
+
"signature": "export type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;",
|
|
154
|
+
"description": "字段数组类型",
|
|
155
|
+
"typeParams": [
|
|
156
|
+
{
|
|
157
|
+
"name": "D"
|
|
158
|
+
}
|
|
159
|
+
]
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
"name": "ColumnScope",
|
|
163
|
+
"type": "type",
|
|
164
|
+
"package": "@qin-ui/element-plus-pro",
|
|
165
|
+
"signature": "export type ColumnScope<D extends Data = Data> =",
|
|
166
|
+
"description": "Element Plus 表格列作用域",
|
|
167
|
+
"typeParams": [
|
|
168
|
+
{
|
|
169
|
+
"name": "D"
|
|
170
|
+
}
|
|
171
|
+
]
|
|
172
|
+
},
|
|
173
|
+
{
|
|
174
|
+
"name": "Column",
|
|
175
|
+
"type": "type",
|
|
176
|
+
"package": "@qin-ui/element-plus-pro",
|
|
177
|
+
"signature": "export type Column<D extends Data = Data> = Partial<\n Omit<ColumnType<any>, 'prop' | 'property' | 'children' | 'render'>\n> &",
|
|
178
|
+
"description": "基于 Element Plus 的 ColumnType 列类型，并添加：\n- prop 作为主要字段（Element Plus 使用 prop 而非 dataIndex）\n- key 作为辅助标识\n- hidden 属性\n- render 自定义渲染函数",
|
|
179
|
+
"typeParams": [
|
|
180
|
+
{
|
|
181
|
+
"name": "D"
|
|
182
|
+
}
|
|
183
|
+
],
|
|
184
|
+
"examples": [
|
|
185
|
+
"```ts\ninterface User { name: string; age: number }\n\nconst columns: Columns<User> = [\n{ prop: 'name', label: '姓名', width: 120 },\n{ prop: 'age', label: '年龄', width: 80 },\n]\n```"
|
|
186
|
+
]
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
"name": "Table",
|
|
190
|
+
"type": "type",
|
|
191
|
+
"package": "@qin-ui/element-plus-pro",
|
|
192
|
+
"signature": "export type Table<\n D extends Data = Data,\n T extends Data = ExtendWithAny<D>,\n> = Omit<_Table<D, T, Column<T>>, 'dataSource'> &",
|
|
193
|
+
"description": "在 core Table 类型的基础上：\n1. 将列类型 C 绑定为本地 Column<T>\n2. 将 dataSource 重命名为 data（Element Plus 使用 data 而非 dataSource）",
|
|
194
|
+
"typeParams": [
|
|
195
|
+
{
|
|
196
|
+
"name": "D"
|
|
197
|
+
},
|
|
198
|
+
{
|
|
199
|
+
"name": "T"
|
|
200
|
+
}
|
|
201
|
+
]
|
|
202
|
+
},
|
|
203
|
+
{
|
|
204
|
+
"name": "useTable",
|
|
205
|
+
"type": "function",
|
|
206
|
+
"package": "@qin-ui/element-plus-pro",
|
|
207
|
+
"signature": "export const useTable = <\n D extends Data = Data,\n T extends Data = ExtendWithAny<D>,\n>(\n params: UseTableParams<D, T> = {}",
|
|
208
|
+
"description": "创建 @qin-ui/element-plus-pro 表格实例的 Hook\n基于 core useTable 封装，适配 Element Plus 的 API 风格：\n- 数据源使用 `data` 而非 `dataSource`",
|
|
209
|
+
"typeParams": [
|
|
210
|
+
{
|
|
211
|
+
"name": "D"
|
|
212
|
+
},
|
|
213
|
+
{
|
|
214
|
+
"name": "T"
|
|
215
|
+
}
|
|
216
|
+
],
|
|
217
|
+
"examples": [
|
|
218
|
+
"```ts\ninterface User { name: string; age: number }\n\nconst table = useTable<User>({\ncolumns: [\n{ prop: 'name', title: '姓名', width: 120 },\n{ prop: 'age', title: '年龄', width: 80 },\n],\ndata: [],\npageParam: { current: 1, pageSize: 20, total: 0 },\n})\n```"
|
|
219
|
+
]
|
|
220
|
+
}
|
|
221
|
+
]
|
|
222
|
+
}
|