Ame's blog
Ame
2022-02-13

el-lists

列表式、清单型数据展示组件，相比表格展示el-table-ts (opens new window)会更突出某一系列数据

# 特性

  1. 传递 data 和 column 两个必要属性即可渲染出列表。
  2. 支持 slot / jsx(参考 babel-plugin-transform-vue-jsx (opens new window)) / h 函数三种方式自定义渲染列项标题，列项数据。
  3. 可同级渲染列，并支持展开/关闭，使得同类数据归纳更便捷。
  4. 集成 el-pagination 分页组件，并扩展插槽，自定义分页渲染更便捷。
  5. 完善的类型声明，可完美运行在 ts 项目中。

# 安装和引入

安装

npm install el-lists -S
1

引入

该组件强依赖于 element-ui，请确保使用该组件前已引入

import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

import ElLists from 'el-lists'
import 'el-lists/dist/el-lists.css'

Vue.use(ElementUI)
Vue.use(ElLists)
1
2
3
4
5
6
7
8

# 阅前约定

列由多个列项组成，列项由列项标题、列项数据（列项值）组成

例如 姓名(列项标题): 刘飞朋(列项数据)

图示

# 基础用法

data 和 columns 两个属性

data 定义表格数据，columns 定义列属性

该组件内置状态status、标题title，因此你需要在data对象数组中定义这两个属性的值，更多内置属性请查看

男性男性人员描述标题
姓名：刘小凡
性别：男
年龄：18
地址：江苏省 南京市
描述：180
女性女性人员描述标题
姓名：张如霞
性别：女
年龄：16
地址：江苏省 南京市
描述：160
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns" />
</template>

<script>
  const listData = [
    {
      name: '刘小凡',
      sex: '男',
      age: 18,
      address: '江苏省 南京市',
      desc: {
        height: 180,
      },
      status: '男性',
      title: '男性人员描述标题',
    },
    {
      name: '张如霞',
      sex: '女',
      age: 16,
      address: '江苏省 南京市',
      desc: {
        height: 160,
      },
      status: '女性',
      title: '女性人员描述标题',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
          { label: '年龄', prop: 'age' },
          { label: '地址', prop: 'address' },
          { label: '描述', prop: 'desc.height' },
        ],
      }
    },
  }
</script>
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
Expand Copy

# 定义列头数据

该组件内置了列标题title，列状态status，列状态描述statusType三种属性，如果你不指定，相应位置则什么都不渲染

statusType 的值也可为 css class(样式类名)，这时你可以自己写status的样式

我是成功类型状态我是成功类型标题
姓名：刘小凡
性别：男
年龄：18
我是失败类型状态我是失败类型标题
姓名：张如霞
性别：女
年龄：16
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns" />
</template>

<script>
  const listData = [
    {
      title: '我是成功类型标题',
      status: '我是成功类型状态',
      statusType: 'success',
      name: '刘小凡',
      sex: '男',
      age: 18,
    },
    {
      title: '我是失败类型标题',
      status: '我是失败类型状态',
      statusType: 'error',
      name: '张如霞',
      sex: '女',
      age: 16,
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
          { label: '年龄', prop: 'age' },
        ],
      }
    },
  }
</script>
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
Expand Copy

# 控制列项的显示与隐藏

使用columns对象中的hidden属性来控制列项的显示与隐藏，查看详情

我是成功类型状态我是成功类型标题
年龄：18
我是失败类型状态我是失败类型标题
年龄：16
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns" />
</template>

<script>
  const listData = [
    {
      title: '我是成功类型标题',
      status: '我是成功类型状态',
      statusType: 'success',
      name: '刘小凡',
      sex: '男',
      age: 18,
    },
    {
      title: '我是失败类型标题',
      status: '我是失败类型状态',
      statusType: 'error',
      name: '张如霞',
      sex: '女',
      age: 16,
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name', hidden: true },
          {
            label: '性别',
            prop: 'sex',
            hidden: (allData, cellData) => {
              console.log(allData, '这一行的所有数据')
              console.log(cellData, '列项数据')
              // true 隐藏，false 不隐藏
              return true
            },
          },
          { label: '年龄', prop: 'age' },
        ],
      }
    },
  }
</script>
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
Expand Copy

# 布局

el-lists 组件布局基于 element layout

通过组件的 layout 属性定义列表布局，layout 对象结构为{row, col}，分别对应Row Attributes (opens new window)，Col Attributes (opens new window)。

同时columns属性中也支持col属性定义单项布局，且优先级高于layout.col

男性男性人员描述标题
姓名：刘小凡
性别：男
年龄：18
地址：江苏省 南京市
描述：180
女性女性人员描述标题
姓名：张如霞
性别：女
年龄：16
地址：江苏省 南京市
描述：160
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns" :layout="layout" />
</template>

<script>
  const listData = [
    {
      name: '刘小凡',
      sex: '男',
      age: 18,
      address: '江苏省 南京市',
      desc: {
        height: 180,
      },
      status: '男性',
      title: '男性人员描述标题',
    },
    {
      name: '张如霞',
      sex: '女',
      age: 16,
      address: '江苏省 南京市',
      desc: {
        height: 160,
      },
      status: '女性',
      title: '女性人员描述标题',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
          { label: '年龄', prop: 'age' },
          {
            label: '地址',
            prop: 'address',
            col: { span: 24 },
          },
          { label: '描述', prop: 'desc.height' },
        ],
        // 以下为默认值
        layout: {
          row: {
            gutter: 20,
          },
          // 优先级低于columns列配置内的col配置项
          col: { span: 6 },
        },
      }
    },
  }
</script>
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
Expand Copy

# 内置 showTooltip

组件在数据超过其容器宽度时将会折叠数据text-overflow: ellipsis;，鼠标移入后将会激活一个 toolTip，将折叠的数据完全显示。

行配置项中，配置 showTooltip: false 将不激活 toolTip，但数据依旧被折叠

状态标题
显示：长长长长长长长长长长长长长长长长长长长长
不显示：长长长长长长长长长长长长长长长长长长长长
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns"></el-lists>
</template>

<script>
  const listData = [
    {
      title: '标题',
      status: '状态',
      fold: '长长长长长长长长长长长长长长长长长长长长',
      noFold: '长长长长长长长长长长长长长长长长长长长长',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '显示', prop: 'fold' },
          { label: '不显示', prop: 'noFold', showTooltip: false },
        ],
      }
    },
  }
</script>
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
Expand Copy

# 内置插槽

# left

列头左侧插槽（即 status，title 所在位置），只有在 status、title 都未指定，status、title 插槽都未指定的情况下才起作用，可获取的数据有该列所有的数据及**h**函数

使用方式参考：

#left="{data, h}" 或#left="row" 此时 row = {data, h}

我是插槽自定义的左侧内容：刘小凡
姓名：刘小凡
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #left="row">
      我是插槽自定义的左侧内容：{{ row.data.name }}
    </template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      name: '刘小凡',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [{ label: '姓名', prop: 'name' }],
      }
    },
  }
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Expand Copy

# status

列状态插槽，可获取的数据有该列所有的数据及**h**函数

使用方式参考：

#status="{data, h}" 或#status="row" 此时 row = {data, h}

我是插槽自定义的状态我不是插槽定义的标题
姓名：刘小凡
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #status="row">我是插槽自定义的{{ row.data.status }}</template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      title: '我不是插槽定义的标题',
      status: '状态',
      name: '刘小凡',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [{ label: '姓名', prop: 'name' }],
      }
    },
  }
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Expand Copy

# title

列标题插槽，可获取的数据有该列所有的数据及**h**函数

使用方式参考：

#title="{data, h}" 或#title="row" 此时 row = {data, h}

我不是插槽定义的状态我是插槽自定义的标题
姓名：刘小凡
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #title="row">我是插槽自定义的{{ row.data.title }}</template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      title: '标题',
      status: '我不是插槽定义的状态',
      name: '刘小凡',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [{ label: '姓名', prop: 'name' }],
      }
    },
  }
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Expand Copy

列头右侧插槽，可获取的数据有该列所有的数据及**h**函数

使用方式参考：

#right="{data, h}" 或#right="row" 此时 row = {data, h}

我不是插槽定义的状态我不是插槽定义的标题
自定义的右侧
姓名：刘小凡
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #right="row">自定义的右侧</template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      title: '我不是插槽定义的标题',
      status: '我不是插槽定义的状态',
      name: '刘小凡',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [{ label: '姓名', prop: 'name' }],
      }
    },
  }
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Expand Copy

# opera

列右侧操作区域插槽，可获取的数据有该列所有的数据及**h**函数

使用方式参考：

#opera="{data, h}" 或#opera="row" 此时 row = {data, h}

状态我不是插槽定义的标题
姓名：刘小凡
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #opera="row">
      <el-button type="primary" size="small" @click="handleOpera">
        跟{{ row.data.name }}结婚
      </el-button>
    </template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      title: '我不是插槽定义的标题',
      status: '状态',
      name: '刘小凡',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [{ label: '姓名', prop: 'name' }],
      }
    },
    methods: {
      handleOpera() {
        this.$message.success('这是一个美好的愿望')
      },
    },
  }
</script>
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
Expand Copy

# 自定义列-列项标题/列项值

支持 jsx/slot/h 函数三种方式的自定义渲染。 你可以在自定义渲染中获取到 {} 对象 slot 语法：可以在列属性scopedSlots.customRender的属性值设置为 slot 名称，然后在 template 模板中写 slot jsx/h 语法：可直接在列定义中设置customRender函数中返回 JSX（注意此时需要 jsx 支持），或者返回 h 函数生成的 VNode。

状态标题
姓名：刘小凡
性别：男
猜猜我的年龄：
刚满18岁
自定义地址标题：安徽省南京市
描述：180
状态标题
姓名：张如霞
性别：女
猜猜我的年龄：
刚满18岁
自定义地址标题：安徽省南京市
描述：160
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns">
    <template #handle>安徽省南京市</template>
    <template #handleTitle>自定义地址标题</template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      title: '标题',
      status: '状态',
      name: '刘小凡',
      sex: '男',
      age: 18,
      address: '江苏省 南京市',
      desc: {
        height: 180,
      },
    },
    {
      title: '标题',
      status: '状态',
      name: '张如霞',
      sex: '女',
      age: 16,
      address: '江苏省 南京市',
      desc: {
        height: 160,
      },
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
          {
            label: '年龄',
            prop: 'age',
            // 可以这样
            // customRender/customTitle都支持JSX、h函数
            customRender: () => {
              return <div>刚满18岁</div>
            },
            customTitle: () => {
              return '猜猜我的年龄'
            },
          },
          {
            label: '地址',
            prop: 'address',
            scopedSlots: {
              customRender: 'handle',
              customTitle: 'handleTitle',
            },
          },
          { label: '描述', prop: 'desc.height' },
        ],
      }
    },
    methods: {
      handleView({ name, age }) {
        this.$message.success(`${name} ${age}岁`)
      },
    },
  }
</script>
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
Expand Copy

# 折叠与展开

应用场景，同一标题下有相同的列表数据

可在定义列表数据时通过extra属性传入更多的数据

成年都是男性
名字：刘小凡
性别：男
成年都是女性
名字：刘艳
性别：女
  • 1
共 0 条
<template>
  <el-lists :data="list" :columns="columns" @expand="handleExpand"></el-lists>
</template>

<script>
  const listData = [
    {
      title: '都是男性',
      status: '成年',
      name: '刘小凡',
      sex: '男',
      extra: [
        {
          name: '刘凡',
          sex: '男',
        },
        {
          name: '刘小',
          sex: '男',
        },
      ],
    },
    {
      title: '都是女性',
      status: '成年',
      name: '刘艳',
      sex: '女',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '名字', prop: 'name' },
          { label: '性别', prop: 'sex' },
        ],
      }
    },
    methods: {
      handleExpand(expand) {
        console.log(expand, '展开折叠参数')
      },
    },
  }
</script>
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
Expand Copy

# scroll 事件

按下 F12(打开控制台)，滚动表格查看scroll事件

状态标题
姓名：刘小凡
性别：男
状态标题
姓名：张如霞
性别：女
状态标题
姓名：张如霞
性别：女
状态标题
姓名：张如霞
性别：女
  • 1
共 0 条
<template>
  <el-lists
    :data="list"
    :columns="columns"
    style="height: 350px"
    @scroll="handleScroll"
  />
</template>

<script>
  const listData = [
    {
      title: '标题',
      status: '状态',
      name: '刘小凡',
      sex: '男',
    },
    {
      title: '标题',
      status: '状态',
      name: '张如霞',
      sex: '女',
    },
    {
      title: '标题',
      status: '状态',
      name: '张如霞',
      sex: '女',
    },
    {
      title: '标题',
      status: '状态',
      name: '张如霞',
      sex: '女',
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
        ],
      }
    },
    methods: {
      handleScroll(e) {
        console.log(e)
      },
    },
  }
</script>
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
Expand Copy

# 集成 pagination

默认展示

分页器，参考 el-pagination 文档 (opens new window)，

默认分页配置为

const defPagination = {
  currentPage: 1,
  pageSizes: [10, 20, 30, 50],
  pageSize: 10,
  layout: 'prev, pager, next, sizes, total',
  background: true,
}
1
2
3
4
5
6
7

增加内置插槽,名为pagination（使用方法见下方代码示例），可访问到总数total,分页配置项config

注意

el-pagination 中的 current-change 事件改为 page-change

姓名：刘小凡
性别：男
年龄：18
地址：江苏省 南京市
描述：180
姓名：刘小凡
性别：男
年龄：18
地址：江苏省 南京市
描述：180
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 10
共 100 条
<template>
  <el-lists
    :data="list"
    :columns="columns"
    :pagination="{ layout: 'prev, pager, next', background: true }"
    :total="100"
    @page-change="handlePageChange"
  >
    <template #pagination="{ total, config }">
      <span>{{ total }}/第五页</span>
    </template>
  </el-lists>
</template>

<script>
  const listData = [
    {
      name: '刘小凡',
      sex: '男',
      age: 18,
      address: '江苏省 南京市',
      desc: {
        height: 180,
      },
    },
    {
      name: '刘小凡',
      sex: '男',
      age: 18,
      address: '江苏省 南京市',
      desc: {
        height: 180,
      },
    },
  ]
  export default {
    data() {
      return {
        list: listData,
        columns: [
          { label: '姓名', prop: 'name' },
          { label: '性别', prop: 'sex' },
          { label: '年龄', prop: 'age' },
          { label: '地址', prop: 'address' },
          { label: '描述', prop: 'desc.height' },
        ],
      }
    },
    methods: {
      handlePageChange({ pageSize, currentPage }) {
        console.log(pageSize, currentPage)
      },
    },
  }
</script>
<style>
  .el-pagination {
    margin-top: 10px;
    margin-left: -10px;
  }
</style>
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
Expand Copy

# API

# el-lists 属性

参数 类型 默认值 说明
data Array [] 列表数据
详细见data-attributes
columns Array [] column item 配置列表，
详细见columns-attributes
pagination Object|Boolean true |
{    currentPage: 1,
     pageSizes: [10, 20, 30, 50],
     pageSize: 10,
     layout: 'prev, pager, next, sizes, total',
     background: true
}		 翻页器配置，默认显示翻页器。
相关 api 可查看el-pagination (opens new window)
total Number 0 翻页器条数总数
layout Object {
row: {
gutter: 20,
},
// 优先级低于 columns 列配置内的 col 配置项
col: { span: 6 },
}		 整体的布局配置，基于element Layout 布局 (opens new window)

# el-lists 事件

事件名称 说明 说明
scroll el-lists 滚动事件 e
page-change currentPage 改变时会触发 { pageSize, currentPage }
size-change pageSize 改变时会触发 { pageSize, currentPage }
prev-click 用户点击上一页按钮改变当前页后触发 { pageSize, currentPage }
next-click 用户点击下一页按钮改变当前页后触发 { pageSize, currentPage }

# data Attributes 属性

以下属于内置属性

属性 类型 默认值 说明
title string
status string
statusType string 'wait'
内置的 statusType 值
’success‘ #00C1CE
‘error’ #FF637B
’warning‘ #EEC08E
‘wait’ #92A5FC
’back‘ #C0C4CC
’other‘ #FF9BAA

# columns Attributes 属性

属性 类型 默认值 说明
label String 列项名称
prop String 列项数据字段，支持多层对象嵌套，如 user.age
hidden Boolean |Function false 是否隐藏该列。为 Function 时，可以在回调函数中获取当前列的所有数据，需返回一个 boolean 值来确定隐藏与否
showTooltip Boolean 是否在列表项数据被折叠，鼠标移入时展示一个 toolTip
col Object col-attributes (opens new window)
customRender Function 自定义列数据渲染。customRender({cellValue, row, column, $index, h, store, _self})，支持 jsx 和 h 函数
customTitle Function 自定义列头部渲染。({column, $index, h, store, _self})，支持 jsx 和 h 函数
scopedSlots Object 使用 slot 方式自定义渲染，可替换 customRender/customTitle 函数，优先级低。比如：scopedSlots: { customRender: 'slotName1', customTitle: 'slotName2' }

# 内置插槽

内置分页器插槽，名为pagination使用见集成-pagination 章节示例，可访问到总数total,分页配置项`config

编辑 (opens new window)
上次更新: 2022/03/30, 19:03:00
el-form-plus
vue-ts-template

← vue-ts-template →

最近更新
01
http状态码
04-18
02
test
02-13
03
test
02-13
更多文章>
Theme by ame | Copyright © 2020-2022 Ame | MIT License | 鲁ICP备18003274号-2