FxTableV2 虚拟滚动表格

基于 FxFixedSizeGrid / FxDynamicSizeGrid（@fx/components）的虚拟滚动表格，只渲染可见区域的行列，适合大数据量（万级以上）表格。UI 框架无关：纯 Vue + @fx/styles token + useNamespace('table-v2')。

核心能力：固定列（左/右）、单列/多列排序、自定义单元格 / 表头渲染函数、固定底部、空数据、遮罩层、动态行高、手动滚动控制、多层表头、展开行、树形数据。

基础用法

columns 定义列（key / title / dataKey / width，其中 width 必填），data 为数据数组，width / height 必填。下方示例渲染 10000 行，仅可见行参与渲染。

固定列

fixed 属性开启固定列布局后，表格拆分为 main / left / right 三个区域同步滚动。列上设置 fixed: true（默认左侧）、fixed: FixedDir.LEFT 或 fixed: FixedDir.RIGHT 固定到对应方向。

排序

列上设置 sortable: true 后表头出现排序按钮。配合 sort-by（单列受控排序，{ key, order }）与 column-sort 事件实现受控排序；排序方向取值用 SortOrder.ASC / SortOrder.DESC。

空数据

data 为空数组时显示空数据占位，可用 empty 具名插槽自定义内容。

固定底部

footer-height 设置底部高度（默认 0 即不显示），用 footer 具名插槽自定义底部内容，底部不参与纵向虚拟滚动。

自定义行样式

row-class 传入字符串或 ({ columns, rowData, rowIndex }) => string 回调，按行返回 className。

遮罩层

overlay 具名插槽覆盖在表格之上（绝对定位），常用于加载中遮罩。插槽内容自行定位。

vue

<template>
  <FxTableV2
    :columns="columns"
    :data="data"
    :row-height="40"
    :width="700"
    :height="400"
  >
    <template #overlay>
      <div class="fx-table-v2-overlay-demo">
        <span class="fx-table-v2-overlay-demo__spinner" />
        <span class="fx-table-v2-overlay-demo__text">加载中…</span>
      </div>
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = generateData(columns, 200)
</script>

<style scoped>
.fx-table-v2-overlay-demo {
  position: absolute;
  inset: 0;
  z-index: 9;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12px;
  background-color: var(--fx-color-mask, rgba(255, 255, 255, 0.9));
  color: var(--fx-color-primary, #409eff);
}

.fx-table-v2-overlay-demo__spinner {
  width: 26px;
  height: 26px;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: fx-table-v2-overlay-spin 0.8s linear infinite;
}

.fx-table-v2-overlay-demo__text {
  font-size: 14px;
}

@keyframes fx-table-v2-overlay-spin {
  to {
    transform: rotate(360deg);
  }
}
</style>

手动滚动

通过 ref 拿到实例后调用 scrollTo / scrollToLeft / scrollToTop / scrollToRow 编程式滚动。

vue

<template>
  <div class="fx-table-v2-manual-demo">
    <div class="fx-table-v2-manual-demo__bar">
      <label class="fx-table-v2-manual-demo__field">
        <span>滚动像素</span>
        <FxInput v-model="scrollDelta" />
      </label>
      <label class="fx-table-v2-manual-demo__field">
        <span>滚动行数</span>
        <FxInput v-model="scrollRows" />
      </label>
    </div>
    <div class="fx-table-v2-manual-demo__bar">
      <FxBtn @click="scrollByPixels">按像素滚动</FxBtn>
      <FxBtn @click="scrollByRows">按行滚动</FxBtn>
    </div>
    <FxTableV2
      ref="tableRef"
      :columns="columns"
      :data="data"
      :width="700"
      :height="400"
      fixed
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { FxBtn, FxInput } from '@fx/components'
import type { Column, TableV2Instance } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = generateData(columns, 200)

const tableRef = ref<TableV2Instance>()
const scrollDelta = ref(200)
const scrollRows = ref(10)

function scrollByPixels() {
  tableRef.value?.scrollToTop(Number(scrollDelta.value))
}

function scrollByRows() {
  tableRef.value?.scrollToRow(Number(scrollRows.value))
}
</script>

<style scoped>
.fx-table-v2-manual-demo__bar {
  display: flex;
  align-items: center;
  gap: 16px;
  margin-bottom: 16px;
}

.fx-table-v2-manual-demo__field {
  display: flex;
  align-items: center;
  gap: 8px;
  font-size: 14px;
}

.fx-table-v2-manual-demo__field :deep(.fx-input) {
  width: 120px;
}
</style>

自适应容器

用 FxAutoResizer 包裹表格，通过默认插槽把容器实测的 { width, height } 传给表格，表格随容器尺寸变化自适应。

多列排序

sort-state（多列排序状态对象，key → order）配合 column-sort 事件实现多列受控排序，每列独立维护排序方向。

自定义单元格

列上设置 cellRenderer 自定义单元格渲染（返回 VNode），headerCellRenderer 自定义表头单元格。

vue

<template>
  <FxTableV2 :columns="columns" :data="data" :width="700" :height="400" fixed />
</template>

<script lang="ts" setup>
import { h, ref } from 'vue'
import { FixedDir, FxBtn, FxTag, FxTooltip } from '@fx/components'
import { FxIcon } from '@fx-core/icon'
import type { Column } from '@fx/components'

let id = 0

const dataGenerator = () => ({
  id: `random-id-${++id}`,
  name: 'Tom',
  date: '2020-10-1',
})

// 日期格式化（YYYY/MM/DD），不引入额外依赖
const formatDate = (date: string) => {
  const d = new Date(date)
  const m = String(d.getMonth() + 1).padStart(2, '0')
  const day = String(d.getDate()).padStart(2, '0')
  return `${d.getFullYear()}/${m}/${day}`
}

const columns: Column[] = [
  {
    key: 'date',
    title: 'Date',
    dataKey: 'date',
    width: 150,
    fixed: FixedDir.LEFT,
    cellRenderer: ({ cellData }) => {
      const formatted = formatDate(cellData)
      return h(
        FxTooltip,
        { content: formatted, placement: 'top' },
        {
          default: () =>
            h('span', { class: 'fx-table-v2-cell-demo-date' }, [
              h(FxIcon, { name: 'ep:timer' }),
              h('span', null, formatted),
            ]),
        },
      )
    },
  },
  {
    key: 'name',
    title: 'Name',
    dataKey: 'name',
    width: 150,
    align: 'center',
    cellRenderer: ({ cellData }) => h(FxTag, null, () => cellData as any),
  },
  {
    key: 'operations',
    title: 'Operations',
    width: 180,
    align: 'center',
    cellRenderer: () =>
      h('span', { class: 'fx-table-v2-cell-demo-ops' }, [
        h(FxBtn, { size: 'small' }, () => '编辑'),
        h(FxBtn, { size: 'small', type: 'danger' }, () => '删除'),
      ]),
  },
]

const data = ref(Array.from({ length: 200 }).map(dataGenerator))
</script>

<style scoped>
.fx-table-v2-cell-demo-date {
  display: flex;
  align-items: center;
  gap: 8px;
}

.fx-table-v2-cell-demo-ops {
  display: inline-flex;
  gap: 8px;
}
</style>

行选择

在列上用 cellRenderer + FxCheckbox 渲染行选择框，headerCellRenderer 渲染表头全选框（含半选态）。

vue

<template>
  <div class="fx-table-v2-selection-demo">
    <FxAutoResizer>
      <template #default="{ height, width }">
        <FxTableV2
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </FxAutoResizer>
  </div>
</template>

<script lang="ts" setup>
import { h, ref, unref } from 'vue'
import { FxAutoResizer, FxCheckbox } from '@fx/components'
import type { CheckboxValueType, Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        checked: false,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = ref(generateData(columns, 200))

// 选择列：行选择 + 表头全选（cellRenderer / headerCellRenderer + FxCheckbox）
columns.unshift({
  key: 'selection',
  width: 50,
  cellRenderer: ({ rowData }) =>
    h(FxCheckbox, {
      modelValue: rowData.checked,
      ariaLabel: '选择该行',
      onChange: (value: CheckboxValueType) => {
        rowData.checked = value
      },
    }),
  headerCellRenderer: () => {
    const _data = unref(data)
    const allSelected = _data.every((row) => row.checked)
    const containsChecked = _data.some((row) => row.checked)
    return h(FxCheckbox, {
      modelValue: allSelected,
      indeterminate: containsChecked && !allSelected,
      ariaLabel: '全选',
      onChange: (value: CheckboxValueType) => {
        data.value = _data.map((row) => {
          row.checked = value
          return row
        })
      },
    })
  },
})
</script>

<style scoped>
.fx-table-v2-selection-demo {
  height: 400px;
}
</style>

动态行高

设置 estimated-row-height 后启用动态行高模式，行高随单元格内容自适应（配合 cellRenderer 渲染不等高内容）。

vue

<template>
  <FxTableV2
    :columns="columns"
    :data="data"
    :sort-by="sort"
    :estimated-row-height="40"
    :width="700"
    :height="400"
    fixed
    @column-sort="onColumnSort"
  />
</template>

<script lang="ts" setup>
import { h, ref, resolveComponent } from 'vue'
import { FixedDir, SortOrder, FxBtn } from '@fx/components'
import type { Column, SortBy } from '@fx/components'

const FxIcon = resolveComponent('FxIcon')

const longText =
  '这是一段较长的描述文本，用于演示动态行高模式下单元格自动撑开行高的效果。'
const midText = '中等长度的描述文本，行高自适应。'
const shortText = '短文本。'

const textList = [shortText, midText, longText]

let id = 0

const dataGenerator = () => ({
  id: `random-${++id}`,
  name: 'Tom',
  date: '2016-05-03',
  description: textList[Math.floor(Math.random() * 3)],
})

const columns: Column[] = [
  {
    key: 'id',
    title: 'Id',
    dataKey: 'id',
    width: 150,
    sortable: true,
    fixed: FixedDir.LEFT,
  },
  {
    key: 'name',
    title: 'Name',
    dataKey: 'name',
    width: 150,
    align: 'center',
    cellRenderer: ({ cellData }) =>
      h(
        'span',
        { class: 'fx-table-v2-dynamic-demo-tag' },
        cellData as any,
      ),
  },
  {
    key: 'description',
    title: 'Description',
    dataKey: 'description',
    width: 200,
    cellRenderer: ({ cellData }) =>
      h(
        'div',
        { style: 'padding: 10px 0; line-height: 1.6;' },
        cellData as any,
      ),
  },
  {
    key: 'operations',
    title: 'Operations',
    width: 180,
    align: 'center',
    cellRenderer: () =>
      h('span', { class: 'fx-table-v2-dynamic-demo-ops' }, [
        h(FxBtn, { size: 'small' }, () => '编辑'),
        h(FxBtn, { size: 'small', type: 'danger' }, () => '删除'),
      ]),
  },
]

const data = ref(
  Array.from({ length: 200 })
    .map(dataGenerator)
    .sort((a, b) => (a.name > b.name ? 1 : -1)),
)

const sort = ref<SortBy>({ key: 'name', order: SortOrder.ASC })

const onColumnSort = (sortBy: SortBy) => {
  const order = sortBy.order === 'asc' ? 1 : -1
  const dataClone = [...data.value]
  dataClone.sort((a, b) => (a[sortBy.key] > b[sortBy.key] ? order : -order))
  sort.value = sortBy
  data.value = dataClone
}
</script>

<style scoped>
.fx-table-v2-dynamic-demo-tag {
  display: inline-flex;
  align-items: center;
  padding: 0 10px;
  height: 24px;
  font-size: 12px;
  border-radius: 4px;
  background-color: var(--fx-color-primary-light-9, #ecf5ff);
  color: var(--fx-color-primary, #409eff);
  border: 1px solid var(--fx-color-primary-light-7, #d9ecff);
}

.fx-table-v2-dynamic-demo-ops {
  display: inline-flex;
  gap: 8px;
}
</style>

跨表区同列高亮

cell-props 回调给每个单元格打标记 + 绑定 mouseenter / mouseleave，配合根 class 实现 main / left / right 三表区同一列联动高亮。

vue

<template>
  <div class="fx-table-v2-cross-demo">
    <FxAutoResizer>
      <template #default="{ height, width }">
        <FxTableV2
          :columns="columns"
          :cell-props="cellProps"
          :class="kls"
          :data="data"
          :width="width"
          :height="height"
        />
      </template>
    </FxAutoResizer>
  </div>
</template>

<script lang="ts" setup>
import { h, ref } from 'vue'
import { FxAutoResizer } from '@fx/components'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
// 行号列：cellRenderer 返回行号文本
columns.unshift({
  key: 'column-n-1',
  width: 50,
  title: 'No.',
  cellRenderer: ({ rowIndex }) => h('span', null, `${rowIndex + 1}`),
  align: 'center',
})
const data = generateData(columns, 200)

const kls = ref<string>('')

// cellProps 回调：给每个单元格打 data-key + mouseenter/leave，实现跨表区同列高亮
const cellProps = ({ columnIndex }: { columnIndex: number }) => {
  const key = `hovering-col-${columnIndex}`
  return {
    ['data-key']: key,
    onMouseenter: () => {
      kls.value = key
    },
    onMouseleave: () => {
      kls.value = ''
    },
  }
}
</script>

<style scoped>
.fx-table-v2-cross-demo {
  height: 400px;
}

/* 同列 hover 时所有表区该列高亮 */
:deep(.hovering-col-0 [data-key='hovering-col-0']),
:deep(.hovering-col-1 [data-key='hovering-col-1']),
:deep(.hovering-col-2 [data-key='hovering-col-2']),
:deep(.hovering-col-3 [data-key='hovering-col-3']),
:deep(.hovering-col-4 [data-key='hovering-col-4']),
:deep(.hovering-col-5 [data-key='hovering-col-5']),
:deep(.hovering-col-6 [data-key='hovering-col-6']),
:deep(.hovering-col-7 [data-key='hovering-col-7']),
:deep(.hovering-col-8 [data-key='hovering-col-8']),
:deep(.hovering-col-9 [data-key='hovering-col-9']),
:deep(.hovering-col-10 [data-key='hovering-col-10']) {
  background: var(--fx-color-primary-light-7, #ecf5ff);
}

:deep([data-key='hovering-col-0']) {
  font-weight: bold;
}
</style>

合并单元格

通过 row 具名插槽拿到 { cells, columns, rowData, rowIndex }，用 cloneVNode 修改单元格 style（累加宽度 / 拉高高度）并置空被覆盖的 cell，实现列合并 / 行合并。

vue

<template>
  <FxTableV2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <ColSpanRow v-bind="props" />
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import { cloneVNode, defineComponent, h } from 'vue'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) => {
  return Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })
}

const columns: Column[] = generateColumns(10)
const data = generateData(columns, 200)

const colSpanIndex = 1
columns[colSpanIndex].colSpan = ({ rowIndex }: { rowIndex: number }) =>
  (rowIndex % 4) + 1
columns[colSpanIndex].align = 'center'

// 自定义行：把 colSpan 指定的相邻列合并成一个单元格（累加宽度，置空被合并的 cell）
const ColSpanRow = defineComponent({
  name: 'FxTableV2ColSpanRow',
  props: ['cells', 'columns', 'rowData', 'rowIndex'],
  setup(props) {
    return () => {
      const cells = [...(props.cells as any[])]
      const colSpan = props.columns[colSpanIndex].colSpan({
        rowData: props.rowData,
        rowIndex: props.rowIndex,
      })
      if (colSpan > 1) {
        let width = Number.parseInt(cells[colSpanIndex].props.style.width)
        for (let i = 1; i < colSpan; i++) {
          width += Number.parseInt(cells[colSpanIndex + i].props.style.width)
          cells[colSpanIndex + i] = null
        }
        const style = {
          ...cells[colSpanIndex].props.style,
          width: `${width}px`,
          backgroundColor: 'var(--fx-color-primary-light-5, #a0cfff)',
        }
        cells[colSpanIndex] = cloneVNode(cells[colSpanIndex], { style })
      }
      return cells
    }
  },
})
</script>

vue

<template>
  <FxTableV2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <RowSpanRow v-bind="props" />
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import { cloneVNode, defineComponent, h } from 'vue'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = generateData(columns, 200)

const rowSpanIndex = 0
columns[rowSpanIndex].rowSpan = ({ rowIndex }: { rowIndex: number }) =>
  rowIndex % 2 === 0 && rowIndex <= data.length - 2 ? 2 : 1

// 自定义行：把 rowSpan 指定的单元格纵向跨行（拉高 2 倍行高），被覆盖的行该列留空占位
const RowSpanRow = defineComponent({
  name: 'FxTableV2RowSpanRow',
  props: ['cells', 'columns', 'rowData', 'rowIndex'],
  setup(props) {
    return () => {
      const cells = [...(props.cells as any[])]
      const rowSpan = props.columns[rowSpanIndex].rowSpan({
        rowData: props.rowData,
        rowIndex: props.rowIndex,
      })
      if (rowSpan > 1) {
        const cell = cells[rowSpanIndex]
        const style = {
          ...cell.props.style,
          backgroundColor: 'var(--fx-color-danger-light-5, #fbc4c4)',
          height: `${rowSpan * 50}px`,
          alignSelf: 'flex-start',
          zIndex: 1,
        }
        cells[rowSpanIndex] = cloneVNode(cell, { style })
      } else {
        const style = cells[rowSpanIndex].props.style
        // 被跨行覆盖的位置渲染纯占位（不污染样式）
        cells[rowSpanIndex] = h('div', { style: { ...style, width: `${style.width}px` } })
      }
      return cells
    }
  },
})
</script>

vue

<template>
  <FxTableV2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <SpansRow v-bind="props" />
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import { cloneVNode, defineComponent, h } from 'vue'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = generateData(columns, 200)

const colSpanIndex = 1
columns[colSpanIndex].colSpan = ({ rowIndex }: { rowIndex: number }) =>
  (rowIndex % 4) + 1
columns[colSpanIndex].align = 'center'

const rowSpanIndex = 0
columns[rowSpanIndex].rowSpan = ({ rowIndex }: { rowIndex: number }) =>
  rowIndex % 2 === 0 && rowIndex <= data.length - 2 ? 2 : 1

// 同时处理 colSpan + rowSpan
const SpansRow = defineComponent({
  name: 'FxTableV2SpansRow',
  props: ['cells', 'columns', 'rowData', 'rowIndex'],
  setup(props) {
    return () => {
      const cells = [...(props.cells as any[])]

      const colSpan = props.columns[colSpanIndex].colSpan({
        rowData: props.rowData,
        rowIndex: props.rowIndex,
      })
      if (colSpan > 1) {
        let width = Number.parseInt(cells[colSpanIndex].props.style.width)
        for (let i = 1; i < colSpan; i++) {
          width += Number.parseInt(cells[colSpanIndex + i].props.style.width)
          cells[colSpanIndex + i] = null
        }
        const style = {
          ...cells[colSpanIndex].props.style,
          width: `${width}px`,
          backgroundColor: 'var(--fx-color-primary-light-5, #a0cfff)',
        }
        cells[colSpanIndex] = cloneVNode(cells[colSpanIndex], { style })
      }

      const rowSpan = props.columns[rowSpanIndex].rowSpan({
        rowData: props.rowData,
        rowIndex: props.rowIndex,
      })
      if (rowSpan > 1) {
        const cell = cells[rowSpanIndex]
        const style = {
          ...cell.props.style,
          backgroundColor: 'var(--fx-color-danger-light-5, #fbc4c4)',
          height: `${rowSpan * 50}px`,
          alignSelf: 'flex-start',
          zIndex: 1,
        }
        cells[rowSpanIndex] = cloneVNode(cell, { style })
      } else {
        const style = cells[rowSpanIndex].props.style
        cells[rowSpanIndex] = h('div', {
          style: { ...style, width: `${style.width}px` },
        })
      }
      return cells
    }
  },
})
</script>

展开行详情

expand-column-key 指定展开列，行数据携带 children 作为展开内容；用 row 插槽判断展开行（rowData.detail）渲染详情，配合 estimated-row-height 让详情行自适应高度。

vue

<template>
  <FxTableV2
    :columns="columns"
    :data="data"
    :estimated-row-height="50"
    :expand-column-key="columns[0].key"
    :width="700"
    :height="400"
  >
    <template #row="props">
      <DetailRow v-bind="props" />
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import { defineComponent, h, ref } from 'vue'
import type { Column } from '@fx/components'

const detailedText = `这是一段详情文本，用于演示展开行（expand）模式下点击展开图标后，
在行下方显示自定义的详情内容。文本可以很长，配合 estimated-row-height
让该行自动撑开行高。`

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = ref(
  generateData(columns, 200).map((d) => {
    d.children = [{ id: `${d.id}-detail-content`, detail: detailedText }]
    return d
  }),
)

// 自定义行：展开后 children 行的 rowData.detail 存在 → 渲染详情；否则渲染普通单元格
const DetailRow = defineComponent({
  name: 'FxTableV2DetailRow',
  inheritAttrs: false,
  props: ['cells', 'rowData'],
  setup(props) {
    return () => {
      if (props.rowData.detail) {
        return h(
          'div',
          { class: 'fx-table-v2-detail-demo', style: 'padding: 16px 24px;' },
          props.rowData.detail,
        )
      }
      return props.cells
    }
  },
})
</script>

<style scoped>
:deep(.fx-table-v2-detail-demo) {
  line-height: 1.6;
  color: var(--fx-color-text-regular, #606266);
  background-color: var(--fx-color-fill-light, #fafafa);
}
</style>

树形数据

扁平数据按 parentId 归集为树后传入，expand-column-key 指定展开列，v-model:expanded-row-keys 双向绑定展开状态，展开后子节点自动扁平化插入并按深度缩进。

vue

<template>
  <FxTableV2
    v-model:expanded-row-keys="expandedRowKeys"
    :columns="columns"
    :data="treeData"
    :width="700"
    :expand-column-key="expandColumnKey"
    :height="400"
    fixed
    @row-expand="onRowExpanded"
    @expanded-rows-change="onExpandedRowsChange"
  />
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { FixedDir } from '@fx/components'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10).map((column, columnIndex) => {
  let fixed: true | 'left' | 'right' | undefined
  if (columnIndex < 2) fixed = FixedDir.LEFT
  else if (columnIndex > 8) fixed = FixedDir.RIGHT
  else fixed = undefined
  return { ...column, fixed }
})

const data = generateData(columns, 200)

const expandColumnKey = 'column-0'

// 注入子节点（含二级子节点）演示树形展开
for (let i = 0; i < 50; i++) {
  data.push(
    {
      ...data[0],
      id: `${data[0].id}-sub-${i}`,
      parentId: data[0].id,
      [expandColumnKey]: `Sub ${i}`,
    },
    {
      ...data[2],
      id: `${data[2].id}-sub-${i}`,
      parentId: data[2].id,
      [expandColumnKey]: `Sub ${i}`,
    },
    {
      ...data[2],
      id: `${data[2].id}-sub-sub-${i}`,
      parentId: `${data[2].id}-sub-${i}`,
      [expandColumnKey]: `Sub-Sub ${i}`,
    },
  )
}

// 扁平数组 → 树（按 parentId 归集 children）
function unflatten(
  list: ReturnType<typeof generateData>,
  rootId: any = null,
  dataKey = 'id',
  parentKey = 'parentId',
) {
  const tree: any[] = []
  const childrenMap: Record<string, any[]> = {}

  for (const datum of list) {
    const item = { ...datum }
    const id = item[dataKey]
    const parentId = item[parentKey]

    if (Array.isArray(item.children)) {
      childrenMap[id] = item.children.concat(childrenMap[id] || [])
    } else if (!childrenMap[id]) {
      childrenMap[id] = []
    }
    item.children = childrenMap[id]

    if (parentId !== undefined && parentId !== rootId) {
      if (!childrenMap[parentId]) childrenMap[parentId] = []
      childrenMap[parentId].push(item)
    } else {
      tree.push(item)
    }
  }

  return tree
}

const treeData = computed(() => unflatten(data))

const expandedRowKeys = ref<string[]>([])

const onRowExpanded = ({ expanded }: { expanded: boolean }) => {
  // eslint-disable-next-line no-console
  console.log('Expanded:', expanded)
}

const onExpandedRowsChange = (expandedKeys: any[]) => {
  // eslint-disable-next-line no-console
  console.log(expandedKeys)
}
</script>

筛选

用 headerCellRenderer 自定义表头，配合 FxPopover 渲染弹出式筛选面板：点击筛选图标弹出勾选条件与确认 / 重置按钮，确认后切换数据集。

vue

<template>
  <FxTableV2 fixed :columns="fixedColumns" :data="data" :width="700" :height="400" />
</template>

<script lang="ts" setup>
import { computed, h, nextTick, ref } from 'vue'
import { FixedDir, FxBtn, FxCheckbox, FxPopover } from '@fx/components'
import { FxIcon } from '@fx-core/icon'
import type { Column, HeaderCellSlotProps } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `${prefix}${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
const data = ref(generateData(columns, 200))

const shouldFilter = ref(false)
const popoverVisible = ref(false)

const ariaLabel = computed(() => `筛选 ${columns[0].title}`)

const onFilter = () => {
  popoverVisible.value = false
  data.value = shouldFilter.value
    ? generateData(columns, 100, 'filtered-')
    : generateData(columns, 200)
}

const onReset = () => {
  shouldFilter.value = false
  onFilter()
}

// 弹出后将焦点移入面板，便于键盘操作
const handleAfterEnter = () => {
  nextTick(() => {
    const button = document.querySelector(
      '.fx-table-v2__demo-filter button',
    ) as HTMLElement | null
    button?.focus()
  })
}

columns[0].headerCellRenderer = (props: HeaderCellSlotProps) => {
  return h('div', { class: 'fx-table-v2__demo-filter-head' }, [
    h('span', { class: 'fx-table-v2__demo-filter-title' }, props.column.title),
    h(
      FxPopover,
      {
        visible: popoverVisible.value,
        'onUpdate:visible': (v: boolean) => {
          popoverVisible.value = v
        },
        trigger: 'click',
        width: 200,
        onAfterEnter: handleAfterEnter,
      },
      {
        default: () =>
          h(
            'button',
            {
              type: 'button',
              ariaLabel: ariaLabel.value,
              class: 'fx-table-v2__demo-filter-btn',
            },
            [h(FxIcon, { size: 14, name: 'ep:filter' })],
          ),
        content: () =>
          h('div', { class: 'fx-table-v2__demo-filter-wrapper' }, [
            h('div', { class: 'fx-table-v2__demo-filter-group' }, [
              h(
                FxCheckbox,
                {
                  modelValue: shouldFilter.value,
                  onChange: (v: boolean) => {
                    shouldFilter.value = v
                  },
                },
                () => '筛选文本',
              ),
            ]),
            h('div', { class: 'fx-table-v2__demo-filter' }, [
              h(FxBtn, { text: true, onClick: onFilter }, () => '确认'),
              h(FxBtn, { text: true, onClick: onReset }, () => '重置'),
            ]),
          ]),
      },
    ),
  ])
}

const fixedColumns: Column[] = columns.map((column, columnIndex) => {
  let fixed: true | 'left' | 'right' | undefined
  if (columnIndex < 2) fixed = FixedDir.LEFT
  else if (columnIndex > 9) fixed = FixedDir.RIGHT
  else fixed = undefined
  return { ...column, fixed, width: 100 }
})
</script>

<style scoped>
.fx-table-v2__demo-filter-head {
  display: flex;
  align-items: center;
  justify-content: center;
}

.fx-table-v2__demo-filter-title {
  margin-inline-end: 8px;
  font-size: 12px;
}

.fx-table-v2__demo-filter-btn {
  display: flex;
  padding: 0;
  margin: 0;
  cursor: pointer;
  background-color: transparent;
  border: none;
  appearance: none;
}
</style>

<style>
/* 面板内部样式（Popover teleport 到 body，需用全局样式） */
.fx-table-v2__demo-filter {
  display: flex;
  justify-content: space-between;
  margin: 12px -12px -12px;
  padding: 0 12px;
  border-top: 1px solid var(--fx-border-color-light);
}
</style>

单元格编辑

cellRenderer 根据行内 editing 标记在触发器（div）与编辑器（FxInput）间切换，点击进入编辑、失焦 / 回车退出。

vue

<template>
  <div class="fx-table-v2-inline-demo">
    <FxAutoResizer>
      <template #default="{ height, width }">
        <FxTableV2
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </FxAutoResizer>
  </div>
</template>

<script lang="ts" setup>
import { defineComponent, h, ref, withKeys } from 'vue'
import { FxAutoResizer, FxInput } from '@fx/components'
import type { Column } from '@fx/components'

// 可编辑单元格：编辑态渲染 FxInput，非编辑态渲染触发器
const InputCell = defineComponent({
  name: 'FxTableV2InputCell',
  props: [
    'value',
    'onChange',
    'onBlur',
    'onKeydownEnter',
    'forwardRef',
  ],
  setup(props) {
    return () =>
      h(FxInput, {
        ref: props.forwardRef as any,
        modelValue: props.value,
        onInput: props.onChange,
        onBlur: props.onBlur,
        onKeydown: withKeys(props.onKeydownEnter, ['enter']),
      })
  },
})

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        editing: false,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(10)
columns[0] = {
  ...columns[0],
  title: 'Editable Column',
  cellRenderer: ({ rowData, column }: any) => {
    const onChange = (value: string) => {
      rowData[column.dataKey] = value
    }
    const onEnterEditMode = () => {
      rowData.editing = true
    }
    const onExitEditMode = () => {
      rowData.editing = false
    }
    const input = ref()
    const setRef = (el: any) => {
      input.value = el
      if (el) el.focus?.()
    }

    return rowData.editing
      ? h(InputCell, {
          forwardRef: setRef,
          value: rowData[column.dataKey],
          onChange,
          onBlur: onExitEditMode,
          onKeydownEnter: onExitEditMode,
        })
      : h(
          'div',
          { class: 'fx-table-v2-inline-demo-trigger', onClick: onEnterEditMode },
          rowData[column.dataKey],
        )
  },
}

const data = ref(generateData(columns, 200))
</script>

<style scoped>
.fx-table-v2-inline-demo {
  height: 400px;
}

:deep(.fx-table-v2-inline-demo-trigger) {
  border: 1px transparent dotted;
  padding: 4px;
  cursor: text;
}

:deep(.fx-table-v2-inline-demo-trigger:hover) {
  border-color: var(--fx-color-primary, #409eff);
}
</style>

多层表头

header-height 传数组开启多层表头，用 header 具名插槽自定义每一层（拿到 { cells, columns, headerIndex }），把相邻列合并成分组表头；固定列占位用 placeholderSign 识别。

vue

<template>
  <FxTableV2
    fixed
    :columns="fixedColumns"
    :data="data"
    :header-height="[50, 40, 50]"
    :header-class="headerClass"
    :width="700"
    :height="400"
  >
    <template #header="props">
      <CustomizedHeader v-bind="props" />
    </template>
  </FxTableV2>
</template>

<script lang="ts" setup>
import { defineComponent, h } from 'vue'
import { FixedDir, placeholderSign } from '@fx/components'
import type { Column } from '@fx/components'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-',
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      },
    )
  })

const columns: Column[] = generateColumns(15)
const data = generateData(columns, 200)

const fixedColumns: Column[] = columns.map((column, columnIndex) => {
  let fixed: true | 'left' | 'right' | undefined
  if (columnIndex < 3) fixed = FixedDir.LEFT
  else if (columnIndex > 12) fixed = FixedDir.RIGHT
  else fixed = undefined
  return { ...column, fixed, width: 100 }
})

// 自定义多层表头：最后一层（headerIndex=2）渲染原始 cells；其余层把相邻列合并成分组表头
const CustomizedHeader = defineComponent({
  name: 'FxTableV2GroupHeader',
  props: ['cells', 'columns', 'headerIndex'],
  setup(props) {
    return () => {
      const { cells, columns, headerIndex } = props as any
      if (headerIndex === 2) return cells

      const groupCells: any[] = []
      let width = 0
      let idx = 0

      columns.forEach((column: any, columnIndex: number) => {
        if (column.placeholderSign === placeholderSign) {
          groupCells.push((cells as any[])[columnIndex])
        } else {
          width += (cells as any[])[columnIndex].props.column.width
          idx++

          const nextColumn = columns[columnIndex + 1]
          if (
            columnIndex === columns.length - 1 ||
            nextColumn?.placeholderSign === placeholderSign ||
            idx === (headerIndex === 0 ? 4 : 2)
          ) {
            groupCells.push(
              h(
                'div',
                {
                  class: 'fx-table-v2-group-demo-cell',
                  role: 'columnheader',
                  style: {
                    ...(cells as any[])[columnIndex].props.style,
                    width: `${width}px`,
                  },
                },
                `Group width ${width}`,
              ),
            )
            width = 0
            idx = 0
          }
        }
      })
      return groupCells
    }
  },
})

const headerClass = ({ headerIndex }: { headerIndex: number }) => {
  if (headerIndex === 1) return 'fx-table-v2-group-demo-highlight'
  return ''
}
</script>

<style scoped>
:deep(.fx-table-v2-group-demo-cell) {
  display: flex;
  align-items: center;
  justify-content: center;
  border-right: 1px solid var(--fx-border-color, #dcdfe6);
}

:deep(.fx-table-v2-group-demo-cell:last-child) {
  border-right: none;
}

:deep(.fx-table-v2-group-demo-highlight) {
  background-color: var(--fx-color-primary, #409eff);
  color: var(--fx-color-white, #fff);
  font-size: 14px;
  font-weight: bold;
}

:deep(.fx-table-v2-group-demo-highlight .fx-table-v2-group-demo-cell) {
  padding: 0 4px;
}
</style>

粘性行

fixed-data 传入不参与滚动的固定行（粘在底部），配合 scroll 事件按滚动位置更新粘性行内容、row-class 标记样式。

FxTableV2 API

FxTableV2 Attributes

属性	说明	类型	默认值
columns	列定义	`Column[]`	`[]`
data	行数据	`Record<PropertyKey, any>[]`	`[]`
data-getter	自定义取值函数（优先于 `dataKey`）	`(params) => any`	—
fixed-data	固定在底部不参与滚动的数据	`any[]`	—
row-key	行 key 字段名或取值函数	`KeyType`	`'id'`
width	表格总宽度（必填）	`number`	—
height	表格总高度（必填）	`number`	—
max-height	最大高度（超出滚动）	`number`	—
row-height	行高（固定行高模式）	`number`	`50`
estimated-row-height	预估行高，设置后启用动态行高模式	`number`	—
header-height	表头高度，多层表头传数组	`number \| number[]`	`50`
footer-height	底部高度	`number`	`0`
fixed	是否启用固定列布局（生成 main/left/right 三表区）	`boolean`	`false`
use-is-scrolling	是否追踪滚动状态（注入 `isScrolling`）	`boolean`	`false`
indent-size	缩进尺寸（树形 / 展开行）	`number`	`12`
icon-size	展开图标尺寸	`number`	`12`
h-scrollbar-size	横向滚动条尺寸	`number`	`6`
v-scrollbar-size	纵向滚动条尺寸	`number`	`6`
scrollbar-always-on	滚动条常驻显示	`boolean`	`false`
cache	上下预渲染行数	`number`	`2`
header-class	表头 className	`string \| HeaderClassNameGetter`	—
header-props	表头额外 props	`object \| ExtractHeaderPropGetter`	—
header-cell-props	表头单元格额外 props	`object \| ExtractHeaderCellPropGetter`	—
row-class	行 className	`string \| RowClassNameGetter`	—
row-props	行额外 props	`object \| ExtractRowPropGetter`	—
cell-props	单元格额外 props	`object \| ExtraCellPropGetter`	—
class	根 className	`string`	—
style	根 style	`CSSProperties`	—
expand-column-key	展开行列 key	`string`	—
expanded-row-keys	受控展开行 keys	`KeyType[]`	—
default-expanded-row-keys	默认展开行 keys（非受控）	`KeyType[]`	—
sort-by	单列排序状态（受控）	`SortBy`	`{}`
sort-state	多列排序状态（受控）	`SortState`	—
row-event-handlers	行事件处理集合	`RowEventHandlers`	—

FxTableV2 Slots

名称	说明	参数
cell	单元格默认内容（所有列共用）	`{ cellData, rowData, rowIndex, column, columnIndex }`
header-cell	表头单元格默认内容（所有列共用）	`{ column, columnIndex, headerIndex }`
row	自定义整行	`{ columns, rowData, rowIndex }`
header	自定义整行表头	`{ columns, headerIndex }`
footer	底部内容	—
empty	空数据占位	—
overlay	遮罩层（覆盖在表格之上）	—

单列自定义优先用 column.cellRenderer / column.headerCellRenderer，cell / header-cell 插槽对所有列生效。

FxTableV2 Events

事件名	说明	回调参数
column-sort	列排序触发	`{ column, key, order }`
scroll	滚动触发	`{ scrollLeft, scrollTop }`
row-expand	行展开 / 收起	`{ expanded, rowData, rowIndex }`
row-hover	行 hover	`{ hovered, rowData, rowIndex }`
row-height-change	行高变化（动态行高）	`RowHeightChangedParams`
expanded-rows-change	展开行 keys 变化	`KeyType[]`
end-reached	滚动到底部	`remainDistance: number`
rows-rendered	行渲染范围变化	`{ rowCacheStart, rowCacheEnd, rowVisibleStart, rowVisibleEnd }`

FxTableV2 Exposes

名称	说明	参数
scrollTo	滚动到指定位置	`({ scrollLeft?, scrollTop? })`
scrollToLeft	滚动到横向位置	`(scrollLeft: number)`
scrollToTop	滚动到纵向位置	`(scrollTop: number)`
scrollToRow	滚动到指定行	`(row: number, strategy?: 'auto' \| 'smart' \| 'center' \| 'start' \| 'end')`

Column

列定义（width 必填）。

属性	说明	类型
key	列唯一标识（兼做排序 key）	`KeyType`
data-key	数据字段名（默认渲染取值用）	`KeyType`
title	列标题	`string`
width	列宽（px，必填）	`number`
min-width	最小列宽	`number`
max-width	最大列宽	`number`
align	排列方向	`'left' \| 'center' \| 'right'`
fixed	固定列：`true` 固定左侧，或指定方向	`true \| FixedDir`
flex-grow	剩余空间分配	`number`
flex-shrink	空间收缩	`number`
sortable	是否可排序	`boolean`
hidden	是否隐藏	`boolean`
class	单元格 className（字符串或 getter）	`string \| ClassNameGetter`
header-class	表头单元格 className	`string \| HeaderClassGetter`
style	列自定义样式	`CSSProperties`
cell-renderer	单元格自定义渲染函数	`CellRenderer`
header-cell-renderer	表头单元格自定义渲染函数	`HeaderCellRenderer`

内置常量

排序方向与固定列方向用内置常量取值（避免硬编码字符串）。

import { SortOrder, FixedDir, Alignment } from '@fx/components'

SortOrder.ASC   // 'asc'
SortOrder.DESC  // 'desc'
FixedDir.LEFT   // 'left'
FixedDir.RIGHT  // 'right'
Alignment.LEFT  // 'left'
Alignment.CENTER // 'center'
Alignment.RIGHT // 'right'

类型声明

展开查看完整类型定义

type KeyType = string | number | symbol

type RowCommonParams = {
  rowData: any
  rowIndex: number
}

type ColumnCommonParams<T> = {
  columns: Column<T>[]
  column: Column<T>
  columnIndex: number
}

type CellRendererParams<T> = {
  cellData: T
} & RowCommonParams &
  ColumnCommonParams<T>

type HeaderCellRendererParams<T> = {
  headerIndex: number
} & ColumnCommonParams<T>

type ClassNameGetterParams<T> = {
  cellData: T
} & RowCommonParams &
  ColumnCommonParams<T>

type DataGetterParams<T> = {
  columns: Column<T>[]
  column: Column<T>
  columnIndex: number
} & RowCommonParams

type DataGetter<T> = (params: DataGetterParams<T>) => T

type ClassNameGetter<T> = (params: ClassNameGetterParams<T>) => string

type HeaderClassGetter<T> = (
  params: ColumnCommonParams<T> & { headerIndex: number },
) => string

type CellRenderer<T> = (params: CellRendererParams<T>) => VNode

type HeaderCellRenderer<T> = (params: HeaderCellRendererParams<T>) => VNode

type HeaderClassNameGetter<T> = (params: {
  columns: Column<T>[]
  headerIndex: number
}) => string

type RowClassNameGetter<T> = (
  params: { columns: Column<T>[] } & RowCommonParams
) => string

type ExtraCellPropGetter<T> = (
  params: ColumnCommonParams<T> &
    RowCommonParams & { cellData: T; rowData: any }
) => any

type ExtractHeaderPropGetter<T> = (params: {
  columns: Column<T>[]
  headerIndex: number
}) => any

type ExtractHeaderCellPropGetter<T> = (
  params: ColumnCommonParams<T> & { headerIndex: number }
) => any

type ExtractRowPropGetter<T> = (
  params: { columns: Column<T>[] } & RowCommonParams
) => any

type ColumnSortParams<T> = {
  column: Column<T>
  key: KeyType
  order: SortOrder
}

type ScrollPos = {
  scrollLeft: number
  scrollTop: number
}

type CellSlotProps<T> = {
  class: string
  columns: Column<T>[]
  column: Column<T>
  columnIndex: number
  cellData: T
  rowData: any
  rowIndex: number
  isScrolling: boolean
}

type HeaderSlotProps = {
  cells: VNode[]
  columns: Column<any>[]
  headerIndex: number
}

type HeaderCellSlotProps = {
  class: string
  columns: Column<any>[]
  column: Column<any>
  columnIndex: number
  headerIndex: number
  style: CSSProperties
  headerCellProps?: any
  sortBy: SortBy
  sortState?: SortState | undefined
  onColumnSorted: (e: MouseEvent) => void
}

type RowSlotProps = {
  cells: VNode[]
  columns: Column<any>[]
  depth: number
  style: CSSProperties
  rowData: any
  rowIndex: number
  isScrolling: boolean
}

type RowEventHandlerParams = {
  rowKey: KeyType
  event: Event
} & RowCommonParams

type RowEventHandler = (params: RowEventHandlerParams) => void

type RowEventHandlers = {
  onClick?: RowEventHandler
  onContextmenu?: RowEventHandler
  onDblclick?: RowEventHandler
  onMouseenter?: RowEventHandler
  onMouseleave?: RowEventHandler
}

type RowExpandParams = {
  expanded: boolean
  rowKey: KeyType
} & RowCommonParams

type RowHoverParams = {
  event?: MouseEvent
  hovered: boolean
  rowKey: KeyType
} & Partial<RowCommonParams>

type RowsRenderedParams = {
  rowCacheStart: number
  rowCacheEnd: number
  rowVisibleStart: number
  rowVisibleEnd: number
}

type SortBy = { key: KeyType; order: SortOrder }
type SortState = Record<KeyType, SortOrder>

// 内置常量（const 对象，非 enum）
const SortOrder = {
  ASC: 'asc',
  DESC: 'desc',
} as const

const Alignment = {
  LEFT: 'left',
  CENTER: 'center',
  RIGHT: 'right',
} as const

const FixedDir = {
  LEFT: 'left',
  RIGHT: 'right',
} as const

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

常见问题

如何在首列渲染勾选框？

由于虚拟表格允许自定义单元格渲染，你可以像自定义单元格示例那样，通过 cellRenderer 自行渲染勾选框（FxCheckbox），并自行维护选中状态。参考行选择示例。

为什么虚拟表格比 FxTable 提供的功能少？

虚拟表格有意提供更少的开箱即用功能，让用户按需实现自己的业务逻辑。集成过多功能会使代码难以维护，对大多数用户而言基础功能已足够。部分关键特性尚未开发。

FxAutoResizer API

容器尺寸自适应组件，配合 FxTableV2 让表格填满父容器并随容器尺寸变化自适应。

FxAutoResizer Attributes

属性	说明	类型	默认值
disable-width	是否禁用宽度自适应	`boolean`	`false`
disable-height	是否禁用高度自适应	`boolean`	`false`

FxAutoResizer Slots

名称	说明	参数
default	自定义内容（通常放 FxTableV2）	`{ width, height }`

color picker 颜色选择相关

日期时间选择相关

input输入框相关

FxTableV2 虚拟滚动表格

基础用法

固定列

排序

空数据

固定底部

自定义行样式

遮罩层

手动滚动

自适应容器

多列排序

自定义单元格

行选择

动态行高

跨表区同列高亮

合并单元格

展开行详情

树形数据

筛选

单元格编辑

多层表头

粘性行

FxTableV2 API

FxTableV2 Attributes

FxTableV2 Slots

FxTableV2 Events

FxTableV2 Exposes

Column

内置常量

类型声明

常见问题

如何在首列渲染勾选框？

为什么虚拟表格比 FxTable 提供的功能少？

FxAutoResizer API

FxAutoResizer Attributes

FxAutoResizer Slots

FxTableV2 虚拟滚动表格 ​

基础用法 ​

固定列 ​

排序 ​

空数据 ​

固定底部 ​

自定义行样式 ​

遮罩层 ​

手动滚动 ​

自适应容器 ​

多列排序 ​

自定义单元格 ​

行选择 ​

动态行高 ​

跨表区同列高亮 ​

合并单元格 ​

展开行详情 ​

树形数据 ​

筛选 ​

单元格编辑 ​

多层表头 ​

粘性行 ​

FxTableV2 API ​

FxTableV2 Attributes ​

FxTableV2 Slots ​

FxTableV2 Events ​

FxTableV2 Exposes ​

Column ​

内置常量 ​

类型声明 ​

常见问题 ​

如何在首列渲染勾选框？ ​

为什么虚拟表格比 FxTable 提供的功能少？ ​

FxAutoResizer API ​

FxAutoResizer Attributes ​

FxAutoResizer Slots ​

FxTableV2 虚拟滚动表格

基础用法

固定列

排序

空数据

固定底部

自定义行样式

遮罩层

手动滚动

自适应容器

多列排序

自定义单元格

行选择

动态行高

跨表区同列高亮

合并单元格

展开行详情

树形数据

筛选

单元格编辑

多层表头

粘性行

FxTableV2 API

FxTableV2 Attributes

FxTableV2 Slots

FxTableV2 Events

FxTableV2 Exposes

Column

内置常量

类型声明

常见问题

如何在首列渲染勾选框？

为什么虚拟表格比 FxTable 提供的功能少？

FxAutoResizer API

FxAutoResizer Attributes

FxAutoResizer Slots