ZL Element UI 组件库使用文档

基于 Vue 2 + Element UI 的企业级通用业务组件库
版本：0.1.7

目录

• 快速开始
• 组件列表
  • ZlExport - 导出按钮
  • ZlForm - 表单组件
  • ZlInputTable - 输入表格选择器
  • ZlPagination - 分页组件
  • ZlQuery - 查询组件
  • ZlSelect - 选择器组件
  • ZlTable - 表格组件
  • ZlTablePop - 表格弹窗选择器
  • ZlTreePop - 树形弹窗多选组件
  • ZlTreeOnlyPop - 树形弹窗单选组件
  • ZlWaterMark - 水印组件

快速开始

安装依赖

npm install vue@^2.6.14 element-ui@^2.15.14 --save

全局注册（推荐）

在 main.js 中引入并使用：

import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import ZL_Element from '@/package/index.js'

Vue.use(ElementUI)
Vue.use(ZL_Element, {
  size: '',        // 组件尺寸：'' | 'medium' | 'small' | 'mini'
  zIndex: 2000     // 弹窗层级
})

按需引入

import Vue from 'vue'
import ZL_Element, { ZlTable, ZlSelect, ZlTreePop, ZlPagination } from 'zl-element'

// 注册单个组件
Vue.component('ZlTable', ZlTable)
Vue.component('ZlSelect', ZlSelect)
Vue.component('ZlTreePop', ZlTreePop)
Vue.component('ZlPagination', ZlPagination)

// 或者注册全部组件
Vue.use(ZL_Element)

组件列表

ZlExport - 导出按钮

导出功能按钮，支持 Excel 和 PDF 格式导出。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | function | 导出函数，返回 Promise | Function/Boolean | false | | searchForm | 搜索表单参数 | Object | {} | | disabled | 是否禁用 | Boolean | false | | message | 禁用时的提示信息 | String | '请选择要导出的数据' | | icon | 图标类名 | String | 'el-icon-download' | | title | 导出文件名 | String | '导出数据' | | text | 按钮文本 | String | '导出' | | type | 导出类型：'excel' | 'pdf' | String | 'excel' | | beforeExport | 导出前的回调函数，返回 false 可取消导出 | Function | null | | showConfirm | 是否显示确认对话框 | Boolean | true | | confirmText | 确认对话框的提示文本 | String | '是否要导出数据？' |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | export-success | 导出成功事件 | { type: 'excel' | 'pdf' } | | export-error | 导出失败事件 | error |

示例

<template>
  <zl-export 
    :function="exportData" 
    :searchForm="{ id: 123 }"
    title="用户数据导出"
    type="excel"
    @export-success="handleSuccess"
    @export-error="handleError"
  />
</template>

<script>
export default {
  methods: {
    exportData(params) {
      return this.$api.exportExcel(params)
    },
    handleSuccess() {
      this.$message.success('导出成功')
    },
    handleError(err) {
      this.$message.error('导出失败')
    }
  }
}
</script>

ZlForm - 表单组件

整合查询按钮的表单组件，内置 ZlQuery 组件。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | searchForm | 搜索表单数据对象（必填） | Object | - | | inline | 是否行内表单 | Boolean | true | | labelWidth | 表单标签宽度 | String | '' | | showBig | 展开/收起回调函数 | Function/String | null | | showMore | 是否显示更多按钮 | Boolean | false | | icon | 是否显示图标 | Boolean | true | | iconSearch | 搜索图标类名 | String | 'el-icon-search' | | iconReset | 重置图标类名 | String | 'el-icon-refresh' |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | query | 点击查询按钮 | - | | reset | 点击重置按钮 | - |

Slots

| 插槽名 | 说明 | |--------|------| | default | 表单项内容 |

示例

<template>
  <zl-form
    :search-form="queryForm"
    :show-more="true"
    :show-big="toggleMore"
    @query="handleQuery"
    @reset="handleReset"
  >
    <el-form-item label="姓名">
      <el-input v-model="queryForm.name" />
    </el-form-item>
  </zl-form>
</template>

<script>
export default {
  data() {
    return {
      queryForm: {},
      showMoreFields: false
    }
  },
  methods: {
    toggleMore() {
      this.showMoreFields = !this.showMoreFields
    },
    handleQuery() {
      this.getDataList()
    },
    handleReset() {
      this.queryForm = {}
      this.getDataList()
    }
  }
}
</script>

ZlInputTable - 输入表格选择器

带输入框的表格选择器，点击弹出对话框选择数据。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 绑定值（ID） | String/Number | '' | | title | 弹窗标题 | String | '选择类型' | | columnList | 表格列配置 | Array | [] | | tableId | 表格主键字段名 | String/Number | 'channelsCode' | | paramName | 显示名称字段名 | String | 'channelsName' | | function | 查询函数 | Function | null | | width | 弹窗宽度 | String | '850px' | | querysList | 查询条件配置 | Array | 默认两个查询项 | | border | 是否带有纵向边框 | Boolean | true | | appendToBody | Dialog 自身是否插入至 body | Boolean | false | | modalAppendToBody | 遮罩层是否插入至 body | Boolean | true |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | v-model 更新事件 | value | | submit | 确认选择事件 | 选中的行数据 |

示例

<template>
  <zl-input-table
    v-model="selectedId"
    :column-list="columns"
    :function="queryList"
    @submit="handleSubmit"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedId: '',
      columns: [
        { prop: 'code', label: '代码', minWidth: 120 },
        { prop: 'name', label: '名称', minWidth: 150 }
      ]
    }
  },
  methods: {
    queryList(params) {
      return this.$api.getList(params).then(res => res.data)
    },
    handleSubmit(row) {
      console.log('选中的行:', row)
    }
  }
}
</script>

ZlPagination - 分页组件

基于 el-pagination 的分页组件，支持 v-model 双向绑定。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 分页对象（v-model） | Object | { pageNum: 1, pageSize: 20, total: 0 } | | pageSizes | 每页条数选项 | Array | [20, 50, 100] | | layout | 组件布局 | String | 'total, prev, pager, next, sizes, jumper' | | query | 页码改变时的查询函数 | Function | () => {} |

value 对象结构

{
  pageNum: 1,      // 当前页码
  pageSize: 20,    // 每页条数
  total: 0,        // 总条数
  noSet: true      // 自定义标记
}

示例

<template>
  <zl-pagination 
    v-model="pagination" 
    :query="getDataList" 
  />
</template>

<script>
export default {
  data() {
    return {
      pagination: {
        pageNum: 1,
        pageSize: 20,
        total: 0
      }
    }
  },
  methods: {
    getDataList() {
      this.$api.getList(this.pagination).then(res => {
        this.pagination.total = res.total
      })
    }
  }
}
</script>

ZlQuery - 查询组件

查询和重置按钮组，支持展开/收起更多条件。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | showMore | 是否显示更多按钮 | Boolean | false | | icon | 是否显示图标 | Boolean | true | | iconSearch | 搜索图标类名 | String | 'el-icon-search' | | iconReset | 重置图标类名 | String | 'el-icon-refresh' | | showBig | 展开/收起回调函数 | Function/String | - | | queryType | 查询按钮类型 | String | 'primary' | | resetType | 重置按钮类型 | String | 'default' |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | query | 点击查询按钮 | - | | reset | 点击重置按钮 | - |

示例

<template>
  <div>
    <el-form :inline="true">
      <el-form-item label="姓名">
        <el-input v-model="queryForm.name" />
      </el-form-item>
    </el-form>
    
    <zl-query 
      :show-more="true" 
      :show-big="toggleMore"
      @query="handleQuery" 
      @reset="handleReset" 
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      queryForm: {},
      showMoreFields: false
    }
  },
  methods: {
    toggleMore() {
      this.showMoreFields = !this.showMoreFields
    },
    handleQuery() {
      this.getDataList()
    },
    handleReset() {
      this.queryForm = {}
      this.getDataList()
    }
  }
}
</script>

ZlSelect - 选择器组件

增强型选择器，支持远程数据加载和本地数据渲染。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 绑定值 | String/Number | '' | | function | 数据查询函数 | Function | null | | list | 本地数据列表 | Array | [] | | placeholder | 占位符 | String | '请选择' | | total | 是否显示"全部"选项 | Boolean | false | | filterable | 是否可搜索 | Boolean | false | | clearable | 是否可清空 | Boolean | true | | defaultProps | 字段映射对象 | Object | { value: 'value', label: 'label' } |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | v-model 更新事件 | value | | change | 选中值变化事件 | value |

示例

<template>
  <!-- 远程数据 -->
  <zl-select 
    v-model="selectedValue" 
    :function="getOptions" 
    filterable
  />
  
  <!-- 本地数据 -->
  <zl-select 
    v-model="selectedValue" 
    :list="optionList" 
    :total="true"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedValue: '',
      optionList: [
        { value: '1', label: '选项 1' },
        { value: '2', label: '选项 2' }
      ]
    }
  },
  methods: {
    getOptions() {
      return this.$api.getOptions().then(res => res.data)
    }
  }
}
</script>

ZlTable - 表格组件

基于 el-table 的增强表格，支持操作列、枚举渲染、权限控制等。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | columnList | 列配置数组 | Array | [] | | dataList | 表格数据 | Array | [] | | align | 对齐方式 | String | 'left' | | maxHeight | 最大高度 | String/Number | 'auto' | | operationField | 操作列字段名 | String | 'operation' | | selection | 是否显示多选框 | Boolean | false | | selectable | 选择行启用条件 | Function | null | | permissionChecker | 权限检查函数 | Function | null |

ColumnList 配置项

{
  prop: 'name',              // 字段名
  label: '姓名',             // 列头
  align: 'center',           // 对齐方式
  width: 120,                // 列宽
  minWidth: 150,             // 最小列宽
  fixed: 'left',             // 固定列
  slot: 'customSlot',        // 自定义插槽名
  isTag: true,               // 是否以标签形式展示
  show: false,               // 列显隐控制（支持函数）
  hidden: false,              // 列隐藏控制（支持函数）
  formatter: (row, col, val, index) => val,  // 格式化函数
  tagFormatter: (val) => 'success',          // 标签类型函数
  enum: ['禁用', '启用'],    // 枚举配置（数组形式）
  // 或
  enum: {
    0: { label: '禁用', type: 'info' },
    1: { label: '启用', type: 'success' }
  },                          // 枚举配置（对象形式）
  className: 'custom-class'   // 自定义类名
}

操作列 children 配置

{
  prop: 'operation',
  label: '操作',
  fixed: 'right',
  width: 200,
  children: [
    {
      label: '编辑',
      type: 'text',          // 按钮类型
      show: () => this.showEdit,           // 显隐控制（函数返回布尔值）
      permission: 'USER_EDIT',             // 权限码（支持函数）
      action: { type: 'edit' }              // 声明式操作（推荐）
    },
    {
      label: '删除',
      show: (row) => row.status !== 'save', // 支持 row 参数
      permission: () => this.permissions.delete,
      action: { type: 'delete' }
    },
    {
      label: '查看',
      click: (row, index) => this.view(row) // 兼容旧写法
    }
  ]
}

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | table-action | 操作列声明式事件 | { type, row, index, ...action配置 } | | current-change | 当前行变化事件 | currentRow | | cell-click | 单元格点击事件 | row, column, cell, event | | row-click | 行点击事件 | row, column, event | | selection-change | 选择项变化事件 | selection |

Methods

| 方法名 | 说明 | 参数 | |--------|------|------| | setCurrentRow | 设置当前行 | row | | toggleRowSelection | 切换行选中状态 | row, selected | | clearSelection | 清空选择 | - | | getTableRef | 获取 el-table 实例 | - | | updateTableLayout | 手动更新表格布局 | - |

权限控制

// 方式1：通过 permissionChecker prop 传入权限检查函数
<zl-table
  :column-list="columns"
  :data-list="tableData"
  :permission-checker="myPermissionChecker"
/>

// permissionChecker 签名
function myPermissionChecker(permission, row, actionType) {
  // permission: 权限码，如 'USER_EDIT'
  // row: 行数据（行级权限时）
  // actionType: 操作类型，如 'edit'
  return hasPermission(permission)
}

// 方式2：直接在 show/permission 中判断
children: [
  { label: '编辑', show: () => this.hasPermission('USER_EDIT') },
  { label: '删除', permission: 'USER_DELETE' }
]

示例

<template>
  <zl-table
    :data-list="tableData"
    :column-list="columns"
    border
    stripe
    :selection="true"
    :permission-checker="checkPermission"
    @selection-change="handleSelectionChange"
    @table-action="handleTableAction"
  />
</template>

<script>
export default {
  data() {
    return {
      tableData: [],
      columns: [
        { prop: 'name', label: '姓名', minWidth: 120 },
        { prop: 'status', label: '状态', enum: { 0: '禁用', 1: '启用' } },
        { 
          prop: 'operation',
          label: '操作',
          fixed: 'right',
          width: 200,
          children: [
            { label: '编辑', show: () => this.showEdit, action: { type: 'edit' } },
            { label: '删除', show: (row) => row.status !== 0, action: { type: 'delete' } }
          ]
        }
      ]
    }
  },
  methods: {
    handleSelectionChange(selection) {
      console.log('选中的行:', selection)
    },
    handleTableAction({ type, row, index }) {
      switch (type) {
        case 'edit':
          this.edit(row)
          break
        case 'delete':
          this.delete(row)
          break
      }
    },
    checkPermission(permission, row) {
      // 自定义权限检查逻辑
      return true
    }
  }
}
</script>

ZlTablePop - 表格弹窗选择器

弹窗形式的表格选择器（单选）。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 绑定对象（v-model） | Object | {} | | title | 弹窗标题 | String | '选择类型' | | columnList | 表格列配置 | Array | [] | | tableId | 表格主键字段名 | String/Number | 'channelsCode' | | paramId | 绑定值的字段名 | String/Number | 'channelsId' | | function | 查询函数 | Function | () => {} | | width | 弹窗宽度 | String | '850px' | | querysList | 查询条件配置 | Array | 默认两个查询项 | | border | 是否带有纵向边框 | Boolean | true |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | v-model 更新事件 | value | | submit | 确认选择事件 | 选中的行数据 |

示例

<template>
  <el-button @click="openPop">选择渠道</el-button>
  
  <zl-table-pop
    v-model="popValue"
    :column-list="columns"
    :function="queryList"
    @submit="handleSubmit"
  />
</template>

<script>
export default {
  data() {
    return {
      popValue: {
        addDialogVisible: false,
        channelsId: ''
      },
      columns: [
        { prop: 'code', label: '代码', minWidth: 120 },
        { prop: 'name', label: '名称', minWidth: 150 }
      ]
    }
  },
  methods: {
    openPop() {
      this.popValue.addDialogVisible = true
    },
    queryList(params) {
      return this.$api.getList(params).then(res => res.data)
    },
    handleSubmit(row) {
      console.log('选中的行:', row)
      this.popValue.channelsId = row.code
    }
  }
}
</script>

ZlTreePop - 树形弹窗多选组件

树形结构弹窗多选组件。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 绑定值（多个 ID 逗号分隔） | String | '' | | title | 弹窗标题 | String | '选择机构' | | defaultProps | 树节点配置 | Object | { children: 'childDepartment', label: 'departmentName' } | | function | 数据查询函数 | Function | () => {} | | nodeKey | 节点 key 字段名 | String | 'id' |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | v-model 更新事件 | value |

示例

<template>
  <zl-tree-pop
    v-model="selectedDeptIds"
    :function="getDeptTree"
    @input="handleDeptChange"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedDeptIds: ''
    }
  },
  methods: {
    getDeptTree() {
      return this.$api.getDeptTree().then(res => res.data)
    },
    handleDeptChange(value) {
      console.log('选中的部门 IDs:', value)
    }
  }
}
</script>

ZlTreeOnlyPop - 树形弹窗单选组件

树形结构弹窗单选组件。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value | 绑定值（单个 ID） | String/Number | '' | | function | 数据查询函数 | Function | () => {} | | nodeKey | 节点 key 字段名 | String | 'id' | | defaultProps | 树节点配置 | Object | { children: 'childDepartment', label: 'departmentName' } | | name | 名称字段（用于回显） | String | '' | | expandOnClickNode | 点击节点是否展开 | Boolean | false | | highlightCurrent | 高亮当前节点 | Boolean | true | | defaultExpandAll | 默认展开所有节点 | Boolean | false | | placeholder | 占位符 | String | '请选择' |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | v-model 更新事件 | value | | name | 选中名称返回事件 | name |

示例

<template>
  <zl-tree-only-pop
    v-model="selectedDeptId"
    :function="getDeptTree"
    @input="handleDeptChange"
    @name="handleDeptName"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedDeptId: ''
    }
  },
  methods: {
    getDeptTree() {
      return this.$api.getDeptTree().then(res => res.data)
    },
    handleDeptChange(value) {
      console.log('选中的部门 ID:', value)
    },
    handleDeptName(name) {
      console.log('选中的部门名称:', name)
    }
  }
}
</script>

ZlWaterMark - 水印组件

页面水印组件，支持自定义文本和动态时间显示。

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | hiddenTime | 是否隐藏时间显示 | Boolean | false | | text | 水印文本内容 | String | '水印 ' | | opacity | 透明度 | Number | 0.14 | | color | 颜色 | String | '#ccc' | | className | 自定义类名 | String | 'mark-set' |

Slots

| 插槽名 | 说明 | |--------|------| | default | 被水印覆盖的内容 |

示例

<template>
  <zl-water-mark 
    text="内部资料" 
    :opacity="0.2"
    color="#999"
  >
    <div class="content">
      <h1>页面内容</h1>
      <p>这是受保护的内容...</p>
    </div>
  </zl-water-mark>
</template>

全局配置

通过 Vue.use() 传入配置对象：

Vue.use(ZL_Element, {
  size: 'small',  // 全局组件尺寸
  zIndex: 3000    // 全局弹窗层级
})

size 可选值

• '' - 默认尺寸
• 'medium' - 中等尺寸
• 'small' - 小尺寸
• 'mini' - 超小尺寸

注意事项

1. 依赖要求：本项目依赖 Vue 2.x 和 Element UI
2. 样式覆盖：如需自定义样式，建议使用 ::v-deep 深度选择器
3. 函数返回值：所有 function prop 都需要返回 Promise 对象
4. v-model 使用：支持 v-model 的组件会监听 input 事件并触发 input 回调
5. 树形组件：树形组件需要确保数据中有唯一的 nodeKey
6. 表格枚举：ZlTable 的 enum 配置支持数组和对象两种形式，对象形式可配置标签类型

常见问题

Q: 如何自定义表格列的样式？

A: 在 columnList 中设置 className 属性：

{
  prop: 'name',
  label: '姓名',
  className: 'custom-column-class'
}

Q: 如何让表格支持横向滚动？

A: 设置 maxHeight 并为列设置固定宽度或 minWidth：

<zl-table 
  :max-height="500"
  :column-list="columns"
/>

Q: 如何实现行级权限控制？

A: 使用 permissionChecker prop 传入自定义权限检查函数，或在按钮配置中使用 show 函数返回行级判断结果。

Q: 水印组件如何实时更新？

A: 水印会自动每秒更新时间显示，可通过 hiddenTime 属性关闭时间显示。

更新日志

• 0.1.7 新增 ZlForm 表单组件
• 0.1.7 ZlTable 新增 enum 配置、权限控制、operation slot
• 0.1.7 ZlExport 新增 beforeExport 回调和确认对话框配置
• 0.1.7 优化表格布局自动刷新机制
• 0.1.7 增加树形组件过滤功能
• 0.1.7 统一组件尺寸配置

技术支持

如有问题请联系开发团队或提交 Issue。

作者: z_l
License: MIT
Repository: https://gitee.com/zhuyuelei/packge_to_npm