npm package: @scenetechnology/cj_element_table
Description: element plus 3.0 表格组件
Latest version: 0.1.47

# cj_element_table

## 项目概述

cj_element_table 是一个基于 Vue3 和 element plus 的表格组件项目。该项目提供了增强的表格功能，简化了表格的使用和配置。

## 安装说明

### 环境要求

- Node.js (建议 v16 或更高版本)
- Yarn 包管理器

### 安装步骤

1. 克隆或下载项目代码
2. 在项目根目录运行以下命令安装依赖：

```
npm install @scenetechnology/cj_element_table --legacy-peer-deps
```

### 引入

1. 在 main.js 中 引入 UI 库 引入 UI 样式

```
import cj_element_table from '@scenetechnology/cj_element_table'
import '@scenetechnology/cj_element_table/dist/cj_element_table.css'
app.use(cj_element_table)
```

# cj_element_table 组件使用文档

## 组件说明

cj_element_table 是一个基于 Element Plus 的表格组件封装，提供了丰富的表格功能，包括数据展示、搜索、排序、导入导出等功能。

## 属性配置

### 基础属性 api

| 属性名                  | 说明                     | 类型          | 默认值                                                      | 是否必填 |
| ----------------------- | ------------------------ | ------------- | ----------------------------------------------------------- | -------- |
| tableData               | 表格数据                 | Object        | {rows: [],total: 0}                                         | 是       |
| columns                 | 表格列配置               | Array         | -                                                           | 是       |
| routerName              | 路由名称                 | String        | -                                                           | 是       |
| exportUrl               | 导出表格数据接口         | String        | -                                                           | 否       |
| exportXlsxName          | 导出表格名称             | String        | 路由名称                                                    | 否       |
| exportConfig            | 导出下拉定义             | Object        | {type:'fujian',url:''}显示导出附件下拉                      | 否       |
| exportParams            | 导出时额外附加的参数对象，会合并到所有导出接口调用中 | Object | {}                                         | 否       |
| templateUrl             | 下载表格模板接口         | String        | -                                                           | 否       |
| templateName            | 表格模板文件名称         | String        | -                                                           | 否       |
| inputUrl                | 导入表格数据接口         | String        | -                                                           | 否       |
| showSelection           | 是否显示表格多选框       | Boolean       | true                                                        | 否       |
| showIndex               | 是否显示表格序号         | Boolean       | true                                                        | 否       |
| showInputButtons        | 是否显示导入按钮         | Boolean       | true                                                        | 否       |
| showTemplateDownload    | 是否显示下载导入模板按钮 | Boolean       | true                                                        | 否       |
| showOutputButtons       | 是否显示导出按钮         | Boolean       | true                                                        | 否       |
| showTableSettingButtons | 是否显示列表设置按钮     | Boolean       | true                                                        | 否       |
| showViewSettingButtons  | 是否显示视图设置按钮     | Boolean       | true                                                        | 否       |
| showCustomExport        | 是否显示自定义导出按钮     | Boolean       | true                                                        | 否       |
| maxHeight               | 表格最大高度             | number/string | 55vh                                                        | 否       |
| selecTableDisabledField | 表格多选框禁用条件       | Object        | {key:'',value:''} 当表格 row 中的[key]字段等于 value 时禁用 | 否       |
| initialQuery            | 初始化查询条件           | Object        | {page: 1,rows: 10,total: 0,}                                | 否       |
| pageSizes               | 分页大小选项             | Array         | [10, 20, 30, 50]                                            | 否       |
| colsPerRow              | 每行的列数               | Number        | 4                                                           | 否       |
| headerCellStyle         | 表头单元格样式           | Object        | {background:'#f5f7fa',color:'#606266',fontWeight:'bold'}    | 否       |
| exportFormatter         | 自定义导出数据格式化函数 | Function      | null                                                        | 否       |
| useCustomExport         | 是否启用外部自定义导出逻辑 | Boolean       | false                                                       | 否       |

### columns 配置项说明

| 字段名       | 说明                                                              | 类型    | 是否必填 | 默认值    | 可选值      |
| ------------ | ----------------------------------------------------------------- | ------- | -------- | --------- | ----------- |
| prop         | 字段名称                                                          | String  | 是       | -         | -           |
| label        | 显示标签                                                          | String  | 是       | -         | -           |
| search       | 是否可搜索                                                        | Boolean | 否       | false     | true/false  |
| searchKey    | 搜索使用字段 默认使用 prop 字段搜索                               | String  | 否       | prop 字段 | -           |
| searchType   | 搜索类型                                                          | String  | 否       | -         | select/date |
| require      | 是否必填                                                          | Boolean | 否       | false     | true/false  |
| defaultValue | 搜索框默认字段                                                    | any     | 否       | -         | -           |
| hide         | 是否显示(列表,不设置导出)                                         | Boolean | 否       | false     | true/false  |
| options      | 选项数组（当 searchType 为 select 时使用）                        | Array   | 否       | -         | -           |
| exportName   | 当你显示的和导出的不想用一个字段时，exportName 表示你要导出的字段 | String  | 否       | -         | -           |
| propName     | 有option默认使用prop从options中获取label显示，有该字段时使用该字段显示 | String  | 否       | -         | -           |

### event 字段详细说明

| search | 表格搜索回调 |
| selection-change | 表格行，选中回调 |
| uploadSuccess | 导入文件回调 |

### columns 字段详细说明

```javascript
const columns = [
  {
    prop: "name",
    require: true,
    label: "项目名称及规模",
    search: true,
  },
  {
    prop: "type",
    label: "项目类型",
    search: true,
    require: true,
    searchType: "select",
    options: [
      { value: 1, label: "新建" },
      { value: 2, label: "改建" },
      { value: 3, label: "扩建" },
      { value: 4, label: "技改（技术改造）" },
      { value: 5, label: "引进（技术引进）" },
    ],
  },
  {
    prop: "status",
    label: "项目状态",
    search: true,
    require: true,
    searchType: "select",
    options: [
      { value: 1, label: "取消" },
      { value: 2, label: "设立" },
      { value: 3, label: "设计" },
      { value: 4, label: "建设中" },
      { value: 5, label: "试生产" },
      { value: 6, label: "竣工验收" },
    ],
  },
  {
    prop: "save",
    label: "是否提交",
    require: true,
    options: [
      { value: 1, label: "待提交" },
      { value: 2, label: "已提交" },
    ],
  },
  {
    prop: "report_date",
    label: "报告时间",
    search: true,
    searchType: "date",
  },
];
```

## 事件

| 事件名           | 说明                             | 回调参数                      |
| ---------------- | -------------------------------- | ----------------------------- |
| selection-change | 当选择项发生变化时会触发该事件   | selection: 已选择的行数据数组 |
| search           | 当搜索条件发生变化时会触发该事件 | query: 搜索条件对象           |
| custom-export    | 触发自定义导出事件（需开启 useCustomExport） | exportData: { type, query, selection, tableData, columns, exportParams } |

## 插槽

| 插槽名    | 说明             |
| --------- | ---------------- |
| operation | 表格顶部操作区域 |
| columns   | 自定义列操作栏   |

## 使用示例

```vue
<template>
  <cj_element_table
    ref="tableRef"
    :exportUrl="exportUrl"
    :templateUrl="templateUrl"
    :inputUrl="inputUrl"
    :tableData="tableData"
    :columns="columns"
    @selection-change="handleSelectionChange"
    @search="handleSearch"
    :exportFormatter="customExportFormatter"
  >
    <template #operation>
      <el-button
        type="primary"
        @click="handleAdd"
        >添加</el-button
      >
    </template>
    <template #columns>
      <el-table-column
        label="操作"
        align="center"
        min-width="120"
      >
        <template #default="scope">
          <el-button
            link
            type="primary"
            @click="handleEdit(scope.row)"
            >编辑</el-button
          >
          <el-button
            link
            type="danger"
            @click="handleDelete(scope.row)"
            >删除</el-button
          >
        </template>
      </el-table-column>
    </template>
  </cj_element_table>
</template>
<script>
// 自定义导出数据格式化函数
const customExportFormatter = (row, columns) => {
  const newRow = { ...row };

  // 处理状态字段
  if (newRow.status === "0") {
    newRow.status = "待审核";
  } else if (newRow.status === "1") {
    newRow.status = "已完成";
  } else if (newRow.status === "-1") {
    newRow.status = "已拒绝";
  }

  return newRow;
};
</script>
```

## 自定义导出使用示例

如果你不想使用组件内置的导出功能（组件内置导出通常需要配置 `exportUrl` 和 `exportConfig`），你可以开启 `useCustomExport` 并在外部自行处理导出逻辑。

```vue
<template>
  <cj_element_table
    ref="tableRef"
    :tableData="tableData"
    :columns="columns"
    :useCustomExport="true"
    @custom-export="handleCustomExport"
  >
  </cj_element_table>
</template>

<script setup>
import { ref } from 'vue'

// 假设我们有一个导出接口
// import { exportDataApi } from '@/api'
// 或者使用第三方库，比如 xlsx
// import * as XLSX from 'xlsx'

const tableRef = ref(null)
const tableData = ref({ rows: [], total: 0 })
const columns = ref([
  { prop: 'name', label: '姓名' },
  { prop: 'age', label: '年龄' }
])

const handleCustomExport = (exportData) => {
  const { type, query, selection, tableData, columns, exportParams } = exportData
  console.log('触发导出:', type)
  console.log('当前查询条件:', query)
  console.log('额外附加参数:', exportParams)

  // 【示例1】：调用后端接口导出
  /*
  // 组装参数
  const params = {
    ...query,
    ...exportParams,
    exportType: type, // 'custom' | 'page' | 'all' 等
    ids: selection.map(item => item.id).join(',') // 如果是导出选中项
  }
  exportDataApi(params).then(res => {
    // 处理文件流下载...
  })
  */

  // 【示例2】：使用 xlsx 库纯前端导出（以导出当前页数据为例）
  /*
  const exportList = tableData.map(row => {
    const obj = {}
    columns.forEach(col => {
      if(!col.hide) {
        obj[col.label] = row[col.prop]
      }
    })
    return obj
  })

  const worksheet = XLSX.utils.json_to_sheet(exportList)
  const workbook = XLSX.utils.book_new()
  XLSX.utils.book_append_sheet(workbook, worksheet, "Sheet1")
  XLSX.writeFile(workbook, "自定义导出数据.xlsx")
  */
}
</script>
```

## exportParams 导出附加参数使用示例

`exportParams` 用于在不修改组件内部逻辑的情况下，向所有导出接口调用中附加固定的业务参数（如项目ID、部门ID等）。

该参数会自动合并到以下所有导出路径中：
- 导出全部数据（`type: 'all'`）
- 按筛选条件导出（`type: 'filter'`）
- 自定义导出弹窗（`type: 'custom'`）
- 后端文件流导出（`exportConfig.type: 'file'`）
- 自定义导出事件（`useCustomExport` 模式下通过 `exportParams` 字段回传）

```vue
<template>
  <cj_element_table
    :tableData="tableData"
    :columns="columns"
    :exportUrl="exportApi"
    :exportParams="{ deptId: 'dept_001', projectId: 'proj_abc' }"
  />
</template>

<script setup>
import { ref } from 'vue'
import { exportApi } from '@/api'

const tableData = ref({ rows: [], total: 0 })
const columns = ref([
  { prop: 'name', label: '姓名' },
  { prop: 'age', label: '年龄' }
])
// 点击导出时，接口实际收到的参数为：
// { page: 1, rows: 10000, deptId: 'dept_001', projectId: 'proj_abc' }
</script>
```

> **注意**：`exportParams` 中的字段优先级低于当前筛选条件（`query` 和 `searchForm`），若存在同名字段，筛选条件会覆盖 `exportParams` 中的值。

npm run build:lib //打包 记得改版本号

npm publish --access public //发布