@qin-ui/antd-vue-pro 2.1.9 → 2.1.11
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 +123 -0
- package/LICENSE +9 -0
- package/README.md +312 -67
- package/api.json +229 -0
- package/es/antd-vue-pro.css +6 -6
- package/es/component-provider/index-Dmz32tSB.js +174 -0
- package/es/component-provider/index.js +2 -172
- package/es/core/{index-C98RSrpN.js → index-ghYuQ3Sy.js} +29 -29
- package/es/form/index.js +65 -74
- package/es/index.d.ts +763 -138
- package/es/index.js +18 -17
- package/es/table/index.js +3 -3
- package/package.json +12 -9
package/AI-CONTEXT.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# @qin-ui/antd-vue-pro
|
|
2
|
+
|
|
3
|
+
> 基于 ant-design-vue v4 的配置驱动表单和表格组件库。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @qin-ui/antd-vue-pro ant-design-vue vue
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 快速开始
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { ProForm, ProTable } from '@qin-ui/antd-vue-pro';
|
|
15
|
+
import { useForm, useTable } from '@qin-ui/antd-vue-pro';
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 核心导出
|
|
19
|
+
|
|
20
|
+
### 组件
|
|
21
|
+
|
|
22
|
+
| 组件名 | 描述 |
|
|
23
|
+
| ---------------------- | ---------------- |
|
|
24
|
+
| `ProForm` | 配置驱动表单组件 |
|
|
25
|
+
| `ProTable` | 配置驱动表格组件 |
|
|
26
|
+
| `ProComponentProvider` | 全局配置提供者 |
|
|
27
|
+
|
|
28
|
+
### Hooks
|
|
29
|
+
|
|
30
|
+
| Hook | 描述 |
|
|
31
|
+
| ------------------ | ------------ |
|
|
32
|
+
| `useForm<D>()` | 创建表单实例 |
|
|
33
|
+
| `useFields<D>()` | 字段配置管理 |
|
|
34
|
+
| `useFormRef()` | 表单组件引用 |
|
|
35
|
+
| `useTable<D, T>()` | 创建表格实例 |
|
|
36
|
+
|
|
37
|
+
## ProForm 使用
|
|
38
|
+
|
|
39
|
+
```vue
|
|
40
|
+
<template>
|
|
41
|
+
<ProForm :form="form" @submit="onSubmit">
|
|
42
|
+
<template #name="{ value }">
|
|
43
|
+
<a-input :value="value" />
|
|
44
|
+
</template>
|
|
45
|
+
</ProForm>
|
|
46
|
+
</template>
|
|
47
|
+
|
|
48
|
+
<script setup lang="ts">
|
|
49
|
+
interface User {
|
|
50
|
+
name: string;
|
|
51
|
+
age: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const form = useForm<User>({ name: '张三' }, [
|
|
55
|
+
{ path: 'name', label: '姓名', component: 'input' },
|
|
56
|
+
{ path: 'age', label: '年龄', component: 'input-number' },
|
|
57
|
+
]);
|
|
58
|
+
</script>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## ProTable 使用
|
|
62
|
+
|
|
63
|
+
```vue
|
|
64
|
+
<template>
|
|
65
|
+
<ProTable :table="table" />
|
|
66
|
+
</template>
|
|
67
|
+
|
|
68
|
+
<script setup lang="ts">
|
|
69
|
+
interface User {
|
|
70
|
+
name: string;
|
|
71
|
+
age: number;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const table = useTable({
|
|
75
|
+
columns: [
|
|
76
|
+
{ dataIndex: 'name', title: '姓名' },
|
|
77
|
+
{ dataIndex: 'age', title: '年龄' },
|
|
78
|
+
],
|
|
79
|
+
dataSource: [],
|
|
80
|
+
});
|
|
81
|
+
</script>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## 字段配置（Field）
|
|
85
|
+
|
|
86
|
+
每个字段支持以下属性：
|
|
87
|
+
|
|
88
|
+
- `path` - 数据路径（类型安全）
|
|
89
|
+
- `label` - 字段标签
|
|
90
|
+
- `component` - 组件名（内置支持: input, select, date-picker, cascader 等）
|
|
91
|
+
- `hidden` - 是否隐藏
|
|
92
|
+
- `disabled` - 是否禁用
|
|
93
|
+
- `rules` - 校验规则
|
|
94
|
+
- `valueFormatter` - 值格式化函数
|
|
95
|
+
- `fields` - 嵌套子字段
|
|
96
|
+
- `grid` - 网格布局
|
|
97
|
+
- `slots` - FormItem 插槽配置
|
|
98
|
+
- `componentStyle/componentClass` - 组件样式
|
|
99
|
+
- `componentContainer` - 组件容器包装
|
|
100
|
+
- `formItemStyle/formItemClass` - FormItem 样式
|
|
101
|
+
- `formItemContainer` - FormItem 容器包装
|
|
102
|
+
- `modelProp` - v-model 绑定属性名
|
|
103
|
+
|
|
104
|
+
完整类型定义见 `Field<ComponentName, D>`。
|
|
105
|
+
|
|
106
|
+
## 表格列配置（Column）
|
|
107
|
+
|
|
108
|
+
每列支持以下属性：
|
|
109
|
+
|
|
110
|
+
- `dataIndex` - 数据路径（优先使用）
|
|
111
|
+
- `key` - 列标识（dataIndex 不满足时使用）
|
|
112
|
+
- `hidden` - 是否隐藏
|
|
113
|
+
- 所有 ant-design-vue ColumnType 属性（title, width, fixed, align 等）
|
|
114
|
+
|
|
115
|
+
## 类型扩展
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
declare module '@qin-ui/antd-vue-pro' {
|
|
119
|
+
interface ComponentMap {
|
|
120
|
+
'my-custom-component': typeof MyComponent;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
package/LICENSE
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023-present pro-components
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,113 +1,358 @@
|
|
|
1
|
-
# antd-vue-pro
|
|
1
|
+
# @qin-ui/antd-vue-pro
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> 基于 **Ant Design Vue v4+** 和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm` 和 `ProTable`，助您摆脱繁琐的模板代码，快速搭建桌面端中后台应用。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://img.shields.io/badge/Ant%20Design%20Vue-4.x-blue" alt="Ant Design Vue 4.x" />
|
|
7
|
+
<img src="https://img.shields.io/badge/Vue-3.3%2B-brightgreen" alt="Vue 3.3+" />
|
|
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>
|
|
11
|
+
|
|
12
|
+
## 📝 [使用示例和文档详细内容](https://dufan3715.github.io/pro-components/)
|
|
6
13
|
|
|
7
14
|
---
|
|
8
15
|
|
|
9
|
-
## ✨
|
|
16
|
+
## ✨ 核心特性
|
|
10
17
|
|
|
11
|
-
- 🛡️
|
|
12
|
-
- 🔥
|
|
13
|
-
- ⚙️
|
|
18
|
+
- 🛡️ **底层坚实**：基于 Ant Design Vue 4.x 构建，原生支持 Vue 3.3+。
|
|
19
|
+
- 🔥 **Schema 驱动**：使用声明式 JSON 配置即可快速生成表单，极大地减少了模板文件的编写。
|
|
20
|
+
- ⚙️ **动态自适应**：支持表单字段的动态隐藏、禁用与规则联动，表格列的动态控制与配置。
|
|
21
|
+
- 🧩 **极致扩展**：原生支持自定义渲染组件与插槽定制，提供 `ProComponentProvider` 进行全局默认属性覆盖。
|
|
22
|
+
- 📐 **完美类型推导**：基于 TypeScript 提供完备的强类型推导和自动补全，开发体验流畅。
|
|
14
23
|
|
|
15
24
|
---
|
|
16
25
|
|
|
17
26
|
## 📦 安装
|
|
18
27
|
|
|
19
|
-
|
|
28
|
+
确保您的项目中已安装 `ant-design-vue` (v4+) 和 `vue` (v3.3+)：
|
|
29
|
+
|
|
30
|
+
```bash
|
|
20
31
|
npm i @qin-ui/antd-vue-pro
|
|
32
|
+
# 或使用 pnpm
|
|
33
|
+
pnpm add @qin-ui/antd-vue-pro
|
|
21
34
|
```
|
|
22
35
|
|
|
23
|
-
>
|
|
36
|
+
> [!WARNING]
|
|
37
|
+
> **2.0+ 升级提示**：2.0 版本进行了底层重构，`useForm` 返回的 `formData` 从原本的 `ref` 包装调整为了真正的 `reactive` 响应式对象，获取和修改属性时无需使用 `.value`。
|
|
24
38
|
|
|
25
39
|
---
|
|
26
40
|
|
|
27
|
-
##
|
|
41
|
+
## 🚀 快速开始
|
|
42
|
+
|
|
43
|
+
### 1. 全局注册组件（可选）
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { createApp } from 'vue';
|
|
47
|
+
import Antd from 'ant-design-vue';
|
|
48
|
+
import 'ant-design-vue/dist/reset.css';
|
|
49
|
+
import AntdVuePro from '@qin-ui/antd-vue-pro';
|
|
50
|
+
import App from './App.vue';
|
|
51
|
+
|
|
52
|
+
const app = createApp(App);
|
|
53
|
+
app.use(Antd);
|
|
54
|
+
app.use(AntdVuePro); // 全局注册 ProForm, ProTable 和 ProComponentProvider
|
|
55
|
+
app.mount('#app');
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 2. 基础表单使用示例
|
|
59
|
+
|
|
60
|
+
```vue
|
|
61
|
+
<script setup lang="ts">
|
|
62
|
+
import { ProForm, useForm } from '@qin-ui/antd-vue-pro';
|
|
63
|
+
|
|
64
|
+
interface UserForm {
|
|
65
|
+
username: string;
|
|
66
|
+
age: number;
|
|
67
|
+
gender: string;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// 1. 创建类型安全的表单实例
|
|
71
|
+
const form = useForm<UserForm>(
|
|
72
|
+
{ username: '张三', age: 18, gender: 'male' }, // 初始数据
|
|
73
|
+
[
|
|
74
|
+
{
|
|
75
|
+
path: 'username',
|
|
76
|
+
label: '用户名',
|
|
77
|
+
component: 'input',
|
|
78
|
+
rules: [{ required: true, message: '请输入用户名' }],
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
path: 'age',
|
|
82
|
+
label: '年龄',
|
|
83
|
+
component: 'input-number',
|
|
84
|
+
min: 1,
|
|
85
|
+
max: 150,
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
path: 'gender',
|
|
89
|
+
label: '性别',
|
|
90
|
+
component: 'select',
|
|
91
|
+
options: [
|
|
92
|
+
{ label: '男', value: 'male' },
|
|
93
|
+
{ label: '女', value: 'female' },
|
|
94
|
+
],
|
|
95
|
+
},
|
|
96
|
+
]
|
|
97
|
+
);
|
|
98
|
+
|
|
99
|
+
// 2. 提交表单校验与数据获取
|
|
100
|
+
const handleSubmit = async () => {
|
|
101
|
+
try {
|
|
102
|
+
await form.formRef.value?.validate();
|
|
103
|
+
console.log('提交的数据：', form.formData);
|
|
104
|
+
} catch (error) {
|
|
105
|
+
console.error('校验失败：', error);
|
|
106
|
+
}
|
|
107
|
+
};
|
|
108
|
+
</script>
|
|
109
|
+
|
|
110
|
+
<template>
|
|
111
|
+
<div style="padding: 24px; max-width: 600px;">
|
|
112
|
+
<ProForm :form="form" />
|
|
113
|
+
<a-button type="primary" style="margin-top: 16px;" @click="handleSubmit">
|
|
114
|
+
提交表单
|
|
115
|
+
</a-button>
|
|
116
|
+
</div>
|
|
117
|
+
</template>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 📚 组件 API 说明
|
|
28
123
|
|
|
29
124
|
### 1. ProComponentProvider
|
|
30
125
|
|
|
31
|
-
|
|
126
|
+
作为全局或局部范围的上下文配置器，通过传入 `component-vars` 属性来统一覆盖子组件的默认配置。
|
|
32
127
|
|
|
33
|
-
####
|
|
128
|
+
#### Props
|
|
34
129
|
|
|
35
|
-
|
|
130
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
131
|
+
| :--------------- | :-------------------------------------- | :-------------- | :----- |
|
|
132
|
+
| `component-vars` | 需要全局 provide 给子组件的默认属性配置 | `ComponentVars` | - |
|
|
36
133
|
|
|
37
|
-
|
|
38
|
-
| -------------- | ----------------- | ------------- | ------ |
|
|
39
|
-
| component-vars | 需要provide的配置 | ComponentVars | |
|
|
134
|
+
---
|
|
40
135
|
|
|
41
136
|
### 2. ProForm
|
|
42
137
|
|
|
43
|
-
|
|
138
|
+
基于 Ant Design Vue Form 深度封装的高级表单组件。
|
|
139
|
+
|
|
140
|
+
#### Props
|
|
44
141
|
|
|
45
|
-
|
|
142
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
143
|
+
| :----- | :-------------------------------------------------------- | :--------------------- | :------ |
|
|
144
|
+
| `form` | 由 `useForm` 返回的表单实例 | `Form` | - |
|
|
145
|
+
| `grid` | 是否启用栅格网格布局，支持传入 Grid 配置以配置自适应 | `boolean \| GridProps` | `false` |
|
|
146
|
+
| `...` | 其余属性均继承自 Ant Design Vue `a-form` 组件的原生 Props | `FormProps` | - |
|
|
46
147
|
|
|
47
|
-
|
|
48
|
-
- 需要表单字段的动态增减
|
|
49
|
-
- 需要统一表单布局和样式
|
|
148
|
+
#### Events & Methods
|
|
50
149
|
|
|
51
|
-
|
|
52
|
-
antd-vue-pro 导出了一个名为 `useForm` 的自定义 Hook，用于处理表单数据和字段配置， 配合`useForm` 可以更轻松地使用 ProForm。
|
|
53
|
-
:::
|
|
150
|
+
- 所有事件（如 `finish`, `finishFailed` 等）和方法（如 `validate`, `resetFields`）均与 Ant Design Vue `a-form` 组件完全继承，且能直接透传绑定。
|
|
54
151
|
|
|
55
|
-
|
|
152
|
+
---
|
|
56
153
|
|
|
57
|
-
|
|
154
|
+
### 3. ProTable
|
|
58
155
|
|
|
59
|
-
|
|
60
|
-
| ------ | --------------------------------------- | ----------------------------------------------------------------- | ------ |
|
|
61
|
-
| form | useForm 返回对象 | Form | - |
|
|
62
|
-
| grid | 是否启用栅格布局 | boolean \| [GridProps](https://antdv.com/components/grid-cn/#api) | - |
|
|
63
|
-
| ... | 继承 Ant Design Vue Form 组件的所有参数 | [FormProps](https://antdv.com/components/form-cn/#form) | - |
|
|
156
|
+
基于 Ant Design Vue Table 深度封装的高级表格组件，将搜索表单、列配置、分页高度集成。
|
|
64
157
|
|
|
65
|
-
|
|
158
|
+
#### Props
|
|
66
159
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
160
|
+
| 参数名 | 说明 | 类型 | 默认值 |
|
|
161
|
+
| :----------------- | :-------------------------------------------------------- | :------------------------------------- | :------ |
|
|
162
|
+
| `table` | 由 `useTable` 返回的表格实例 | `Table` | - |
|
|
163
|
+
| `search` | 触发表格查询的回调函数，需返回 Promise 或直接返回查询数据 | `(params: any) => Promise<any> \| any` | - |
|
|
164
|
+
| `addIndexColumn` | 是否自动在表格首列插入序号列 | `boolean` | `false` |
|
|
165
|
+
| `immediateSearch` | 表格挂载时（onMounted）是否立即触发一次 `search` 查询 | `boolean` | `false` |
|
|
166
|
+
| `control` | 是否在表格右上角工具栏中展示尺寸调节和列动态显示控制按钮 | `boolean` | `true` |
|
|
167
|
+
| `searchFormConfig` | 查询表单的布局配置参数 | `SearchFormConfig` | - |
|
|
168
|
+
| `tableContainer` | 表格的外部包裹容器，默认为 false | `Component \| false` | - |
|
|
169
|
+
| `...` | 其余参数继承自 Ant Design Vue `a-table` 的原生属性 | `TableProps` | - |
|
|
70
170
|
|
|
71
|
-
|
|
171
|
+
#### Slots
|
|
72
172
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
173
|
+
| 插槽名 | 说明 |
|
|
174
|
+
| :------------ | :------------------------------------------------- |
|
|
175
|
+
| `search-form` | 自定义搜索栏表单内容 |
|
|
176
|
+
| `button-bar` | 自定义操作按钮组区域（位于搜索栏下方，表格左上方） |
|
|
177
|
+
| `toolbar` | 自定义工具栏区域（位于表格右上方控制按钮旁） |
|
|
178
|
+
| `table` | 完全自定义渲染表格区域 |
|
|
76
179
|
|
|
77
|
-
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## ⚙️ 核心 Hooks 说明
|
|
183
|
+
|
|
184
|
+
### 1. `useForm`
|
|
185
|
+
|
|
186
|
+
用于创建表单管理对象，整合了表单数据、字段规则和 ref 控制。
|
|
187
|
+
|
|
188
|
+
#### 入参定义
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const form = useForm<D>(initFormData?, initFields?, root?)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- `initFormData`: 表单初始数据对象（`DeepPartial<D>`）
|
|
195
|
+
- `initFields`: 初始字段配置数组（`Field[]`）
|
|
196
|
+
- `root`: 是否创建根 Form 实例，默认为 `true`。若为 `false`，则内部会隐式 inject 父级表单上下文。
|
|
197
|
+
|
|
198
|
+
#### 返回值 (Form 实例)
|
|
199
|
+
|
|
200
|
+
| 属性/方法 | 说明 | 类型 |
|
|
201
|
+
| :----------------------------- | :---------------------------------------------------------------------------------- | :------------------------------- |
|
|
202
|
+
| `formData` | 响应式表单数据对象（**2.0+ 中由 reactive 包装**） | `Reactive<D>` |
|
|
203
|
+
| `fields` | 响应式表单字段配置数组引用 | `Ref<Field[]>` |
|
|
204
|
+
| `formRef` | 底层 Ant Design Vue `a-form` 的 DOM/组件引用实例 | `Ref<FormInstance \| undefined>` |
|
|
205
|
+
| `getFormData(path)` | 安全获取指定字段路径（支持深层 'a.b'）的数据值 | `(path) => any` |
|
|
206
|
+
| `setFormData(path, val)` | 安全更新指定路径的值，支持批量对象或函数式更新 | `(path, val) => void` |
|
|
207
|
+
| `getField(path, opts?)` | 获取指定 path 的字段配置，支持查找函数定位，支持配置 `{ all: true }` 获取所有匹配项 | `(path, opts) => Field` |
|
|
208
|
+
| `setField(path, patch, opts?)` | 增量更新指定字段的配置参数（如改变 label、hidden 等），支持 merge 或 rewrite 更新 | `(path, patch, opts) => void` |
|
|
209
|
+
| `deleteField(path)` | 从当前配置数组中删除特定 path 的表单字段配置 | `(path) => void` |
|
|
210
|
+
| `appendField(path, field)` | 在特定的字段 path 后面，动态追加一个新的表单字段配置 | `(path, field) => void` |
|
|
211
|
+
| `prependField(path, field)` | 在特定的字段 path 前面，动态插入一个新的表单字段配置 | `(path, field) => void` |
|
|
212
|
+
| `getParentField(path)` | 查找获取当前子字段的父级配置项，一级字段返回虚拟根容器 | `(path) => Field` |
|
|
213
|
+
|
|
214
|
+
---
|
|
78
215
|
|
|
79
|
-
|
|
216
|
+
### 2. `useTable`
|
|
80
217
|
|
|
81
|
-
|
|
218
|
+
用于创建和管理表格实例，内置集成了列配置操作与搜索表单组件。
|
|
82
219
|
|
|
83
|
-
|
|
84
|
-
- 需要集成搜索表单和工具栏
|
|
85
|
-
- 需要统一表格布局和样式
|
|
220
|
+
#### 入参参数
|
|
86
221
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
222
|
+
```ts
|
|
223
|
+
const table = useTable<D, T>({
|
|
224
|
+
columns: [], // 初始列配置
|
|
225
|
+
dataSource: [], // 静态初始数据源
|
|
226
|
+
pageParam: {}, // 分页参数配置
|
|
227
|
+
searchParam: {}, // 搜索栏初始数据
|
|
228
|
+
searchFields: [], // 搜索栏字段 Schema 配置
|
|
229
|
+
});
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
#### 返回值 (Table 实例)
|
|
233
|
+
|
|
234
|
+
| 属性/方法 | 说明 | 类型 |
|
|
235
|
+
| :------------------------ | :-------------------------------------------------------- | :--------------------- |
|
|
236
|
+
| `columns` | 响应式表格列配置数组 | `Ref<Column[]>` |
|
|
237
|
+
| `dataSource` | 响应式表格列表数据源 | `Ref<T[]>` |
|
|
238
|
+
| `pageParam` | 响应式分页参数对象（包含 `current`, `pageSize`, `total`） | `Reactive<PageParam>` |
|
|
239
|
+
| `searchForm` | 搜索栏表单关联的 `useForm` 实例，提供完美的表单操作 API | `Form<D>` |
|
|
240
|
+
| `setColumn(key, patch)` | 合并或重置修改指定 key 的列配置属性（如 width、title 等） | `(key, patch) => void` |
|
|
241
|
+
| `deleteColumn(key)` | 动态移除某一个指定 key 对应的表格列配置 | `(key) => void` |
|
|
242
|
+
| `appendColumn(key, col)` | 在某一个列的后方动态追加配置列 | `(key, col) => void` |
|
|
243
|
+
| `prependColumn(key, col)` | 在某一个列的前方动态插入配置列 | `(key, col) => void` |
|
|
244
|
+
| `setPageParam(param)` | 增量设置当前分页参数值，支持传入对象或更新函数 | `(param) => void` |
|
|
245
|
+
| `resetQueryParams()` | 重置搜索参数，并恢复分页至第 1 页 | `() => void` |
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## 📄 字段配置（`Field`）详解
|
|
250
|
+
|
|
251
|
+
在进行表单 Schema 编写时，`Field` 数组中的每一项都支持以下属性定义：
|
|
252
|
+
|
|
253
|
+
### 公共基础属性
|
|
254
|
+
|
|
255
|
+
| 属性名 | 说明 | 类型 | 默认值 |
|
|
256
|
+
| :------------------- | :---------------------------------------------------------------------------- | :---------------------------- | :-------- |
|
|
257
|
+
| `path` | 字段标识，需对应数据对象 `formData` 的 key，支持多级嵌套，例如 `address.city` | `string` | - |
|
|
258
|
+
| `label` | 字段中文标签，支持字符串或直接传入 VNode 组件进行自定义 | `string \| Component \| Slot` | - |
|
|
259
|
+
| `component` | 调用的表单项组件的类型，支持内置类型键名或直接传入自定义 Vue 组件 | `string \| Component` | `'input'` |
|
|
260
|
+
| `hidden` | 字段是否被隐藏（在 DOM 中彻底不渲染，但数据保留），支持 Ref/Computed 响应式 | `boolean \| Ref<boolean>` | `false` |
|
|
261
|
+
| `disabled` | 组件的禁用状态，支持 Ref/Computed 响应式 | `boolean \| Ref<boolean>` | `false` |
|
|
262
|
+
| `rules` | 字段数据校验规则，遵循 ant-design-vue Form 校验格式 | `Rule[]` | - |
|
|
263
|
+
| `span` | 栅格占位宽度（在 ProForm 开启 `grid` 网格布局后有效） | `number` | - |
|
|
264
|
+
| `formItemStyle` | 挂载在外部 `a-form-item` 节点上的额外 CSS 样式属性 | `CSSProperties` | - |
|
|
265
|
+
| `formItemClass` | 挂载在外部 `a-form-item` 节点上的自定义类名 | `string` | - |
|
|
266
|
+
| `formItemContainer` | 针对该表单项的最外层 DOM 包裹组件 | `Component` | - |
|
|
267
|
+
| `formItemDataAttrs` | 附加在 `a-form-item` DOM 节点上的自定义 data 属性 | `Record<string, string>` | - |
|
|
268
|
+
| `componentStyle` | 直接传递给内部表单输入组件的额外 CSS 样式属性 | `CSSProperties` | - |
|
|
269
|
+
| `componentClass` | 直接传递给内部表单输入组件的自定义类名 | `string` | - |
|
|
270
|
+
| `componentContainer` | 针对表单输入组件的包裹组件（位于 FormItem 与组件之间） | `Component` | - |
|
|
271
|
+
| `componentDataAttrs` | 附加在内部输入组件 DOM 节点上的自定义 data 属性 | `Record<string, string>` | - |
|
|
272
|
+
| `slots` | 该表单项的插槽自定义内容，包含 formItem 插槽或组件插槽 | `Record<string, Slot>` | - |
|
|
273
|
+
| `valueFormatter` | 字段值转换处理器，可在输入更新或提取数据时做 get/set 转换 | `ValueFormatter` | - |
|
|
274
|
+
| `modelProp` | 双向绑定的数据属性名称（当使用自定义组件且非 value 绑定时） | `string` | `'value'` |
|
|
275
|
+
| `fields` | 嵌套子表单项的 Schema 数组配置（用于分组或复杂嵌套表单） | `Field[]` | - |
|
|
276
|
+
| `grid` | 针对当前嵌套子表单项所使用的网格布局参数（仅当有 `fields` 时有效） | `boolean \| GridProps` | - |
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
### 内置组件映射（`component` 可选值）
|
|
281
|
+
|
|
282
|
+
组件库默认封装了 Ant Design Vue 的高频交互组件，您可以在 `component` 属性中填入以下预设键名来自动调用：
|
|
283
|
+
|
|
284
|
+
| 内置键名 | 渲染对应的 Ant Design Vue 组件 |
|
|
285
|
+
| :----------------- | :------------------------------ |
|
|
286
|
+
| `'input'` | `a-input` 文本输入框 |
|
|
287
|
+
| `'textarea'` | `a-textarea` 文本域 |
|
|
288
|
+
| `'input-search'` | `a-input-search` 搜索输入框 |
|
|
289
|
+
| `'input-password'` | `a-input-password` 密码框 |
|
|
290
|
+
| `'input-number'` | `a-input-number` 数字输入框 |
|
|
291
|
+
| `'select'` | `a-select` 下拉选择器 |
|
|
292
|
+
| `'cascader'` | `a-cascader` 级联选择器 |
|
|
293
|
+
| `'date-picker'` | `a-date-picker` 日期选择器 |
|
|
294
|
+
| `'range-picker'` | `a-range-picker` 日期范围选择器 |
|
|
295
|
+
| `'time-picker'` | `a-time-picker` 时间选择器 |
|
|
296
|
+
| `'checkbox-group'` | `a-checkbox-group` 复选框组 |
|
|
297
|
+
| `'radio-group'` | `a-radio-group` 单选按钮组 |
|
|
298
|
+
| `'switch'` | `a-switch` 开关切换器 |
|
|
299
|
+
| `'slider'` | `a-slider` 滑动条 |
|
|
300
|
+
| `'tree-select'` | `a-tree-select` 树形选择器 |
|
|
301
|
+
| `'transfer'` | `a-transfer` 穿梭框 |
|
|
302
|
+
| `'custom'` | 完全渲染自定义组件 |
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
### 🧩 扩充注册您的自定义组件
|
|
307
|
+
|
|
308
|
+
#### 步骤 1：利用 ComponentProvider 全局注册
|
|
309
|
+
|
|
310
|
+
```vue
|
|
311
|
+
<script setup lang="ts">
|
|
312
|
+
import { ProComponentProvider } from '@qin-ui/antd-vue-pro';
|
|
313
|
+
import MyRichTextEditor from './components/MyRichTextEditor.vue';
|
|
90
314
|
|
|
91
|
-
|
|
315
|
+
const componentMap = {
|
|
316
|
+
'rich-editor': MyRichTextEditor,
|
|
317
|
+
};
|
|
318
|
+
</script>
|
|
319
|
+
|
|
320
|
+
<template>
|
|
321
|
+
<ProComponentProvider :component-map="componentMap">
|
|
322
|
+
<AppLayout />
|
|
323
|
+
</ProComponentProvider>
|
|
324
|
+
</template>
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
#### 步骤 2：追加 TypeScript 全局声明获取强类型补全
|
|
328
|
+
|
|
329
|
+
在项目任意 `.d.ts` 类型文件中写入以下代码：
|
|
330
|
+
|
|
331
|
+
```ts
|
|
332
|
+
declare module '@qin-ui/antd-vue-pro' {
|
|
333
|
+
interface ComponentMap {
|
|
334
|
+
'rich-editor': typeof MyRichTextEditor;
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
现在，您在表单配置中写入 `component: 'rich-editor'` 时，将自动获得精准的属性类型联想与校验！
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Peer Dependencies
|
|
344
|
+
|
|
345
|
+
| 依赖包名称 | 推荐版本要求 |
|
|
346
|
+
| :--------------- | :----------- |
|
|
347
|
+
| `vue` | `^3.5.0` |
|
|
348
|
+
| `ant-design-vue` | `^4.0.0` |
|
|
349
|
+
|
|
350
|
+
---
|
|
92
351
|
|
|
93
|
-
|
|
352
|
+
## 🤝 贡献与反馈
|
|
94
353
|
|
|
95
|
-
|
|
96
|
-
| ---------------- | --------------------------------------------------------- | -------------------------------------------------------- | ------ |
|
|
97
|
-
| table | useTable返回对象 | Object | - |
|
|
98
|
-
| search | 表格数据查询获取方法 | Function | - |
|
|
99
|
-
| addIndexColumn | 是否添加索引列 | boolean | - |
|
|
100
|
-
| immediateSearch | onMounted 时立即触发一次search事件 | boolean | - |
|
|
101
|
-
| control | 是否展示表格 size 和 column 控制按钮 | boolean | - |
|
|
102
|
-
| searchFormConfig | 索栏查询字段表单配置 | Object | - |
|
|
103
|
-
| tableContainer | 表格容器包裹组件，会渲染在Table的外层，需要有default slot | Component | - |
|
|
104
|
-
| ... | 继承 Ant Design Vue Table 组件的所有参数 | [TableProps](https://antdv.com/components/table-cn/#api) | - |
|
|
354
|
+
欢迎在任何时候通过 [GitHub Issues](https://github.com/dufan3715/pro-components/issues) 提交对本子包的优化建议和反馈。
|
|
105
355
|
|
|
106
|
-
|
|
356
|
+
## 📄 开源许可证
|
|
107
357
|
|
|
108
|
-
|
|
109
|
-
| ----------- | -------------- |
|
|
110
|
-
| search-form | 自定义搜索表单 |
|
|
111
|
-
| button-bar | 自定义按钮组 |
|
|
112
|
-
| toolbar | 自定义工具栏 |
|
|
113
|
-
| table | 自定义表格 |
|
|
358
|
+
基于 [MIT](LICENSE) 开源许可证。
|