poorki-elementui

基于 Element UI 2.11 的二次封装组件库，提供更丰富和易用的 Vue 2 组件。

📦 安装

npm install poorki-elementui

🚀 快速开始

完整引入

import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import poorkiElementui from 'poorki-elementui'
import 'poorki-elementui/lib/index.css'

Vue.use(ElementUI)
Vue.use(poorkiElementui)

按需引入

import { 
  PkForm, 
  PkTable, 
  PkFileUpload, 
  PkImageUpload,
  PkFormDialog,
  PkPagination,
  PkTextInput,
  PkNumberInput,
  PkSelect,
  PkRadio,
  PkCheckbox,
  PkDatepicker,
  PkCascader,
  PkTreeSelect
} from 'poorki-elementui'

Vue.component(PkForm.name, PkForm)
Vue.component(PkTable.name, PkTable)
Vue.component(PkFileUpload.name, PkFileUpload)
Vue.component(PkImageUpload.name, PkImageUpload)
Vue.component(PkFormDialog.name, PkFormDialog)
Vue.component(PkPagination.name, PkPagination)
Vue.component(PkTextInput.name, PkTextInput)
Vue.component(PkNumberInput.name, PkNumberInput)
Vue.component(PkSelect.name, PkSelect)
Vue.component(PkRadio.name, PkRadio)
Vue.component(PkCheckbox.name, PkCheckbox)
Vue.component(PkDatepicker.name, PkDatepicker)
Vue.component(PkCascader.name, PkCascader)
Vue.component(PkTreeSelect.name, PkTreeSelect)

📋 组件API文档

🎯 PkForm - 动态表单

强大的动态表单生成器，支持多种表单控件类型、动态显示/隐藏、验证规则等。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 表单数据对象 | Object | - | {} | | formConfig | 表单配置数组 | Array | - | [] | | rules | 验证规则对象 | Object | - | {} | | inline | 是否行内表单模式 | Boolean | - | false | | gutter | 栅格间隔 | Number | - | 20 | | inlineSearch | 是否显示搜索按钮 | Boolean | - | false | | labelWidth | 标签宽度 | String/Number | - | - | | onSearch | 搜索回调函数 | Function | - | null | | onReset | 重置回调函数 | Function | - | null |

方法 (Methods)

| 方法名 | 说明 | 参数 | |--------|------|------| | validate | 表单验证 | - | | validateField | 验证单个字段 | props: string/array | | resetFields | 重置表单字段 | - | | clearValidate | 清除验证信息 | props: string/array | | submit | 提交表单 | - | | getFormData | 获取表单数据 | - |

事件 (Events)

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | 表单数据更新时触发 | formData: Object | | submit | 表单提交时触发 | formData: Object |

插槽 (Slots)

| 插槽名 | 说明 | 作用域参数 | |--------|------|------------| | append | 表单底部自定义内容 | { formData } | | [自定义slot] | 自定义表单项内容 | { config, formData } |

FormConfig 配置项

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | type | 表单控件类型 | String | text | | label | 标签文本 | String | - | | prop | 表单域字段 | String | - | | placeholder | 占位文本 | String | - | | span | 栅格占位 | Number | 8 | | show | 是否显示 | Function | true | | disabled | 是否禁用 | Boolean/Function | false | | rules | 验证规则 | Array/Object | - | | list | 选项列表 | Array | - | | slot | 自定义插槽名 | String | - |

支持的表单控件类型：

• text - 文本输入框
• textarea - 多行文本框
• number - 数字输入框
• select - 下拉选择器
• radio - 单选框组
• checkbox - 多选框组
• date - 日期选择器
• daterange - 日期范围选择器
• cascader - 级联选择器
• switch - 开关
• image - 图片上传
• file - 文件上传
• slot - 自定义插槽

📊 PkTable - 数据表格

功能丰富的数据表格组件，支持分页、排序、筛选、列设置等。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | columns | 列配置数组 | Array | - | [] | | tableData | 表格数据 | Array | - | [] | | isPagination | 是否显示分页 | Boolean | - | false | | page | 分页配置 | Object | - | { pageIndex: 1, pageSize: 10, total: 0 } | | selectedRows | 选中的行数据 | Array | - | [] | | layout | 分页布局 | String | - | 'total, sizes, prev, pager, next, jumper' |

方法 (Methods)

| 方法名 | 说明 | 参数 | |--------|------|------| | validate | 验证表格中的表单 | - | | clearValidate | 清除验证信息 | props: string/array | | openColumnSettings | 打开自定义列设置对话框 | - | | resetColumnSettings | 重置自定义列设置 | - |

事件 (Events)

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | pageChange | 分页变化时触发 | { pageIndex, pageSize } | | update:selectedRows | 选中行变化时触发 | selection: Array | | column-settings-change | 自定义列设置变化时触发 | selectedColumns: Array |

插槽 (Slots)

| 插槽名 | 说明 | 作用域参数 | |--------|------|------------| | default | 表格顶部自定义内容 | - | | empty | 空数据自定义内容 | - | | [自定义slot] | 自定义列内容 | { row, column, $index } |

Columns 配置项

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | label | 列标题 | String | - | | prop | 列字段 | String | - | | type | 列类型 | String | - | | slot | 自定义插槽名 | String | - | | width | 列宽度 | String/Number | - | | minWidth | 最小宽度 | String/Number | - | | fixed | 是否固定列 | Boolean/String | - | | formatter | 格式化函数 | Function | - | | rules | 验证规则 | Array/Object | - | | on | 事件监听器 | Object | - |

📁 PkFileUpload - 文件上传

通用文件上传组件，支持多种文件类型和下载。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 文件列表 | Array | - | [] | | uploadApi | 上传API函数 | Function | - | - | | downloadApi | 下载API函数 | Function | - | - | | accept | 接受的文件类型 | String | - | - | | limit | 最大上传数量 | Number | - | - | | itemWidth | 文件项宽度 | String | - | - | | showAdd | 是否显示添加按钮 | Boolean | - | true | | showDownload | 是否显示下载按钮 | Boolean | - | true | | showDelete | 是否显示删除按钮 | Boolean | - | true |

事件 (Events)

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | 文件列表更新时触发 | fileList: Array |

插槽 (Slots)

| 插槽名 | 说明 | 作用域参数 | |--------|------|------------| | default | 自定义上传区域 | { uploading, fileList, handlePickFile, handleDownload, handleRemove } |

🖼️ PkImageUpload - 图片上传

专门用于图片上传的组件，支持预览和裁剪。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 图片列表 | Array | - | [] | | uploadApi | 上传API函数 | Function | - | - | | downloadApi | 下载API函数 | Function | - | - | | width | 图片宽度 | String | - | - | | height | 图片高度 | String | - | - | | limit | 最大上传数量 | Number | - | - | | singleMode | 是否单图模式 | Boolean | - | false | | showAdd | 是否显示添加按钮 | Boolean | - | true | | showPreview | 是否显示预览按钮 | Boolean | - | true | | showDownload | 是否显示下载按钮 | Boolean | - | true | | showDelete | 是否显示删除按钮 | Boolean | - | true |

事件 (Events)

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | 图片列表更新时触发 | imageList: Array |

插槽 (Slots)

| 插槽名 | 说明 | 作用域参数 | |--------|------|------------| | default | 自定义上传区域 | { uploading, imageList, handlePickFile, handleDownload, handleRemove } |

💬 PkFormDialog - 表单对话框

结合 PkForm 的对话框组件，用于表单弹窗操作。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | labelWidth | 标签宽度 | String | - | '120px' | | showFooter | 是否显示底部 | Boolean | - | true | | showCancel | 是否显示取消按钮 | Boolean | - | true | | showSubmit | 是否显示确认按钮 | Boolean | - | true | | dialogWidth | 对话框宽度 | String | - | '70%' | | titleCenter | 标题是否居中 | Boolean | - | false | | size | 尺寸 | String | medium/small/mini | medium | | appendToBody | 是否插入至body | Boolean | - | false |

方法 (Methods)

| 方法名 | 说明 | 参数 | |--------|------|------| | show | 显示对话框 | { title, formModel, formConfig, beforeClose } | | close | 关闭对话框 | - | | getFormData | 获取表单数据 | - | | setFormData | 设置表单数据 | value: Object |

插槽 (Slots)

| 插槽名 | 说明 | 作用域参数 | |--------|------|------------| | title | 自定义标题 | { row, close, submit } | | default | 对话框内容 | - | | footer | 自定义底部 | { row, close, submit } |

📄 PkPagination - 分页器

分页组件，支持页面大小调整和快速跳转。

属性 (Props)

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | currentPage | 当前页码 | Number | - | 1 | | pageSize | 每页条数 | Number | - | 10 | | total | 总条数 | Number | - | 必填 | | pageSizes | 每页条数选项 | Array | - | [10, 30, 100] | | pageCount | 页码按钮数量 | Number | - | 7 | | layout | 组件布局 | String | - | 'total, sizes, prev, pager, next, jumper' |

事件 (Events)

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | change | 分页变化时触发 | { currentPage, pageSize } |

🔧 基础组件

PkTextInput - 文本输入

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | String/Number | - | - | | placeholder | 占位文本 | String | - | - | | maxlength | 最大长度 | Number | - | - | | clearable | 是否可清空 | Boolean | - | false | | disabled | 是否禁用 | Boolean | - | false | | readonly | 是否只读 | Boolean | - | false |

<PkTextInput
  v-model="value"
  placeholder="请输入内容"
  :maxlength="50"
  clearable
/>

PkNumberInput - 数字输入

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Number | - | - | | min | 最小值 | Number | - | - | | max | 最大值 | Number | - | - | | step | 步长 | Number | - | 1 | | precision | 精度 | Number | - | - | | disabled | 是否禁用 | Boolean | - | false |

<PkNumberInput
  v-model="amount"
  :precision="2"
  :step="0.01"
  :min="0"
  :max="10000"
/>

PkSensitiveInput - 敏感信息输入

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | String | - | - | | type | 输入框类型 | String | password | - | | show-password | 是否显示密码 | Boolean | - | false | | sensitive | 是否敏感数据 | Boolean | - | true |

<PkSensitiveInput
  v-model="password"
  type="password"
  placeholder="请输入密码"
  show-password
/>

PkSelect - 下拉选择

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Any | - | - | | options | 选项数组 | Array | - | [] | | placeholder | 占位文本 | String | - | - | | clearable | 是否可清空 | Boolean | - | false | | filterable | 是否可搜索 | Boolean | - | false | | multiple | 是否多选 | Boolean | - | false | | disabled | 是否禁用 | Boolean | - | false |

<PkSelect
  v-model="selected"
  :options="[
    { label: '选项1', value: 'option1' },
    { label: '选项2', value: 'option2' }
  ]"
  placeholder="请选择"
  clearable
  filterable
/>

PkRadio - 单选框组

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Any | - | - | | options | 选项数组 | Array | - | [] | | button-style | 是否按钮样式 | Boolean | - | false | | disabled | 是否禁用 | Boolean | - | false |

<PkRadio
  v-model="gender"
  :options="[
    { label: '男', value: 'male' },
    { label: '女', value: 'female' }
  ]"
  button-style
/>

PkCheckbox - 多选框组

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Array | - | [] | | options | 选项数组 | Array | - | [] | | button-style | 是否按钮样式 | Boolean | - | false | | disabled | 是否禁用 | Boolean | - | false |

<PkCheckbox
  v-model="hobbies"
  :options="[
    { label: '读书', value: 'reading' },
    { label: '运动', value: 'sports' },
    { label: '音乐', value: 'music' }
  ]"
/>

PkDatepicker - 日期选择器

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Date/Array | - | - | | type | 显示类型 | String | date | - | | placeholder | 占位文本 | String | - | - | | format | 格式化字符串 | String | - | yyyy-MM-dd | | value-format | 绑定值格式 | String | - | - | | clearable | 是否可清空 | Boolean | - | false |

<PkDatepicker
  v-model="date"
  type="date"
  placeholder="选择日期"
  format="yyyy-MM-dd"
/>

PkCascader - 级联选择器

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Array | - | - | | options | 选项数组 | Array | - | [] | | placeholder | 占位文本 | String | - | - | | clearable | 是否可清空 | Boolean | - | false | | showAllLevels | 是否显示完整路径 | Boolean | - | true |

<PkCascader
  v-model="region"
  :options="regionOptions"
  placeholder="请选择地区"
  show-all-levels
/>

PkTreeSelect - 树形选择器

| 参数 | 说明 | 类型 | 可选值 | 默认值 | |------|------|------|--------|--------| | value / v-model | 绑定值 | Any/Array | - | - | | data | 数据源 | Array | - | [] | | props | 配置选项 | Object | - | { label: 'label', children: 'children' } | | showCheckbox | 是否显示复选框 | Boolean | - | false | | multiple | 是否多选 | Boolean | - | false |

<PkTreeSelect
  v-model="selectedNodes"
  :data="treeData"
  :props="{ label: 'name', children: 'children' }"
  show-checkbox
  multiple
/>

🎯 使用示例

基础表单示例

<template>
  <pk-form
    ref="basicForm"
    v-model="basicFormData"
    :formConfig="basicFormConfig"
    :rules="basicRules"
    label-width="120px"
    @submit="handleBasicSubmit"
  >
    <template slot="append" slot-scope="{ formData }">
      <el-form-item>
        <el-button type="primary" @click="submitBasicForm(formData)">提交</el-button>
        <el-button @click="resetBasicForm">重置</el-button>
      </el-form-item>
    </template>
  </pk-form>
</template>

<script>
export default {
  data() {
    return {
      basicFormData: {
        username: '',
        email: '',
        age: '',
        gender: null,
        bio: ''
      },
      basicFormConfig: [
        {
          type: 'text',
          label: '用户名',
          prop: 'username',
          placeholder: '请输入用户名',
          rules: [
            { required: true, message: '用户名不能为空' },
            { min: 3, max: 20, message: '用户名长度在3到20个字符' }
          ]
        },
        {
          type: 'select',
          label: '性别',
          prop: 'gender',
          placeholder: '请选择性别',
          list: [
            { label: '男', value: 'male' },
            { label: '女', value: 'female' }
          ]
        }
      ]
    }
  },
  methods: {
    handleBasicSubmit(formData) {
      this.$message.success('表单提交成功！')
      console.log('提交数据:', formData)
    }
  }
}
</script>

数据表格示例

<template>
  <div>
    <div style="margin-bottom: 10px;">
      <el-button size="small" @click="$refs.pkTableRef.openColumnSettings()">自定义列设置</el-button>
    </div>
    <PkTable
      ref="pkTableRef"
      :is-pagination="true"
      :page="page"
      :columns="tableColumns"
      :table-data="tableData"
      @pageChange="handlePageChange"
    >
      <template slot="image" slot-scope="{row}">
        <el-image
          style="width: 50px; height: 50px"
          :src="row.image"
          :preview-src-list="[row.image]"
        />
      </template>
      <template slot="operation" slot-scope="scope">
        <el-link type="primary" @click="editFunc(scope.row)">编辑</el-link>
        <el-link type="primary" @click="deleteFunc(scope.row)">删除</el-link>
      </template>
    </PkTable>
  </div>
</template>

<script>
export default {
  data() {
    return {
      page: {
        pageIndex: 1,
        pageSize: 10,
        total: 0
      },
      tableColumns: [
        { label: '标题', prop: 'titleOriginal', showOverflowTooltip: true },
        { label: '类型', prop: 'typeId', formatter: this.formatType },
        { 
          label: '图片', 
          prop: 'image', 
          slot: 'image',
          type: 'image', 
          controlProps: { width: '50px', height: '50px' }, 
          singleMode: true 
        },
        {
          label: '首屏展示',
          prop: 'isFirstScreen',
          type: 'switch',
          activeValue: '1',
          inactiveValue: '0',
          on: {
            change: (value, { row }) => {
              console.log('switch change', value, row)
            }
          }
        },
        { label: '操作', slot: 'operation', width: '100px' }
      ],
      tableData: []
    }
  },
  methods: {
    formatType(row, column, cellValue, index) {
      const typeMap = { 1: '新闻', 2: '公告', 3: '活动' }
      return typeMap[cellValue] || '-'
    },
    handlePageChange(params) {
      this.page = { ...this.page, ...params }
      this.loadData()
    },
    editFunc(row) {
      console.log('编辑:', row)
    },
    deleteFunc(row) {
      console.log('删除:', row)
    }
  }
}
</script>

表单对话框示例

<template>
  <div>
    <el-button type="primary" @click="openDialog">打开对话框</el-button>
    <PkFormDialog ref="pkFormDialogRef" />
  </div>
</template>

<script>
export default {
  methods: {
    openDialog() {
      this.$refs.pkFormDialogRef.show({
        title: '编辑信息',
        formModel: { name: '', email: '' },
        formConfig: [
          {
            type: 'text',
            label: '姓名',
            prop: 'name',
            placeholder: '请输入姓名',
            rules: [{ required: true, message: '姓名不能为空' }]
          },
          {
            type: 'text',
            label: '邮箱',
            prop: 'email',
            placeholder: '请输入邮箱',
            rules: [{ required: true, message: '邮箱不能为空' }]
          }
        ],
        beforeClose: (action, instance, done) => {
          if (action === 'confirm') {
            console.log('提交数据:', instance.getFormData())
            done()
          } else {
            done()
          }
        }
      }).then((formData) => {
        console.log('对话框返回数据:', formData)
      }).catch(() => {
        console.log('取消操作')
      })
    }
  }
}
</script>

🎯 核心特性

✨ 动态表单

• 多种表单控件支持
• 动态字段显示/隐藏
• 内置表单验证
• 支持inline模式
• 自定义插槽支持

📊 增强表格

• 可编辑单元格
• 自定义列设置
• 内置分页器
• 丰富的列类型
• 插槽自定义支持

📁 文件处理

• 智能文件类型识别
• 图片预览功能
• 拖拽上传支持
• 进度显示
• 批量操作

🎨 设计一致性

• 基于 Element UI 设计语言
• 响应式布局
• 主题可定制
• 移动端友好

🔧 开发指南

环境要求

• Node.js >= 18.0.0
• npm >= 8.0.0
• Vue >= 2.5.17
• Element UI >= 2.11.0

本地开发

# 克隆项目
git clone https://github.com/your-username/poorki-elementui.git

# 安装依赖
cd poorki-elementui
npm install

# 启动开发服务器
npm run dev

# 构建项目
npm run build:all

# 代码检查
npm run lint

# 代码修复
npm run lint:fix

项目结构

poorki-elementui/
├── src/
│   ├── components/          # 组件源码
│   │   ├── PkForm.vue     # 动态表单组件 ⭐
│   │   ├── PkTable.vue    # 数据表格组件 ⭐
│   │   ├── PkFileUpload.vue # 文件上传组件 ⭐
│   │   ├── PkImageUpload.vue # 图片上传组件 ⭐
│   │   ├── PkFormDialog.vue # 表单对话框组件 ⭐
│   │   ├── PkPagination.vue # 分页组件 ⭐
│   │   ├── PkTextInput.vue # 文本输入组件
│   │   ├── PkSensitiveInput.vue # 敏感输入组件
│   │   ├── PkNumberInput.vue # 数字输入组件
│   │   ├── PkSelect.vue # 下拉选择组件
│   │   ├── PkRadio.vue # 单选框组件
│   │   ├── PkCheckbox.vue # 多选框组件
│   │   ├── PkDatepicker.vue # 日期选择组件
│   │   ├── PkCascader.vue # 级联选择组件
│   │   ├── PkTreeSelect.vue # 树形选择组件
│   │   ├── PkFormItem.vue # 表单项组件
│   │   ├── PkRender.vue # 动态渲染组件
│   │   └── ...           # 其他组件
│   ├── styles/            # 样式文件
│   │   └── variables.scss # SCSS 变量
│   ├── demo.vue           # 演示页面
│   └── index.js          # 入口文件
├── lib/                  # 构建输出
├── dist/                 # 样式文件
├── package.json
├── README.md
└── webpack.config.js      # Webpack 配置

支持的文件类型

文件类型图标映射：

• 🖼️ 图片: jpg, jpeg, png, gif, bmp, webp, svg
• 📄 文档: doc, docx, pdf, txt, rtf
• 📊 表格: xls, xlsx, csv
• 📋 演示: ppt, pptx
• 🎵 音频: mp3, wav, ogg, aac, flac
• 🎬 视频: mp4, avi, mov, wmv, flv, mkv, webm
• 📦 压缩: zip, rar, 7z, tar, gz
• 💻 代码: js, css, html, json, xml, java, py, cpp, c, h

数据格式支持

上传组件支持的数据格式：

• Base64字符串 - data:image/jpeg;base64,xxx 或纯base64
• URL字符串 - https://example.com/image.jpg 或相对路径
• 二进制数据 - Blob、ArrayBuffer、Uint8Array

📝 完整示例

查看 src/demo.vue 获取完整的使用示例，包含：

🎯 表单示例

• ✅ 基础表单示例
• 🔍 搜索表单示例
• 🎨 复杂表单示例
• 🔄 动态表单示例

📊 表格示例

• 📋 可编辑表格示例
• ⚙️ 自定义列 设置功能
• 🖼️ 图片预览
• 🔄 分页操作

💬 对话框示例

• ✏️ 编辑功能
• ➕ 添加功能
• 📝 表单验证

🤝 贡献指南

欢迎贡献代码！请遵循以下规范：

开发规范

1. 代码风格

   • 使用 ESLint 进行代码检查
   • 遵循 Vue.js 官方风格指南
   • 组件名使用 PascalCase
   • 变量名使用 camelCase

2. 提交规范

   • 使用 Conventional Commits 规范
   • 提交信息格式：type(scope): description
   • 类型：feat, fix, docs, style, refactor, test, chore

3. 组件开发

   • 组件必须有明确的 props 类型定义
   • 提供完整的事件监听
   • 编写相应的文档注释
   • 确保向后兼容性

4. 测试要求

   • 新功能需要添加单元测试
   • 确保测试覆盖率不低于 80%
   • 手动测试关键功能

提交流程

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• 感谢 Element UI 团队提供的优秀基础组件库
• 感谢所有贡献者的付出和支持
• 感谢社区的反馈和建议