@daflow-ui/ui-table

展示型 Table 组件，使用 DfTable 和 DfTableColumn 进行声明式列定义。

Installation

pnpm add @daflow-ui/ui-table

Usage

全局引入样式：

import '@daflow-ui/ui-table/style.css';

核心规则

• 只支持 DfTable + DfTableColumn 声明式列定义，不提供 columns prop。
• DfTable 负责表格级能力，如数据源、空态、滚动区域、固定表头和行级配置。
• DfTableColumn 负责列声明，如取值路径、对齐方式、宽度、固定列和自定义渲染。
• prop 是默认取值路径，不是必填；提供 default slot 后，最终单元格内容由 slot 接管。
• label 是默认表头文案；提供 header slot 后，表头内容由 slot 接管。
• fixed 是列级能力；maxHeight 是表格级能力。
• rowClassName 的函数签名是单个上下文对象：({ row, rowIndex }) => string | undefined。

基础列定义

<script setup lang="ts">
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, song: '夜航星', artist: '不才', amount: '¥3,200.00' },
  { id: 2, song: '如常', artist: '房东的猫', amount: '¥2,480.00' }
];
</script>

<template>
  <DfTable :data="rows" row-key="id">
    <DfTableColumn prop="song" label="歌曲" min-width="180px" />
    <DfTableColumn prop="artist" label="艺人" min-width="160px" />
    <DfTableColumn prop="amount" label="分成金额" width="140px" align="right" />
  </DfTable>
</template>

自定义单元格，不依赖 prop

<script setup lang="ts">
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, name: '不才', email: '[email protected]', status: '启用' },
  { id: 2, name: '房东的猫', email: '[email protected]', status: '停用' }
];
</script>

<template>
  <DfTable :data="rows" row-key="id">
    <DfTableColumn label="艺人信息" min-width="220px">
      <template #default="{ row }">
        <div>
          <strong>{{ row.name }}</strong>
          <div>{{ row.email }}</div>
        </div>
      </template>
    </DfTableColumn>
    <DfTableColumn prop="status" label="状态" width="120px" align="center" />
  </DfTable>
</template>

自定义表头和自定义单元格

<script setup lang="ts">
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, song: '夜航星', channel: 'QQ 音乐', amount: '¥3,200.00' },
  { id: 2, song: '如常', channel: '网易云音乐', amount: '¥2,480.00' }
];
</script>

<template>
  <DfTable :data="rows" row-key="id">
    <DfTableColumn prop="song" min-width="220px">
      <template #header>
        <span>歌曲信息</span>
      </template>
      <template #default="{ row }">
        <strong>{{ row.song }}</strong>
        <div>{{ row.channel }}</div>
      </template>
    </DfTableColumn>
    <DfTableColumn prop="amount" label="累计分成" width="160px" align="right" />
  </DfTable>
</template>

行级 class 扩展

<script setup lang="ts">
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, song: '夜航星', artist: '不才', amount: '¥3,200.00', status: 'done' },
  { id: 2, song: '如常', artist: '房东的猫', amount: '¥2,480.00', status: 'pending' }
];

const getRowClassName = ({ row }: { row: { status: string }; rowIndex: number }) => {
  return row.status === 'pending' ? 'row-pending' : undefined;
};
</script>

<template>
  <DfTable :data="rows" row-key="id" :row-class-name="getRowClassName">
    <DfTableColumn prop="song" label="歌曲" min-width="180px" />
    <DfTableColumn prop="artist" label="艺人" min-width="160px" />
    <DfTableColumn prop="amount" label="分成金额" width="140px" align="right" />
  </DfTable>
</template>

路径取值

prop 支持点路径和数组下标路径：

<script setup lang="ts">
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, song: '夜航星', album: { title: '夜航星' }, artists: [{ name: '不才' }] },
  { id: 2, song: '如常', album: { title: '柔软' }, artists: [{ name: '房东的猫' }] }
];
</script>

<template>
  <DfTable :data="rows" row-key="id">
    <DfTableColumn prop="song" label="歌曲" />
    <DfTableColumn prop="album.title" label="专辑" />
    <DfTableColumn prop="artists[0].name" label="主艺人" />
  </DfTable>
</template>

固定列与固定表头

<script setup lang="ts">
import { DfButton } from '@daflow-ui/ui-button';
import { DfTable, DfTableColumn } from '@daflow-ui/ui-table';

const rows = [
  { id: 1, song: '夜航星', channel: 'QQ 音乐', publishDate: '2026-03-01' },
  { id: 2, song: '如常', channel: '网易云音乐', publishDate: '2026-03-05' }
];

const handleView = (row: { id: number }) => {
  console.log('view row', row.id);
};
</script>

<template>
  <DfTable :data="rows" row-key="id" max-height="240px">
    <DfTableColumn prop="song" label="歌曲" min-width="220px" fixed="left" />
    <DfTableColumn prop="channel" label="渠道" min-width="180px" />
    <DfTableColumn prop="publishDate" label="上架日期" width="160px" align="center" />
    <DfTableColumn label="操作" width="160px" align="right" fixed="right">
      <template #default="{ row }">
        <DfButton size="sm" variant="outline" @click="handleView(row)">
          查看
        </DfButton>
      </template>
    </DfTableColumn>
  </DfTable>
</template>

易错点

• rowClassName 的函数签名是单个上下文对象，不是 (row, rowIndex) => ...
• maxHeight 是表格级能力，控制内容区滚动和固定表头；fixed 是列级能力，控制左右固定列
• 即使已经配置了 fixed，当列宽总和未超出容器宽度时，视觉上也可能与普通列一致；发生横向溢出后，固定列效果会更明显

API

DfTable Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | data | T[] | [] | 表格数据 | | striped | boolean | false | 是否开启斑马纹 | | emptyText | string | '暂无数据' | 空态文案 | | maxHeight | number \| string | - | 表格级能力；超出后内容区域滚动，表头保持固定 | | rowClassName | string \| ({ row, rowIndex }) => string \| undefined | - | 行类名或行类名回调，不影响列定义本身 | | rowKey | string \| ((row, rowIndex) => string \| number) | - | 行唯一标识字段路径或解析函数；未传时回退为 rowIndex |

DfTable Slots

| 插槽 | 参数 | 说明 | |------|------|------| | default | - | 传入一个或多个 DfTableColumn，定义列结构 |

DfTableColumn Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | prop | string | - | 默认取值路径，支持点路径和数组下标路径；提供 default slot 后不是必填 | | label | string | - | 默认表头文案；提供 header slot 时会被覆盖 | | align | 'left' \| 'center' \| 'right' | 'left' | 列级对齐方式，同时作用于表头和 body | | width | number \| string | - | 列宽，传 number 时自动补全为 px | | minWidth | number \| string | - | 最小列宽，传 number 时自动补全为 px | | fixed | 'left' \| 'right' | - | 列级能力；固定列方向，作用于整列 | | className | string | - | 当前列 body 单元格的额外类名，不影响表头 | | columnKey | string | - | 列唯一标识 |

DfTableColumn Slots

| 插槽 | 参数 | 说明 | |------|------|------| | default | { row, rowIndex, column } | 自定义 body 单元格内容；应优先按需读取 row | | header | - | 自定义表头内容 |

Current Scope

当前版本聚焦展示型表格，支持：

• DfTable + DfTableColumn 声明式列定义
• 空态、斑马纹、行 hover 高亮
• 列对齐、宽度、最小宽度
• 自定义表头和自定义单元格
• row-key 字段路径 / 函数
• row-class-name
• max-height 固定表头滚动
• 左右固定列

不再保留 columns prop，列定义统一通过 DfTableColumn 声明。