Blame view

ant-design-vue-jeecg/src/components/jeecg/README_JEditableTable.md 26.6 KB
肖超群 authored
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# JEditableTable 帮助文档

## 参数配置

| 参数         | 类型    | 必填 | 说明                                                                            |
|--------------|---------|------|---------------------------------------------------------------------------------|
| columns      | array   | ✔️    | 表格列的配置描述,具体项见下表                                                  |
| dataSource   | array   | ✔️    | 表格数据                                                                        |
| loading      | boolean |      | 是否正在加载,加载中不会显示任何行,默认false                                   |
| actionButton | boolean |      | 是否显示操作按钮,包括"新增"、"删除",默认false                                 |
| rowNumber    | boolean |      | 是否显示行号,默认false                                                         |
| rowSelection | boolean |      | 是否可选择行,默认false                                                         |
| dragSort     | boolean |      | 是否可拖动排序,默认false                                                       |
| dragSortKey  | string  |      | 拖动排序存储的Key,无需定义在columns内也能在getValues()时获取到值,默认orderNum |
| maxHeight    | number  |      | 设定最大高度(px),默认400                                                       |
| disabledRows | object  |      | 设定禁用的行,被禁用的行无法被选择和编辑,配置方法可以查看示例                  |
| disabled     | boolean |      | 是否禁用所有行,默认false                                                       |

### columns 参数详解

| 参数          | 类型    | 必填 | 说明                                                                                                                                                   |
|---------------|---------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| title         | string  | ✔️    | 表格列头显示的问题                                                                                                                                     |
| key           | string  | ✔️    | 列数据在数据项中对应的 key,必须是唯一的                                                                                                               |
| type          | string  | ✔️    | 表单的类型,可以通过`JEditableTableUtil.FormTypes`赋值                                                                                                 |
| width         | string  |      | 列的宽度,可以是百分比,也可以是`px`或其他单位,建议设置为百分比,且每一列的宽度加起来不应超过100%,否则可能会不能达到预期的效果。留空会自动计算百分比 |
| placeholder   | string  |      | 表单预期值的提示信息,可以使用`${...}`变量替换文本(详见`${...} 变量使用方式`)                                                                        |
| defaultValue  | string  |      | 默认值,在新增一行时生效                                                                                                                               |
| validateRules | array   |      | 表单验证规则,配置方式见[validateRules 配置规则](#validaterules-配置规则)                                                                              |
| props         | object  |      | 设置添加给表单元素的自定义属性,例如:`props:{title: 'show title'}`                                                                                     |
| disabled      | boolean |      | 是否禁用当前列,默认false                                                                                                                              |

#### 当 type=checkbox 时所需的参数

| 参数           | 类型    | 必填 | 说明                                                                                                                                                                                                   |
|----------------|---------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| defaultChecked | boolean |      | 默认值是否选中                                                                                                                                                                                         |
| customValue    | array   |      | 自定义值,checkbox需要的是boolean值,如果数据是其他值(例如`'Y' or 'N'`)时,就会导致错误,所以提供了该属性进行转换,例:`customValue: ['Y','N']`,会将`true`转换为`'Y'`,`false`转换为`'N'`,反之亦然 |

#### 当 type=select 时所需的参数

| 参数       | 类型    | 必填 | 说明                                               |
|------------|---------|------|----------------------------------------------------|
| options    | array   | ✔️    | 下拉选项列表,详见下表                             |
| allowInput | boolean |      | 是否允许用户输入内容,并创建新的内容               |
| dictCode   | String  |      | 数据字典Code,若options也有值,则拼接在options后面 |

##### options 所需参数

| 参数      | 类型       | 必填 | 说明                                                                 |
|-----------|------------|------|----------------------------------------------------------------------|
| text      | string     | ✔️    | 显示标题                                                             |
| value     | string     | ✔️    | 真实值                                                               |
| ~~title~~ | ~~string~~ |      | ~~显示标题(已废弃,若同时填写了 title 和 text 那么优先使用 text)~~ |

#### 当 type=upload 时所需的参数

| 参数         | 类型    | 必填 | 说明                                                                                 |
|--------------|---------|------|--------------------------------------------------------------------------------------|
| action       | string  | ✔️    | 上传文件路径                                                                         |
| token        | boolean |      | 上传的时候是否传递token                                                              |
| responseName | string  | ✔️    | 若要从上传成功后从response中取出返回的文件名,那么这里填后台返回的包含文件名的字段名 |

#### 当 type=slot 时所需的参数

| 参数     | 类型   | 必填 | 说明       |
|----------|--------|------|------------|
| slotName | string | ✔️    | slot的名称 |

### validateRules 配置规则

`validateRules` 需要的是一个数组,数组里每项都是一个规则,规则是object类型,规则的各个参数如下

- `required` 是否必填,可选值为`true`or`false`
- `pattern` 正则表达式验证,只有成功匹配该正则的值才能成功通过验证
- `handler` 自定义函数校验,使用方法请见[示例五](#示例五)
- `message` 当验证未通过时显示的提示文本,可以使用`${...}`变量替换文本(详见`${...} 变量使用方式`
- 配置示例请看[示例二](#示例二)

## 事件

| 事件名          | 触发时机                                           | 参数                                             |
|-----------------|----------------------------------------------------|--------------------------------------------------|
| added           | 当添加行操作完成后触发                             |                                                  |
| deleted         | 当删除行操作完成后触发(批量删除操作只会触发一次) | `deleteIds` 被逻辑删除的id                       |
| selectRowChange | 当行被选中或取消选中时触发                         | `selectedRowIds` 被选中行的id                    |
| valueChange     | 当数据发生改变的时候触发的事件                     | `{ type, row, column, value, target }` Event对象 |

## 方法

关于方法的如何调用的问题,请在**FAQ**中查看[方法如何调用](#方法如何调用)

### initialize

用于初始化表格(清空表格)

- `参数:`
- `返回值:`

### resetScrollTop

重置滚动条Top位置

- `参数:`

| 参数名 | 类型   | 必填 | 说明                                                                                                   |
|--------|--------|------|--------------------------------------------------------------------------------------------------------|
| top    | number |      | 新top位置,留空则滚动到上次记录的位置,用于解决切换tab选项卡时导致白屏以及自动将滚动条滚动到顶部的问题 |

- `返回值:`

### add

主动添加行,默认情况下,当用户的滚动条已经在底部的时候,会将滚动条固定在底部,即添加后无需用户手动滚动,而会自动滚动到底部

- `参数:`

| 参数名              | 类型    | 必填 | 说明                                                                |
|---------------------|---------|------|---------------------------------------------------------------------|
| num                 | number  |      | 添加几行,默认为1                                                   |
| forceScrollToBottom | boolean |      | 是否在添加后无论用户的滚动条在什么位置都强制滚动到底部,默认为false |

- `返回值:`

### removeRows

主动删除一行或多行

- `参数:`

| 参数名 | 类型            | 必填 | 说明                                                                                       |
|--------|-----------------|------|--------------------------------------------------------------------------------------------|
| id     | string 或 array | ✔️    | 被删除行的id。如果要删除一个,可以直接传id,如果要删除多个,需要将多个id封装成一个数组传入 |

- `返回值:`

### removeSelectedRows

主动删除被选中的行

- `参数:`
- `返回值:`

### getValues

用于获取表格里所有表单的值,可进行表单验证

- `参数:`

| 参数名   | 类型     | 必填 | 说明                                                                                                                                                      |
|----------|----------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| callback | function | ✔️    | 获取值的回调方法,会传入`error`和`values`两个参数。`error`:未通过验证的数量,当等于`0`时代表验证通过;`values`:获取的值(即使未通过验证该字段也有数据) |
| validate | boolean  |      | 是否进行表单验证,默认为`true`,设为`false`则代表忽略表单验证                                                                                             |
| rowIds   | array    |      | 默认返回所有行的数据,如果传入了`rowIds`,那么就会只返回与该`rowIds`相匹配的数据,如果没有匹配的数据,就会返回空数组                                      |

- `返回值:`

### getValuesSync

`getValues`的同步版,会直接将获取到的数据返回
肖超群 authored
162
- `参数:`
肖超群 authored
163
164
165
166
167

| 参数名  | 类型   | 必填 | 说明                   |
|---------|--------|------|------------------------|
| options | object |      | 选项,详见下方所需参数 |
肖超群 authored
168
169
-
  - `options` 所需参数
肖超群 authored
170
171
172
173
174
175
176

| 参数名   | 类型    | 必填 | 说明                                                                                                                 |
|----------|---------|------|----------------------------------------------------------------------------------------------------------------------|
| validate | boolean |      | 是否进行表单验证,默认为`true`,设为`false`则代表忽略表单验证                                                        |
| rowIds   | array   |      | 默认返回所有行的数据,如果传入了`rowIds`,那么就会只返回与该`rowIds`相匹配的数据,如果没有匹配的数据,就会返回空数组 |

- `返回值:` object
肖超群 authored
177
178
  - `error` 未通过验证的数量,当等于`0`时代表验证通过
  - `values` 获取的值(即使未通过验证该字段也有数据)
肖超群 authored
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212

- `使用示例`

```js
let { error, values } = this.$refs.editableTable.getValuesSync({ validate: true, rowIds: ['rowId1', 'rowId2'] })
if (error === 0) {
    console.log('表单验证通过,数据:', values);
} else {
    console.log('未通过表单验证,数据:', values);
}
```

### getValuesPromise

`getValues`的promise版,会在`resolve`中传入获取到的值,会在`reject`中传入失败原因,例如`VALIDATE_NO_PASSED`

- `参数:`

| 参数名   | 类型    | 必填 | 说明                                                                                                                 |
|----------|---------|------|----------------------------------------------------------------------------------------------------------------------|
| validate | boolean |      | 同`getValues`的`validate`参数                                                                                        |
| rowIds   | array   |      | 默认返回所有行的数据,如果传入了`rowIds`,那么就会只返回与该`rowIds`相匹配的数据,如果没有匹配的数据,就会返回空数组 |

- `返回值:` Promise

### getDeleteIds

用于获取被逻辑删除的行的id,返回一个数组,用户可将该数组传入后台,并进行批量删除

- `参数:`
- `返回值:` array

### getAll
肖超群 authored
213
获取所有的数据,包括values、deleteIds 会在`resolve`中传入获取到的值:`{values, deleteIds}`
肖超群 authored
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
会在`reject`中传入失败原因,例如`VALIDATE_NO_PASSED`

- `参数:`

| 参数名   | 类型    | 必填 | 说明                          |
|----------|---------|------|-------------------------------|
| validate | boolean |      | 同`getValues`的`validate`参数 |

- `返回值:` Promise

### setValues

主动设置表格中某行某列的值

- `参数:`

| 参数名 | 类型  | 必填 | 说明                                                       |
|--------|-------|------|------------------------------------------------------------|
| values | array |      | 传入一个数组,数组中的每项都是一行的新值,具体见下面的示例 |

- `返回值:`
- `示例:`

```js
setValues([
    {
        rowKey: id1, // 行的id
        values: { // 在这里 values 中的 name 是你 columns 中配置的 key
            'name': 'zhangsan',
            'age': '20'
        }
    },
    {
        rowKey: id2,
        values: {
            'name': 'lisi',
            'age': '23'
        }
    }
])
```
肖超群 authored
255
肖超群 authored
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
### clearSelection

主动清空选择的行

- `参数:`
- `返回值:`

## 内置插槽

| 插槽名       | 说明                                                 |
|--------------|------------------------------------------------------|
| buttonBefore | 在操作按钮的**前面**插入插槽,不受`actionButton`属性的影响 |
| buttonAfter  | 在操作按钮的**后面**插入插槽,不受`actionButton`属性的影响 |

## ${...} 变量使用方式
肖超群 authored
272
273
`placeholder`和`message`这两个属性中可以使用`${...}`变量来替换文本 在[示例二](#示例二)中,配置了`title`为`名称`的一列,而`placeholder`配置成了`请输入${title}`
,那么最终显示效果为`请输入名称`
肖超群 authored
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
这就是`${...}`变量的使用方式,在`${}`中可以使用的变量有`title`、`key`、`defaultValue`这三个属性的值

## JEditableTableUtil 使用说明

在之前配置`columns`时提到过`JEditableTableUtil`这个工具类,那么如果想要知道详细的使用说明就请看这里

### export 的常量

#### FormTypes

这是配置`columns.type`时用到的常量值,其中包括

- `normal` 默认,直接显示值,不渲染表单
- `input` 显示输入框
- `inputNumber` 显示数字输入框
- `checkbox` 显示多选框
- `select` 显示选择器(下拉框)
- `date` 日期选择器
- `datetime` 日期时间选择器
- `upload` 上传组件(文件域)
- `slot` 自定义插槽

### VALIDATE_NO_PASSED

在判断表单验证是否通过时使用,如果 reject 的值 === VALIDATE_NO_PASSED 则代表表单验证未通过,你可以做相应的其他处理,反之则可能是发生了报错,可以使用 `console.error` 输出

### 封装的方法

#### validateTables

当你的页面中存在多个JEditableTable实例的时候,如果要获取每个实例的值、判断表单验证是否通过,就会让代码变得极其冗余、繁琐,于是我们就将该操作封装成了一个函数供你调用,它可以同时获取并验证多个JEditableTable实例的值,只有当所有实例的表单验证都通过后才会返回值,否则将会告诉你具体哪个实例没有通过验证。具体使用方法请看下面的示例

- `参数:`

| 参数名 | 类型  | 必填 | 说明                                                   |
|--------|-------|------|--------------------------------------------------------|
| cases  | array |      | 传入一个数组,数组中的每项都是一个JEditableTable的实例 |

- `返回值:` Promise
- `示例:`

```js
import { validateTables, VALIDATE_NO_PASSED } from '@/utils/JEditableTableUtil'
// 封装cases
let cases = []
cases.push(this.$refs.editableTable1)
cases.push(this.$refs.editableTable2)
cases.push(this.$refs.editableTable3)
cases.push(this.$refs.editableTable4)
cases.push(this.$refs.editableTable5)
// 同时验证并获取多个实例的值
validateTables(cases).then((all) => {
    // all 是一个数组,每项都对应传入cases的下标,包含values和deleteIds
    console.log('所有实例的值:', all)
}).catch((e = {}) => {
    // 判断表单验证是否未通过
    if (e.error === VALIDATE_NO_PASSED) {
        console.log('未通过验证的实例下标:', e.index)
    } else {
        console.error('发生异常:', e)
    }
})
```

## FAQ

### 方法如何调用?

[示例一](#示例一)中,设定了一个 `ref="editableTable"` 的属性,那么在vue中就可以使用`this.$refs.editableTable`获取到该表格的实例,并调取其中的方法。
假如我要调取`initialize`方法,就可以这么写:`this.$refs.editableTable.initialize()`

### 如何获取表单的值?

使用`getValue`方法进行获取,详见[示例三](#示例三)

### 如何进行表单验证?

在获取值的时候默认会进行表单验证操作,用户在输入的时候也会对正在输入的表单进行验证,只要配置好规则就可以了

### 如何添加或删除一行?

该功能已封装到组件中,你只需要将 `actionButton` 设置为 `true` 即可,当然你也可以在代码中主动调用新增方法或修改,具体见上方的方法介绍。

### 为什么使用了ATab组件后,切换选项卡会导致白屏或滚动条位置会归零?
肖超群 authored
359
360
在ATab组件中确实会导致滚动条位置归零,且不会触发`onscroll`方法,所以无法动态加载行,导致白屏的问题出现。 解决方法是在ATab组件的`onChange`事件触发时执行实例提供的`resetScrollTop()`
方法即可,但是需要注意的是:代码主动改变ATab的`activeKey`不会触发`onChange`事件,还需要你手动调用下。
肖超群 authored
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577

- `示例`

```html
<template>
    <a-tabs @change="handleChangeTab">
        <a-tab-pane tab="表格1" :forceRender="true" key="1">
            <j-editable-table
                ref="editableTable1"
                :loading="tab1.loading"
                :columns="tab1.columns"
                :dataSource="tab1.dataSource"/>
        </a-tab-pane>
        <a-tab-pane tab="表格2" :forceRender="true" key="2">
            <j-editable-table
                ref="editableTable2"
                :loading="tab2.loading"
                :columns="tab2.columns"
                :dataSource="tab2.dataSource"/>
        </a-tab-pane>
    </a-tabs>
</template>
```

```js
/*--- 忽略部分代码片段 ---*/
methods: {

      /** 切换tab选项卡的时候重置editableTable的滚动条状态 */
      handleChangeTab(key) {
        this.$refs[`editableTable${key}`].resetScrollTop()
      }

}
/*--- 忽略部分代码片段 ---*/
```

### slot(自定义插槽)如何使用?

代码示例请看:[示例四(slot)](#示例四(slot))

----------------------------------------------------------------------------------------

## 示例一

```html
<j-editable-table
    ref="editableTable"
    :loading="loading"
    :columns="columns"
    :dataSource="dataSource"
    :rowNumber="true"
    :rowSelection="true"
    :actionButton="true"
    style="margin-top: 8px;"
    @selectRowChange="handleSelectRowChange"/>
```

## 示例二

```js

import { FormTypes } from '@/utils/JEditableTableUtil'

/*--- 忽略部分代码片断 ---*/
columns: [
    {
        title: '名称',
        key: 'name',
        type: FormTypes.input,
        placeholder: '请输入${title}',
        defaultValue: '称名',
        // 表单验证规则
        validateRules: [
            {
                required: true, // 必填
                message: '${title}不能为空' // 提示的文本
            },
            {
                pattern: /^[a-z|A-Z][a-z|A-Z\d_-]{0,}$/, // 正则
                message: '${title}必须以字母开头,可包含数字、下划线、横杠'
            }
        ]
    },
    {
        title: '年龄',
        key: 'age',
        type: FormTypes.inputNumber,
        placeholder: '请输入${title}',
        defaultValue: 18,
        validateRules: [{required: true, message: '${title}不能为空'}]
    }
]
/*--- 忽略部分代码片断 ---*/
```

## 示例三

```js
// 获取被逻辑删除的字段id
let deleteIds = this.$refs.editableTable.getDeleteIds();
// 获取所有表单的值,并进行验证
this.$refs.editableTable.getValues((error, values) => {
    // 错误数 = 0 则代表验证通过
    if (error === 0) {
        this.$message.success('验证通过')
        // 将通过后的数组提交到后台或自行进行其他处理
        console.log(deleteIds, values)
    } else {
        this.$message.error('验证未通过')
    }
})
```

## 示例四(slot)

```html
<template>
    <j-editable-table :columns="columns" :dataSource="dataSource">
        <!-- 定义插槽 -->
        <!-- 这种定义插槽的写法是vue推荐的新版写法(https://cn.vuejs.org/v2/guide/components-slots.html#具名插槽),旧版已被废弃的写法不再支持 -->
        <!-- 若webstorm这样写报错,请看这篇文章:https://blog.csdn.net/lxq_9532/article/details/81870651 -->
        <template v-slot:action="props">
            <a @click="handleDelete(props)">删除</a>
        </template>
    </j-editable-table>
</template>
<script>
    import { FormTypes } from '@/utils/JEditableTableUtil'
    import JEditableTable from '@/components/jeecg/JEditableTable'
    export default {
        components: { JEditableTable },
        data() {
            return {
                columns: [
                    // ...
                    {
                        title: '操作',
                        key: 'action',
                        width: '8%',
                        type: FormTypes.slot, // 定义该列为 自定义插值列 
                        slotName: 'action' // slot 的名称,对应 v-slot 冒号后面和等号前面的内容
                    }
                ]
            }
        },
        methods: {
            /* a 标签的点击事件,删除当前选中的行 */
            handleDelete(props) {
                // 参数解释
                // props.index :当前行的下标
                // props.text :当前值,可能是defaultValue定义的值,也可能是从dataSource中取出的值
                // props.rowId :当前选中行的id,如果是新增行则是临时id
                // props.column :当前操作的列
                // props.getValue :这是一个function,执行后可以获取当前行的所有值(禁止在template中使用)
                //                  例:const value = props.getValue()
                // props.target :触发当前事件的实例,可直接调用该实例内的方法(禁止在template中使用)
                //                  例:target.add()

                // 使用实例:删除当前操作的行
                let { rowId, target } = props
                target.removeRows(rowId)
            }
        }
    }
</script>
```

## 示例五

```js
// 该示例是自定义函数校验
columns: [
    {
        title: '字段名称',
        key: 'dbFieldName',
        type: FormTypes.input,
        defaultValue: '',
        validateRules: [
            {
                // 自定义函数校验 handler
                handler(type, value, row, column, callback, target) {
                    // type 触发校验的类型(input、change、blur)
                    // value 当前校验的值
                    // callback(flag, message) 方法必须执行且只能执行一次
                    //          flag = 是否通过了校验,不填写或者填写 null 代表不进行任何操作
                    //          message = 提示的类型,默认使用配置的 message
                    // target 行编辑的实例对象

                    if (type === 'blur') {

                        if (value === 'abc') {
                            callback(false, '${title}不能是abc') // false = 未通过,可以跟自定义提示
                            return
                        }

                        let { values } = target.getValuesSync({ validate: false })
                        let count = 0
                        for (let val of values) {
                            if (val['dbFieldName'] === value) {
                                if (++count >= 2) {
                                    callback(false, '${title}不能重复')
                                    return
                                }
                            }
                        }
                        callback(true) // true = 通过验证
                    } else {
                        callback() // 不填写或者填写 null 代表不进行任何操作
                    }
                },
                message: '${title}默认提示'
            }
        ]
    },
]
```