ylwl-cpscoms 1.0.0 → 1.1.0

package/src/DtTable/DtTable/347/273/204/344/273/266/344/275/277/347/224/250/346/226/207/346/241/243.md

@@ -0,0 +1,819 @@
+# DtTable 组件使用文档
+
+> 基于 Element UI 封装的可编辑表格组件，支持多种编辑器类型、表单验证、异步数据加载、联动等功能。
+
+---
+
+## 目录
+
+- [基础用法](#基础用法)
+- [Props 属性](#props-属性)
+- [gridOptions 配置](#gridoptions-配置)
+- [columns 列配置](#columns-列配置)
+- [编辑器类型](#编辑器类型)
+- [操作按钮配置](#操作按钮配置)
+- [Methods 方法](#methods-方法)
+- [Events 事件](#events-事件)
+- [高级功能](#高级功能)
+- [完整示例](#完整示例)
+
+---
+
+## 基础用法
+
+```vue
+<template>
+  <DtTable ref="dtTable" :grid-options="gridOptions" />
+</template>
+
+<script>
+import DtTable from '@/components/global/DtTable'
+
+export default {
+  components: { DtTable },
+  data() {
+    return {
+      gridOptions: {
+        data: [
+          { name: '张三', age: 25, city: '北京' },
+          { name: '李四', age: 30, city: '上海' }
+        ],
+        columns: [
+          { field: 'name', title: '姓名' },
+          { field: 'age', title: '年龄' },
+          { field: 'city', title: '城市' }
+        ]
+      }
+    }
+  }
+}
+</script>
+```
+
+---
+
+## Props 属性
+
+| 属性名 | 类型 | 默认值 | 必填 | 说明 |
+|--------|------|--------|------|------|
+| gridOptions | Object | - | 是 | 表格配置对象，详见 [gridOptions 配置](#gridoptions-配置) |
+| isDisabled | Boolean | false | 否 | 全局禁用所有编辑器 |
+| pagination | Object | 见下方 | 否 | 分页配置 |
+| apiFunction | Function | - | 否 | 数据请求 API 函数，传入后自动启用分页 |
+| apiParams | Object | - | 否 | API 请求额外参数 |
+| immediate | Boolean | false | 否 | 是否在 mounted 时立即加载数据 |
+
+### pagination 默认值
+
+```javascript
+{
+  currentPage: 1,
+  pageSize: 10,
+  total: 0,
+  pageSizes: [10, 20, 50, 100],
+  layout: 'total, sizes, prev, pager, next, jumper',
+  background: true,
+  small: false,
+  disabled: false,
+  hideOnSinglePage: false
+}
+```
+
+---
+
+## gridOptions 配置
+
+```javascript
+gridOptions: {
+  // 表格数据
+  data: [],
+
+  // 列配置
+  columns: [],
+
+  // 操作列按钮
+  actions: [],
+
+  // 滚动区域宽高
+  scroll: {
+    x: '1200px',  // 横向滚动宽度
+    y: 400        // 纵向滚动高度（默认400）
+  },
+
+  // 操作列配置
+  actionWidth: '100px',   // 操作列宽度
+  actionAlign: 'left',    // 操作列对齐方式
+  actionFixed: 'right'    // 操作列固定位置
+}
+```
+
+---
+
+## columns 列配置
+
+### 基础属性
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| field | String | 字段名，对应数据中的 key |
+| title | String | 列标题 |
+| hidden | Boolean | 是否隐藏该列 |
+| attrs | Object | 传递给 `el-table-column` 的额外属性（如 width, minWidth, fixed 等） |
+
+### 示例
+
+```javascript
+columns: [
+  {
+    field: 'name',
+    title: '姓名',
+    attrs: { width: 120, fixed: 'left' }
+  },
+  {
+    field: 'age',
+    title: '年龄',
+    attrs: { minWidth: 80, align: 'center' }
+  }
+]
+```
+
+---
+
+## 编辑器类型
+
+通过 `editor` 属性指定列的编辑器类型。
+
+### 1. 文本显示（默认）
+
+不设置 `editor` 或不配置，直接显示文本。
+
+```javascript
+{
+  field: 'name',
+  title: '姓名'
+  // 显示为文本，空值显示 "-"
+}
+```
+
+### 2. 自定义渲染 (custom)
+
+通过 `render` 函数自定义渲染内容，支持 h 函数。
+
+```javascript
+{
+  field: 'status',
+  title: '状态',
+  editor: 'custom',
+  render: ({ row, h }) => {
+    // 返回文本
+    return row.status === 1 ? '启用' : '禁用'
+
+    // 返回 VNode（使用 h 函数）
+    return h('el-tag', {
+      props: { type: row.status === 1 ? 'success' : 'danger' }
+    }, row.status === 1 ? '启用' : '禁用')
+  }
+}
+```
+
+### 3. 选择器 (select)
+
+```javascript
+{
+  field: 'city',
+  title: '城市',
+  editor: 'select',
+  placeholder: '请选择城市',
+  options: [
+    { label: '北京', value: 'beijing' },
+    { label: '上海', value: 'shanghai' }
+  ],
+  // 自定义选项字段名
+  labelKey: 'name',    // 默认 'label'
+  valueKey: 'code',    // 默认 'value'
+  // 是否可搜索
+  filterable: true,
+  // 是否远程搜索
+  remote: false,
+  // 事件
+  events: {
+    change(value, row, index) {
+      console.log('选择变化:', value)
+    }
+  }
+}
+```
+
+### 4. 输入框 (input)
+
+```javascript
+{
+  field: 'name',
+  title: '姓名',
+  editor: 'input',
+  placeholder: '请输入姓名',
+  events: {
+    change(value, row, index) {
+      console.log('输入变化:', value)
+    },
+    focus(event, row) {
+      console.log('获取焦点')
+    },
+    blur(event, row, index) {
+      console.log('失去焦点')
+    }
+  }
+}
+```
+
+### 5. 数字输入框 (input-number)
+
+```javascript
+{
+  field: 'quantity',
+  title: '数量',
+  editor: 'input-number',
+  min: 1,                    // 最小值，支持函数 (row, index) => number
+  max: 100,                  // 最大值，支持函数 (row, index) => number
+  step: 1,                   // 步长
+  precision: 0,              // 小数精度
+  controlsPosition: '',      // 控制按钮位置 ('right')
+  unit: '个',                // 单位后缀，支持字符串或 h 函数
+  attrs: { width: 180 }
+}
+```
+
+**unit 支持 h 函数**：
+
+```javascript
+{
+  field: 'price',
+  title: '价格',
+  editor: 'input-number',
+  unit: (h, scope) => {
+    return h('span', { style: { color: '#f56c6c' } }, '元')
+  }
+}
+```
+
+### 6. 开关 (switch)
+
+```javascript
+{
+  field: 'enable',
+  title: '是否启用',
+  editor: 'switch',
+  events: {
+    change(value, row, index) {
+      console.log('开关变化:', value)
+    }
+  }
+}
+```
+
+### 7. 时间选择器 (time)
+
+```javascript
+{
+  field: 'time',
+  title: '时间',
+  editor: 'time',
+  placeholder: '选择时间',
+  attrs: {
+    'value-format': 'HH:mm:ss',
+    'picker-options': { selectableRange: '00:00:00 - 23:59:59' }
+  }
+}
+```
+
+### 8. 日期选择器 (date)
+
+```javascript
+{
+  field: 'date',
+  title: '日期',
+  editor: 'date',
+  placeholder: '选择日期',
+  attrs: {
+    'value-format': 'yyyy-MM-dd',
+    type: 'date'
+  }
+}
+```
+
+### 9. 日期时间选择器 (datetime)
+
+```javascript
+{
+  field: 'datetime',
+  title: '日期时间',
+  editor: 'datetime',
+  placeholder: '选择日期时间',
+  attrs: {
+    'value-format': 'yyyy-MM-dd HH:mm:ss'
+  }
+}
+```
+
+### 10. 日期范围选择器 (daterange)
+
+```javascript
+{
+  field: 'dateRange',
+  title: '日期范围',
+  editor: 'daterange',
+  placeholder: '选择日期范围',
+  attrs: {
+    'value-format': 'yyyy-MM-dd'
+  }
+}
+```
+
+---
+
+### 公共编辑器属性
+
+以下属性适用于所有编辑器类型：
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| placeholder | String | 占位符文本 |
+| disabled | Boolean / Function(row, index) | 是否禁用 |
+| rules | Array | 表单验证规则 |
+| events | Object | 事件处理 { change, focus, blur, clear } |
+
+### 禁用配置
+
+```javascript
+// 固定禁用
+{ field: 'name', disabled: true }
+
+// 动态禁用（函数）
+{
+  field: 'name',
+  disabled: (row, index) => {
+    return row.type === 1  // type 为 1 时禁用
+  }
+}
+```
+
+---
+
+## 操作按钮配置
+
+```javascript
+gridOptions: {
+  actions: [
+    {
+      text: '编辑',           // 按钮文字
+      type: 'primary',       // 按钮类型 (primary / success / warning / danger / info / text)
+      icon: 'el-icon-edit',  // 图标
+      style: { color: '#409EFF' },  // 自定义样式
+      show: true,            // 是否显示，支持 Boolean 或 Function(row, index)
+      disabled: false,       // 是否禁用，支持 Boolean 或 Function(row)
+      click(row, index) {    // 点击事件
+        console.log('编辑:', row, index)
+      }
+    },
+    {
+      text: '删除',
+      type: 'text',
+      style: { color: '#F56C6C' },
+      show: (row, index) => row.status !== 1,  // 状态为 1 时隐藏
+      disabled: (row) => row.locked,           // 锁定时禁用
+      click(row, index) {
+        console.log('删除:', row, index)
+      }
+    }
+  ],
+  actionWidth: '150px',  // 操作列宽度
+  actionAlign: 'center', // 对齐方式
+  actionFixed: 'right'   // 固定在右侧
+}
+```
+
+---
+
+## Methods 方法
+
+通过 `ref` 调用组件方法：
+
+```javascript
+this.$refs.dtTable.validate()
+```
+
+### 表格操作
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| getSelection() | - | Array | 获取当前选中的行数据 |
+| clearSelection() | - | void | 清空所有选中状态 |
+| toggleRowSelection(row, selected) | row: Object, selected: Boolean | void | 切换某行的选中状态 |
+| scrollToBottom() | - | void | 滚动表格到底部 |
+
+### 数据请求
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| refresh(params) | params: Object | Promise | 刷新表格数据，可传入额外参数 |
+
+```javascript
+// 刷新数据
+this.$refs.dtTable.refresh()
+
+// 带参数刷新
+this.$refs.dtTable.refresh({ keyword: '搜索词' })
+```
+
+### 表单验证
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| validate() | - | Promise | 验证所有表单字段 |
+| resetFields() | - | void | 重置所有表单字段 |
+| clearValidate() | - | void | 清除所有验证状态 |
+
+```javascript
+// 验证表单
+try {
+  await this.$refs.dtTable.validate()
+  console.log('验证通过')
+} catch (error) {
+  console.log('验证失败')
+}
+```
+
+### 联动操作
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| triggerLinkage(field, type) | field: String, type: String | void | 手动触发指定字段的联动 |
+
+```javascript
+// 手动触发联动
+this.$refs.dtTable.triggerLinkage('province', 'init')
+```
+
+---
+
+## Events 事件
+
+| 事件名 | 回调参数 | 说明 |
+|--------|----------|------|
+| page-change | page: Number | 页码变化时触发 |
+| size-change | size: Number | 每页条数变化时触发 |
+| update:pagination | pagination: Object | 分页信息更新时触发 |
+| action-click | button, row, index | 操作按钮点击时触发 |
+| validate-error | error | 表单验证失败时触发 |
+| selection-change | selection: Array | 选择项变化时触发 |
+| async-load | { field, row, index, options } | 异步选项加载完成时触发 |
+| linkage-change | { sourceField, targetField, value, row, index, options } | 联动数据变化时触发 |
+
+### 使用示例
+
+```vue
+<DtTable
+  :grid-options="gridOptions"
+  @action-click="handleActionClick"
+  @selection-change="handleSelectionChange"
+  @page-change="handlePageChange"
+/>
+```
+
+```javascript
+methods: {
+  handleActionClick(button, row, index) {
+    console.log('点击了按钮:', button.text)
+    console.log('行数据:', row)
+    console.log('行索引:', index)
+  },
+  handleSelectionChange(selection) {
+    console.log('选中的数据:', selection)
+  },
+  handlePageChange(page) {
+    console.log('当前页:', page)
+  }
+}
+```
+
+---
+
+## 高级功能
+
+### 1. 多选列
+
+在 `columns` 中添加 `field: 'selection'` 即可启用多选：
+
+```javascript
+columns: [
+  { field: 'selection', title: '' },
+  { field: 'name', title: '姓名' },
+  // ...
+]
+```
+
+### 2. 异步加载选项
+
+适用于 select 编辑器，动态加载选项数据：
+
+```javascript
+{
+  field: 'city',
+  title: '城市',
+  editor: 'select',
+  asyncOptions: {
+    immediate: true,  // 是否立即加载
+    async loadData(row) {
+      // row 为当前行数据，可据此加载不同选项
+      const { data } = await api.getCityList({ provinceId: row.provinceId })
+      return data.map(item => ({
+        label: item.cityName,
+        value: item.cityId
+      }))
+    }
+  }
+}
+```
+
+### 3. 联动配置
+
+当一个字段变化时，自动加载另一个字段的选项：
+
+```javascript
+{
+  field: 'province',
+  title: '省份',
+  editor: 'select',
+  options: [
+    { label: '北京', value: 'beijing' },
+    { label: '广东', value: 'guangdong' }
+  ],
+  linkage: {
+    targetField: 'city',  // 联动的目标字段
+    clearTarget: true,    // 联动时是否清空目标字段（默认 true）
+    async method(value, row, type) {
+      // value: 当前字段值
+      // row: 当前行数据
+      const { data } = await api.getCityList({ province: value })
+      return data.map(item => ({
+        label: item.cityName,
+        value: item.cityId
+      }))
+    }
+  }
+},
+{
+  field: 'city',
+  title: '城市',
+  editor: 'select',
+  options: []  // 选项由联动动态填充
+}
+```
+
+### 4. API 分页请求
+
+传入 `apiFunction` 后自动启用分页：
+
+```vue
+<DtTable
+  :grid-options="gridOptions"
+  :api-function="getList"
+  :api-params="{ type: 1 }"
+  :immediate="true"
+  :pagination.sync="pagination"
+  @page-change="handlePageChange"
+  @size-change="handleSizeChange"
+/>
+```
+
+```javascript
+import { getList } from '@/api/list'
+
+export default {
+  data() {
+    return {
+      pagination: {
+        currentPage: 1,
+        pageSize: 10
+      }
+    }
+  },
+  methods: {
+    // API 函数需要返回 { list: [], count: Number }
+    getList
+  }
+}
+```
+
+### 5. 自定义渲染（h 函数）
+
+使用 Vue 的 `h` 函数渲染复杂内容：
+
+```javascript
+{
+  field: 'action',
+  title: '操作',
+  editor: 'custom',
+  render: ({ row, h }) => {
+    return h('div', null, [
+      h('el-button', {
+        props: { type: 'text', size: 'small' },
+        on: {
+          click: () => console.log('查看', row)
+        }
+      }, '查看'),
+      h('el-button', {
+        props: { type: 'text', size: 'small' },
+        style: { color: '#F56C6C' },
+        on: {
+          click: () => console.log('删除', row)
+        }
+      }, '删除')
+    ])
+  }
+}
+```
+
+### 6. 表单验证
+
+为列配置 `rules` 属性启用验证：
+
+```javascript
+{
+  field: 'name',
+  title: '姓名',
+  editor: 'input',
+  rules: [
+    { required: true, message: '请输入姓名', trigger: 'blur' },
+    { min: 2, max: 10, message: '长度在 2 到 10 个字符', trigger: 'blur' }
+  ]
+}
+```
+
+---
+
+## 完整示例
+
+```vue
+<template>
+  <div>
+    <el-button @click="handleAdd">新增</el-button>
+    <el-button @click="handleBatchDelete">批量删除</el-button>
+    <el-button @click="handleSubmit">提交</el-button>
+
+    <DtTable
+      ref="dtTable"
+      :grid-options="gridOptions"
+      :api-function="getList"
+      :api-params="queryParams"
+      :pagination.sync="pagination"
+      :immediate="true"
+      @selection-change="handleSelectionChange"
+    />
+  </div>
+</template>
+
+<script>
+import DtTable from '@/components/global/DtTable'
+import { getList } from '@/api'
+
+export default {
+  components: { DtTable },
+  data() {
+    const self = this
+    return {
+      queryParams: { type: 1 },
+      pagination: { currentPage: 1, pageSize: 10 },
+      selectedRows: [],
+      gridOptions: {
+        columns: [
+          { field: 'selection', title: '' },
+          { field: 'id', title: 'ID', attrs: { width: 80 } },
+          {
+            field: 'name',
+            title: '姓名',
+            editor: 'input',
+            rules: [
+              { required: true, message: '请输入姓名', trigger: 'blur' }
+            ],
+            attrs: { minWidth: 120 }
+          },
+          {
+            field: 'status',
+            title: '状态',
+            editor: 'custom',
+            render: ({ row, h }) => {
+              return h('el-tag', {
+                props: { type: row.status === 1 ? 'success' : 'danger' }
+              }, row.status === 1 ? '启用' : '禁用')
+            },
+            attrs: { width: 100 }
+          },
+          {
+            field: 'type',
+            title: '类型',
+            editor: 'select',
+            options: [
+              { label: '类型A', value: 1 },
+              { label: '类型B', value: 2 }
+            ],
+            attrs: { width: 120 }
+          },
+          {
+            field: 'quantity',
+            title: '数量',
+            editor: 'input-number',
+            min: 0,
+            max: 999,
+            precision: 0,
+            unit: '个',
+            attrs: { width: 150 }
+          },
+          {
+            field: 'enable',
+            title: '启用',
+            editor: 'switch',
+            attrs: { width: 80 }
+          }
+        ],
+        actions: [
+          {
+            text: '编辑',
+            type: 'text',
+            click(row, index) {
+              self.handleEdit(row)
+            }
+          },
+          {
+            text: '删除',
+            type: 'text',
+            style: { color: '#F56C6C' },
+            show: (row) => row.status !== 1,
+            click(row, index) {
+              self.handleDelete(row, index)
+            }
+          }
+        ],
+        actionWidth: '150px',
+        scroll: { y: 500 }
+      }
+    }
+  },
+  methods: {
+    getList,
+
+    handleSelectionChange(selection) {
+      this.selectedRows = selection
+    },
+
+    handleAdd() {
+      const data = this.gridOptions.data || []
+      data.push({ id: Date.now(), name: '', status: 1, type: 1, quantity: 0, enable: true })
+      this.gridOptions.data = [...data]
+    },
+
+    handleEdit(row) {
+      console.log('编辑:', row)
+    },
+
+    handleDelete(row, index) {
+      this.$confirm('确认删除?').then(() => {
+        this.gridOptions.data.splice(index, 1)
+      })
+    },
+
+    handleBatchDelete() {
+      const selection = this.$refs.dtTable.getSelection()
+      if (selection.length === 0) {
+        this.$message.warning('请先选择数据')
+        return
+      }
+      // 批量删除逻辑
+    },
+
+    async handleSubmit() {
+      try {
+        await this.$refs.dtTable.validate()
+        console.log('提交数据:', this.gridOptions.data)
+      } catch (error) {
+        console.log('验证失败')
+      }
+    }
+  }
+}
+</script>
+```
+
+---
+
+## 注意事项
+
+1. **数据响应式**：`gridOptions.data` 需要保持响应式，修改时建议使用展开运算符 `[...data]` 触发更新。
+
+2. **字段唯一性**：每列的 `field` 必须唯一，`selection` 为保留字段用于多选列。
+
+3. **验证规则**：`rules` 遵循 Element UI 的表单验证规则格式。
+
+4. **h 函数使用**：render 函数中通过参数 `h` 获取，无需手动导入。
+
+5. **异步选项**：使用 `asyncOptions` 时，选项数据会缓存在行数据的 `_asyncOptions` 中。