开发预览更新于 2026-05-10

VirtualGrid 虚拟网格

2D 虚拟滚动网格，自动列数（基于 minColumnWidth）+ 行虚拟化；适合大图墙 / 缩略图 / 卡片墙。

基础用法

不同于 Masonry，VirtualGrid 每个单元格高度一致——这是它能做行虚拟化的前提。列数自动按 minColumnWidth 算出，每格宽度均分容器。5000 个 cell 也只渲染当前可见行。

背景视口

#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

src/App.vue

<script setup lang="ts">
import { CfVirtualGrid } from '@chufix-design/vue';

const items = Array.from({ length: 5000 }, (_, i) => ({
  id: i,
  color: `oklch(70% 0.12 ${(i * 17) % 360})`,
}));
</script>
<template>
  <CfVirtualGrid
    :items="items"
    :item-height="120"
    :min-column-width="120"
    :gap="8"
    :height="360"
    :item-key="(it) => it.id"
  >
    <template #default="{ item }">
      <div class="demo-tile" :style="{ background: item.color }">#{{ item.id + 1 }}</div>
    </template>
  </CfVirtualGrid>
</template>
<style scoped>
.demo-tile { display: flex; align-items: center; justify-content: center; height: 100%; color: white; font-weight: 600; border-radius: var(--r-4); }
</style>

<script setup>
import { CfVirtualGrid } from '@chufix-design/vue';

const items = Array.from({ length: 5000 }, (_, i) => ({
  id: i,
  color: `oklch(70% 0.12 ${(i * 17) % 360})`,
}));
</script>
<template>
  <CfVirtualGrid
    :items="items"
    :item-height="120"
    :min-column-width="120"
    :gap="8"
    :height="360"
    :item-key="(it) => it.id"
  >
    <template #default="{ item }">
      <div class="demo-tile" :style="{ background: item.color }">#{{ item.id + 1 }}</div>
    </template>
  </CfVirtualGrid>
</template>
<style scoped>
.demo-tile { display: flex; align-items: center; justify-content: center; height: 100%; color: white; font-weight: 600; border-radius: var(--r-4); }
</style>

import { CfVirtualGrid } from '@chufix-design/react';

export default function Demo() {
  const items = Array.from({ length: 5000 }, (_, i) => ({
    id: i,
    color: `oklch(70% 0.12 ${(i * 17) % 360})`,
  }));
  return (
    <>
      <CfVirtualGrid items={items} itemHeight={120} minColumnWidth={120} gap={8} height={360} itemKey={(it) => it.id}
        >
            <div className="demo-tile" style={{ background: item.color }}>#{item.id + 1}</div>
    </>
  );
}

import { CfVirtualGrid } from '@chufix-design/react';

export default function Demo() {
  const items = Array.from({ length: 5000 }, (_, i) => ({
    id: i,
    color: `oklch(70% 0.12 ${(i * 17) % 360})`,
  }));
  return (
    <>
      <CfVirtualGrid items={items} itemHeight={120} minColumnWidth={120} gap={8} height={360} itemKey={(it) => it.id}
        >
            <div className="demo-tile" style={{ background: item.color }}>#{item.id + 1}</div>
    </>
  );
}

API

属性	类型	默认	说明
`items`	`T[]`	`—`	数据数组
`itemHeight`	`number`	`—`	每格高度（px，固定）
`minColumnWidth`	`number`	`200`	单元格最小宽，决定列数
`columns`	`number`	`—`	强制列数，覆盖 minColumnWidth
`gap`	`number`	`8`	行 / 列间距
`overscan`	`number`	`2`	视口外预渲染行
`height`	`number \| string`	`'100%'`	容器高
`itemKey`	`(item, i) => string \| number`	`i`	稳定 key