# ZmTable

`ZmTable` 是基于 Element Plus `el-table` / `el-table-column` 封装的业务表格组件，主要补了这些能力：

- 默认统一表格视觉样式。
- 自动按内容计算列宽，并支持全局限制最大宽度。
- 表格级 `align` 统一控制列对齐方式。
- 列头内置排序、筛选按钮，但排序和筛选逻辑交给调用方自定义。
- 操作列可以开启列设置面板，支持列显隐、固定左/右、拖拽排序。
- 支持多级表头，子级表头只能在自己的父级分组内排序。
- 样式通过少量 CSS 变量开放给外部调整。

## 文件说明

| 文件 | 作用 |
| --- | --- |
| `index.vue` | 表格主体，负责数据、默认样式、列配置收集、列顺序/显隐/固定渲染。 |
| `ZmTableColumn.vue` | 列组件，负责列头按钮、排序、筛选、操作列设置入口、列宽计算。 |
| `ZmTableColumnSettingTree.vue` | 列设置面板里的递归树，负责拖拽排序、显隐、固定按钮。 |
| `token.ts` | 表格内部依赖注入类型和 key。 |
| `useTableComponents.ts` | 给 TS 泛型使用的便捷导出。 |

## 基础用法

推荐在页面里通过 `useTableComponents<T>()` 获取泛型组件，这样 `prop`、`row` 会更容易获得类型提示。

```vue
<script setup lang="ts">
import { useTableComponents } from '@/components/ZmTable/useTableComponents'

interface ListItem {
  id: number
  name: string
  status: string
}

const loading = ref(false)
const list = ref<ListItem[]>([])

const { ZmTable, ZmTableColumn } = useTableComponents<ListItem>()
</script>

<template>
  <ZmTable :data="list" :loading="loading">
    <ZmTableColumn type="index" label="序号" :width="60" />
    <ZmTableColumn prop="name" label="名称" />
    <ZmTableColumn prop="status" label="状态">
      <template #default="{ row }">
        <el-tag>{{ row.status }}</el-tag>
      </template>
    </ZmTableColumn>
  </ZmTable>
</template>
```

也可以直接用小写组件名：

```vue
<zm-table :data="list" :loading="loading">
  <zm-table-column prop="name" label="名称" />
</zm-table>
```

## ZmTable Props

`ZmTable` 继承大部分 Element Plus `TableProps`，下面是额外增加或重点关注的属性。

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `data` | `T[]` | 必填 | 表格数据。 |
| `loading` | `boolean` | 必填 | 表格 loading 状态。 |
| `align` | `'left' \| 'center' \| 'right'` | `'center'` | 全局列对齐方式。普通列会使用它；开启排序、筛选、操作列时，列头会优先左对齐。 |
| `columnMaxWidth` | `number` | `360` | 自动计算列宽时的最大宽度。 |
| `customClass` | `boolean` | `false` | 为 `true` 时不挂载默认 `.zm-table` class，也就不会使用组件默认样式变量。 |
| `showBorder` | `boolean` | `false` | 控制组件自己的边框显示样式。 |
| `showOverflowTooltip` | `boolean` | `true` | 继承自 Element Plus。想让文字换行时传 `false`，再配合页面 CSS 覆盖 `.cell` 的换行样式。 |

组件内部默认还会给 Element Plus 表格设置这些值：

```ts
{
  size: 'default',
  stripe: true,
  border: true,
  highlightCurrentRow: true,
  showOverflowTooltip: true,
  scrollbarAlwaysOn: true,
  tooltipOptions: {
    popperClass: 'max-w-120'
  }
}
```

## ZmTableColumn Props

`ZmTableColumn` 继承大部分 Element Plus `TableColumnCtx`，下面是额外增加或重点关注的属性。

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `prop` | `keyof T \| string` | - | 字段名，也会作为列设置 key 的优先来源。 |
| `action` | `boolean` | `false` | 标记为操作列，并在表头显示列设置按钮。操作列本身不会进入列设置列表。 |
| `hideInColumnSettings` | `boolean` | `false` | 不显示在列设置面板里，适合序号列、选择列等固定功能列。 |
| `isParent` | `boolean` | `false` | 标记当前列是多级表头父级。需要控制子级列排序/显隐/固定时必须加。 |
| `zmSortable` | `boolean` | `false` | 显示排序按钮。组件只维护/展示排序状态，具体排序逻辑由调用方处理。 |
| `zmFilterable` | `boolean` | `false` | 显示筛选按钮和 popover。筛选内容和筛选逻辑由调用方通过 `#filter` 自定义。 |
| `sortOrder` | `'asc' \| 'desc' \| null` | - | 外部受控排序状态。传了这个值之后，组件不会自己保存排序状态。 |
| `defaultSortOrder` | `'asc' \| 'desc' \| null` | `null` | 非受控模式下的默认排序状态。 |
| `zmSortMethod` | `(prop, order) => void` | - | 点击排序按钮后调用。 |
| `filterActive` | `boolean` | - | 强制控制筛选按钮激活态。不传时根据 `filterModelValue` 自动判断。 |
| `filterModelValue` | `any` | - | 筛选值，可用 `v-model:filter-model-value` 双向绑定。 |
| `realValue` | `(...args) => any` | - | 获取真实展示值。自动算宽时会优先使用它；配合 `coverFormatter` 时也会作为 formatter。 |
| `coverFormatter` | `boolean` | `false` | 为 `true` 时，把 `realValue` 作为 Element Plus 的 `formatter` 使用。 |

## 排序

开启 `zm-sortable` 后，表头只显示排序按钮和排序状态图标：

- 未排序：`i-lucide:arrow-up-down`
- 升序：`i-lucide:arrow-up-narrow-wide`
- 降序：`i-lucide:arrow-down-wide-narrow`

点击顺序是：

```txt
null -> asc -> desc -> null
```

非受控用法：

```vue
<ZmTableColumn prop="meetingDate" label="会议日期" zm-sortable :zm-sort-method="handleSort" />
```

```ts
function handleSort(prop: string, order: 'asc' | 'desc' | null) {
  query.value.sortField = prop
  query.value.sortOrder = order
  getList()
}
```

受控用法：

```vue
<ZmTableColumn
  prop="meetingDate"
  label="会议日期"
  zm-sortable
  v-model:sort-order="meetingDateOrder"
  @sort-change="handleSortChange"
/>
```

```ts
const meetingDateOrder = ref<'asc' | 'desc' | null>(null)

function handleSortChange(payload: { prop: string; order: 'asc' | 'desc' | null }) {
  query.value.sortField = payload.prop
  query.value.sortOrder = payload.order
  getList()
}
```

## 筛选

开启 `zm-filterable` 后，表头只显示筛选按钮。popover 里面展示什么、怎么过滤，都由调用方写在 `#filter` 插槽里。

```vue
<ZmTableColumn
  prop="status"
  label="状态"
  zm-filterable
  v-model:filter-model-value="query.status"
  @filter-visible-change="handleFilterVisibleChange"
>
  <template #filter="{ filterModelValue, updateFilterModelValue, close }">
    <div class="p-2">
      <el-select
        :model-value="filterModelValue"
        placeholder="请选择状态"
        clearable
        class="w-full"
        @update:model-value="updateFilterModelValue"
      >
        <el-option label="启用" value="enable" />
        <el-option label="停用" value="disable" />
      </el-select>

      <div class="mt-2 flex justify-end gap-2">
        <el-button size="small" @click="updateFilterModelValue(undefined)">清空</el-button>
        <el-button
          size="small"
          type="primary"
          @click="
            () => {
              handleQuery()
              close()
            }
          "
        >
          确定
        </el-button>
      </div>
    </div>
  </template>
</ZmTableColumn>
```

`#filter` 插槽会收到这些常用参数：

| 参数                            | 说明                                           |
| ------------------------------- | ---------------------------------------------- |
| `prop`                          | 当前列字段名。                                 |
| `filterModelValue`              | 当前筛选值。                                   |
| `updateFilterModelValue(value)` | 更新筛选值，会触发 `update:filterModelValue`。 |
| `close()`                       | 关闭 popover。                                 |
| `setVisible(visible)`           | 手动控制 popover 显隐。                        |

筛选按钮是否高亮：

- 传了 `filterActive` 时，以 `filterActive` 为准。
- 没传 `filterActive` 时，组件会根据 `filterModelValue` 是否有值自动判断。

## 操作列和列设置

给操作列加 `action`，表头会显示设置按钮。

```vue
<ZmTable :data="list" :loading="loading">
  <ZmTableColumn prop="name" label="名称" />
  <ZmTableColumn prop="status" label="状态" />

  <ZmTableColumn label="操作" width="120" fixed="right" action>
    <template #default="{ row }">
      <el-button link type="primary" @click="handleEdit(row)">编辑</el-button>
    </template>
  </ZmTableColumn>
</ZmTable>
```

列设置面板支持：

- 拖拽调整列顺序。
- 显示 / 隐藏列。
- 固定到左侧 / 固定到右侧 / 取消固定。
- 重置为初始列配置。

列设置 key 的优先级：

```txt
columnKey -> prop -> type -> label -> column-${index}
```

建议动态列、同名列、没有 `prop` 的列都手动传 `column-key`，避免 key 不稳定。

```vue
<ZmTableColumn column-key="custom-action" label="自定义列">
  ...
</ZmTableColumn>
```

## 多级表头

Element Plus 原生多级表头可以直接写：

```vue
<ZmTableColumn label="累计" is-parent>
  <ZmTableColumn prop="totalGasInjection" label="注气量" />
  <ZmTableColumn prop="totalWaterInjection" label="注水量" />
  <ZmTableColumn prop="totalPower" label="用电量" />
</ZmTableColumn>
```

如果想让列设置面板识别并控制子级表头，需要给父级列加 `is-parent`。

子级列拖拽时只能在自己的父级分组内排序。比如 `累计` 下面有三个子列，这三个子列只能在 `累计` 里面互相调整，不能被拖到其他父级外面。

## 对齐优先级

普通列对齐优先级：

```txt
列自己的 align -> ZmTable 的 align -> 默认 center
```

开启了下面任意能力时，表头会优先左对齐，方便标题和按钮同时展示：

- `action`
- `zm-sortable`
- `zm-filterable`

示例：

```vue
<ZmTable :data="list" :loading="loading" align="right">
  <ZmTableColumn prop="amount" label="金额" />
  <ZmTableColumn prop="name" label="名称" align="left" />
  <ZmTableColumn prop="date" label="日期" zm-sortable />
</ZmTable>
```

上面例子里：

- `amount` 使用表格全局 `right`。
- `name` 使用列自己的 `left`。
- `date` 因为开启了排序，表头优先 `left`。

## 自动列宽

每个有 `prop` 的列会根据表头和当前数据自动计算 `minWidth`。

计算逻辑大致是：

- 取表头文字宽度。
- 取当前页数据里该列内容的最大文字宽度。
- 如果列头有排序/筛选按钮，会额外加上按钮宽度。
- 最终宽度不会超过 `ZmTable` 的 `columnMaxWidth`，默认是 `360`。

```vue
<ZmTable :data="list" :loading="loading" :column-max-width="480">
  <ZmTableColumn prop="description" label="描述" />
</ZmTable>
```

如果展示值不是原始字段值，建议传 `real-value`，这样自动宽度会按真实显示值计算。

```vue
<ZmTableColumn
  prop="meetingDate"
  label="会议日期"
  cover-formatter
  :real-value="(row) => dayjs(row.meetingDate).format('YYYY-MM-DD')"
/>
```

## 插槽

`ZmTable` 会透传 Element Plus 表格的大部分插槽，默认插槽用于放 `ZmTableColumn`。

`ZmTableColumn` 会透传 Element Plus 列的大部分插槽：

```vue
<ZmTableColumn prop="status" label="状态">
  <template #default="{ row }">
    <el-tag>{{ row.status }}</el-tag>
  </template>
</ZmTableColumn>
```

如果自定义了 `#header`，组件内置的排序、筛选、设置按钮不会自动渲染，需要调用方自己处理表头内容。

## Expose

`ZmTable` 暴露了内部 Element Plus 表格实例：

```vue
<script setup lang="ts">
const tableRef = ref()

function clearSelection() {
  tableRef.value?.elTableRef?.clearSelection()
}
</script>

<template>
  <ZmTable ref="tableRef" :data="list" :loading="loading" />
</template>
```

## CSS 变量

默认样式挂在 `.zm-table` 上。外部可以通过 class 覆盖变量：

```vue
<ZmTable class="meeting-table" :data="list" :loading="loading" />
```

```scss
.meeting-table {
  --zm-table-font-size: 13px;
  --zm-table-header-bg: #f3f6fb;
  --zm-table-cell-height: 44px;
}
```

### 表格变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--zm-table-font-family` | `inherit` | 表格字体。 |
| `--zm-table-font-size` | `12px` | 表格基础字号。 |
| `--zm-table-text-color` | `#40546d` | 普通文字颜色。 |
| `--zm-table-strong-text-color` | `#24364d` | body 单元格文字颜色。 |
| `--zm-table-row-font-weight` | `500` | body 单元格字重。 |
| `--zm-table-bg` | `var(--el-bg-color)` | 表格背景。 |
| `--zm-table-border-color` | `#e7edf4` | 表格外边框颜色。 |
| `--zm-table-radius` | `10px` | 表格圆角。 |
| `--zm-table-header-bg` | `var(--el-fill-color-extra-light, #f7f9fc)` | 表头背景。 |
| `--zm-table-header-text-color` | `var(--el-text-color-secondary, #6b7f99)` | 表头文字颜色。 |
| `--zm-table-header-border-color` | `var(--zm-table-border-color)` | 表头边框颜色。 |
| `--zm-table-header-cell-height` | `36px` | 普通表头高度。 |
| `--zm-table-header-group-cell-height` | `42px` | 多级表头父级高度。 |
| `--zm-table-header-font-size` | `var(--zm-table-font-size)` | 表头字号。 |
| `--zm-table-header-font-weight` | `600` | 表头字重。 |
| `--zm-table-header-line-height` | `16px` | 表头行高。 |
| `--zm-table-header-icon-btn-size` | `18px` | 表头图标按钮尺寸。 |
| `--zm-table-header-icon-btn-color` | `#8aa0b8` | 表头图标默认颜色。 |
| `--zm-table-header-icon-btn-radius` | `4px` | 表头图标按钮圆角。 |
| `--zm-table-header-icon-btn-hover-color` | `var(--el-color-primary)` | 表头图标 hover 颜色。 |
| `--zm-table-header-icon-btn-hover-bg` | `var(--el-color-primary-light-9)` | 表头图标 hover 背景。 |
| `--zm-table-header-icon-btn-active-color` | `var(--zm-table-header-icon-btn-hover-color)` | 表头图标激活颜色。 |
| `--zm-table-header-icon-btn-active-bg` | `var(--zm-table-header-icon-btn-hover-bg)` | 表头图标激活背景。 |
| `--zm-table-header-icon-size` | `16px` | 表头图标尺寸。 |
| `--zm-table-row-border-color` | `#edf2f7` | body 单元格边框颜色。 |
| `--zm-table-stripe-bg` | `#fcfdff` | 斑马纹背景。 |
| `--zm-table-hover-bg` | `#f5f9ff` | 行 hover 背景。 |
| `--zm-table-current-bg` | `#eef6ff` | 当前行背景。 |
| `--zm-table-cell-height` | `38px` | body 单元格高度。 |
| `--zm-table-cell-padding-x` | `13px` | body 单元格左右 padding。 |
| `--zm-table-cell-first-padding-left` | `calc(var(--zm-table-cell-padding-x) + 3px)` | 每行第一个单元格左 padding。 |
| `--zm-table-cell-last-padding-right` | `var(--zm-table-cell-first-padding-left)` | 每行最后一个单元格右 padding。 |
| `--zm-table-cell-line-height` | `18px` | body 单元格行高。 |
| `--zm-table-empty-min-height` | `148px` | 空状态最小高度。 |
| `--zm-table-empty-bg` | `var(--zm-table-bg)` | 空状态背景。 |
| `--zm-table-empty-text-font-size` | `var(--zm-table-font-size)` | 空状态文字字号。 |
| `--zm-table-empty-text-color` | `var(--el-text-color-secondary)` | 空状态文字颜色。 |
| `--zm-table-scrollbar-size` | `7px` | 滚动条尺寸。 |
| `--zm-table-scrollbar-thumb-bg` | `#b8c5d6` | 滚动条滑块颜色。 |

### 列设置变量

列设置面板 popover 使用 `.zm-table-column-setting-popper`，可以全局覆盖，也可以在页面样式中覆盖。

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--zm-table-column-setting-font-size` | `var(--zm-table-font-size, 12px)` | 设置面板字号。 |
| `--zm-table-column-setting-text-color` | `var(--el-text-color-regular)` | 设置面板文字颜色。 |
| `--zm-table-column-setting-border-color` | `var(--el-border-color)` | 设置面板分割线颜色。 |
| `--zm-table-column-setting-hover-bg` | `var(--el-fill-color-lighter)` | 设置项 hover 背景。 |
| `--zm-table-column-setting-radius` | `6px` | 设置项圆角。 |
| `--zm-table-column-setting-gap` | `4px` | 设置项纵向间距。 |
| `--zm-table-column-setting-max-height` | `360px` | 设置面板最大高度。 |
| `--zm-table-column-setting-row-height` | `32px` | 一级设置项高度。 |
| `--zm-table-column-setting-child-row-height` | `30px` | 子级设置项高度。 |
| `--zm-table-column-setting-item-font-weight` | `400` | 普通设置项字重。 |
| `--zm-table-column-setting-group-font-weight` | `600` | 分组设置项字重。 |
| `--zm-table-column-setting-icon-btn-size` | `22px` | 设置项图标按钮尺寸。 |
| `--zm-table-column-setting-icon-size` | `15px` | 设置项图标尺寸。 |
| `--zm-table-column-setting-icon-color` | `#8aa0b8` | 设置项图标默认颜色。 |
| `--zm-table-column-setting-icon-active-color` | `var(--el-color-primary)` | 设置项图标激活颜色。 |
| `--zm-table-column-setting-icon-active-bg` | `var(--el-color-primary-light-9)` | 设置项图标激活背景。 |
| `--zm-table-column-setting-ghost-bg` | `var(--el-color-primary-light-9)` | 拖拽占位背景。 |
| `--zm-table-column-setting-ghost-opacity` | `0.55` | 拖拽占位透明度。 |

### 自动宽度测量变量

自动算宽时会创建隐藏文本节点测量文字宽度，可以用这两个变量控制测量字体：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--zm-table-column-width-measure-font-size` | `--zm-table-font-size` 或当前表格字号 | 测量文字宽度时的字号。 |
| `--zm-table-column-width-measure-font-family` | 当前表格字体或 `Noto Sans SC` | 测量文字宽度时的字体。 |

## 文字换行

默认 `showOverflowTooltip` 是 `true`，单元格会走 Element Plus 的溢出 tooltip。想关闭 tooltip 并让内容自动换行，可以这样写：

```vue
<ZmTable class="wrap-table" :data="list" :loading="loading" :show-overflow-tooltip="false">
  <ZmTableColumn prop="description" label="描述" />
</ZmTable>
```

```scss
.wrap-table {
  :deep(.el-table__body .cell) {
    overflow: visible;
    text-overflow: initial;
    white-space: normal;
    word-break: break-word;
  }
}
```

## 注意事项

- 列设置只识别 `ZmTableColumn`，不要在默认插槽里混入其他会渲染成列的组件。
- 多级表头想被设置面板递归识别，需要在父级列上加 `is-parent`。
- 动态列建议手动传 `column-key`，否则列顺序和显隐状态可能因为 key 变化而重置。
- 排序和筛选按钮只负责 UI 状态，不会自动修改 `data` 或请求接口。
- 如果传了自定义 `#header`，内置排序、筛选、设置按钮不会出现。
- `customClass=true` 会关闭默认 `.zm-table` 样式，相关 CSS 变量也不会自动生效。