Reka UI logoReka UI 中文文档
backdrop
Examples
指南

虚拟化渲染

了解如何通过基于 @tanstack/vue-virtual 的 Reka UI 高效渲染大型数据集。

什么是虚拟化渲染？

虚拟化渲染是一种通过仅渲染当前视窗内可见项来高效渲染大型列表或树状结构的技术。这种方法能显著提升性能并减少内存占用，特别是在处理数千个数据项时效果尤为明显。

使用虚拟化渲染的优势

  • 性能提升：无卡顿渲染数千个数据项
  • 内存占用减少：仅为可见项挂载 DOM 节点
  • 更佳用户体验：快速的初始加载和响应式交互

自定义选项

所有虚拟化组件（组合框、列表框 和 树形组件）均提供以下属性和自定义功能：

  • 自定义项渲染：灵活渲染复杂的项结构
  • estimateSize：为静态或动态项设置预估高度
  • overscan：控制可视区域外渲染的项数量
  • textContent：为每个项设置文本内容以实现类型预检功能

使用方法

以下是确保虚拟化正常工作的重要注意事项：

  1. 需要固定高度/最大高度的 <Virtualizer /> 包装容器
  2. 保持项高度一致，并正确设置 estimateSize 属性
  3. 设置 textContent 属性以确保类型预检的可访问性

示例

vue
<script setup>
import { ComboboxContent, ComboboxItem, ComboboxRoot, ComboboxViewport, ComboboxVirtualizer } from 'reka-ui'

const items = [
  // … 大型数据项数组
]
</script>

<template>
  <ComboboxRoot>
    …
    <ComboboxContent>
      <!-- 确保为 Virtualizer 的父元素设置高度 -->
      <ComboboxViewport class="max-h-80 overflow-y-auto">
        <ComboboxVirtualizer
          v-slot="{ option }"
          :options="items"
          :estimate-size="25"
          :text-content="(opt) => opt.label"
        >
          <ComboboxItem :value="option">
            {{ option.label }}
          </ComboboxItem>
        </ComboboxVirtualizer>
      </ComboboxViewport>
    </ComboboxContent>
  </ComboboxRoot>
</template>

常见问题

虚拟化功能未生效

请确保 <Virtualizer> 的父元素已设置明确高度！

vue
<template>
  <ComboboxRoot>
    …
    <ComboboxContent>
      <!-- 必须定义高度 -->
      <ComboboxViewport class="max-h-80 overflow-y-auto">
        <ComboboxVirtualizer>
          …
        </ComboboxVirtualizer>
      </ComboboxViewport>
    </ComboboxContent>
  </ComboboxRoot>
</template>