列宽拖拽

列宽拖拽适合字段很多、内容长短差异大、用户希望现场微调布局的业务表格。它延续了接近 ant-design-vue 的字段心智，但作为内建能力提供。

在线示例

把鼠标移到表头分隔线上左右拖动。「分类」列限制在 100–280px 之间，resizeColumn 事件把新宽度回写到列配置。

在 Playground 中编辑

<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import { VTable } from '@vtable-guild/vtable-guild'
import type { ColumnType } from '@vtable-guild/vtable-guild'

interface DocRow {
  key: string
  title: string
  category: string
  updatedBy: string
  updatedAt: string
}

// resizable + minWidth/maxWidth 控制可拖拽范围；
// 拖拽需要一个确定的表格宽度，所以固定 tableLayout 并给列写死初始 width。
// 这里用 ColumnType[] 而不是 TableColumnsType，因为下面要按 key 回写 width——
// TableColumnsType 还包含多级表头和 EXPAND_COLUMN 这类哨兵，没有 key/width 字段。
// shallowRef + 整体替换：列配置里有 customRender 之类的函数，深层响应式没有意义。
const columns = shallowRef<ColumnType<DocRow>[]>([
  { title: '文档', dataIndex: 'title', key: 'title', width: 320, resizable: true, minWidth: 160 },
  {
    title: '分类',
    dataIndex: 'category',
    key: 'category',
    width: 160,
    resizable: true,
    minWidth: 100,
    maxWidth: 280,
  },
  { title: '最近编辑', dataIndex: 'updatedBy', key: 'updatedBy', width: 140, resizable: true },
  { title: '更新时间', dataIndex: 'updatedAt', key: 'updatedAt', width: 180 },
])

const dataSource: DocRow[] = [
  {
    key: '1',
    title: '三层主题覆盖设计说明',
    category: '架构',
    updatedBy: '陈嘉',
    updatedAt: '2026-07-14 10:22',
  },
  {
    key: '2',
    title: '虚拟滚动行高测量方案',
    category: '性能',
    updatedBy: '苏晚',
    updatedAt: '2026-07-12 16:40',
  },
  {
    key: '3',
    title: 'antdv 预设 token 对照表',
    category: '主题',
    updatedBy: '周野',
    updatedAt: '2026-07-09 09:05',
  },
  {
    key: '4',
    title: '筛选面板交互边界',
    category: '交互',
    updatedBy: '林悦',
    updatedAt: '2026-07-02 14:18',
  },
]

const lastResize = ref('（把鼠标移到表头分隔线上左右拖动）')

function handleResizeColumn(column: ColumnType<DocRow>, width: number) {
  // 宽度回写到列配置，拖拽结果才会持久生效
  columns.value = columns.value.map((item) => (item.key === column.key ? { ...item, width } : item))
  lastResize.value = `${String(column.key)} → ${Math.round(width)}px`
}
</script>

<template>
  <VTable
    row-key="key"
    bordered
    table-layout="fixed"
    :columns="columns"
    :data-source="dataSource"
    @resize-column="handleResizeColumn"
  />
  <p style="margin-top: 12px; font-size: 13px; opacity: 0.7">最近一次调整：{{ lastResize }}</p>
</template>

基础示例

在列上设置 resizable: true 即可。width 可以是像素数值、auto、百分比等 CSS 宽度，也可以省略。需要限制拖拽范围时，再补上 minWidth 和 maxWidth。

<script setup lang="ts">
import { VTable, type TableColumnsType } from '@vtable-guild/vtable-guild'

interface UserRow {
  key: string
  name: string
  age: number
  status: string
}

const columns: TableColumnsType<UserRow> = [
  { title: '姓名', dataIndex: 'name', key: 'name', width: 180, resizable: true, minWidth: 120 },
  { title: '年龄', dataIndex: 'age', key: 'age', width: 96, resizable: true, maxWidth: 180 },
  { title: '状态', dataIndex: 'status', key: 'status', width: 140, resizable: true },
]
</script>

<template>
  <VTable
    row-key="key"
    :columns="columns"
    :data-source="dataSource"
    @resize-column="handleResize"
  />
</template>

关键行为

• 只有 resizable: true 的列会显示拖拽手柄
• width 是数字时，拖拽从该数值开始；width 是 auto、百分比等非数字值或未设置时，拖拽从表头单元格的实际渲染宽度开始，不会发生起点跳变
• 拖拽过程中会实时更新列宽
• 拖拽结束时会触发 resizeColumn 事件，参数顺序为 (column, width)；其中 width 是调整后的像素数值，适合直接回写到列配置
• 未显式设置 minWidth 时，默认下限是 50

什么时候用

• 运维后台、报表页面或数据看板里字段很多
• 用户希望自己微调列宽，并把宽度持久化
• 你原本只能靠 CSS 或第三方拖拽库去拼列宽调整

相关页面

• 固定列
• 功能对比总览