ylwl-cpscoms 1.1.0 → 1.3.0

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

@@ -1,819 +0,0 @@
-# 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` 中。