@daflow-ui/ui-table

@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: '[e-mail]', status: '启用' },
  { id: 2, name: '房东的猫', email: '[e-mail]', 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 声明。