Liste virtuelle

Seuls les éléments de la fenêtre visible sont rendus. La liste virtuelle prend en charge deux modes : hauteur fixe et hauteur dynamique (le mode dynamique repose sur des décalages précalculés et une recherche dichotomique pour le positionnement).

Hauteur fixe

Hauteur fixe

Élément 0 · Élément 1

Élément 1 · Élément 2

Élément 2 · Élément 3

Élément 3 · Élément 4

<script setup lang="ts">
const listData = Array.from({ length: 1000 }, (_, i) => `Élément ${i + 1}`)
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-height="40">
    <template #default="{ item, index }">
      <div>Élément {{ index }} · {{ item }}</div>
    </template>
  </LhVirtualList>
</template>

<script>
export default {
  data() {
    return {
      listData: Array.from({ length: 1000 }, (_, i) => `Élément ${i + 1}`),
    }
  },
}
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-height="40">
    <template #default="{ item, index }">
      <div>Élément {{ index }} · {{ item }}</div>
    </template>
  </LhVirtualList>
</template>

Hauteur dynamique

itemSize renvoie la hauteur de chaque élément (elle peut être calculée dynamiquement à partir de résultats de mesure).

Hauteur dynamique

Élément 1

Élément 2

Élément 3

<script setup>
const dynamicSize = (index) => (index % 3 === 0 ? 56 : 36)
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-size="dynamicSize">
    <template #default="{ item, index }">{{ item }}</template>
  </LhVirtualList>
</template>

<script>
export default {
  data() {
    return {
      listData: Array.from({ length: 1000 }, (_, i) => `Élément ${i + 1}`),
    }
  },
  methods: {
    dynamicSize(index) {
      return index % 3 === 0 ? 56 : 36
    },
  },
}
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-size="dynamicSize">
    <template #default="{ item, index }">{{ item }}</template>
  </LhVirtualList>
</template>

Tampon de pré-rendu

overscan indique combien de lignes pré-renduire au-delà de la fenêtre visible, en haut et en bas, afin de réduire les clignotements lors d'un défilement rapide.

overscan

Élément 0 · Élément 1

Élément 1 · Élément 2

Élément 2 · Élément 3

Élément 3 · Élément 4

Élément 4 · Élément 5

Élément 5 · Élément 6

Élément 6 · Élément 7

Élément 7 · Élément 8

Élément 8 · Élément 9

Élément 9 · Élément 10

Élément 10 · Élément 11

Élément 11 · Élément 12

Élément 12 · Élément 13

Élément 13 · Élément 14

Élément 14 · Élément 15

Élément 15 · Élément 16

<script setup lang="ts">
const listData = Array.from({ length: 1000 }, (_, i) => `Élément ${i + 1}`)
</script>

<template>
  <LhVirtualList
    :data="listData"
    :item-height="40"
    :height="200"
    :overscan="8"
  />
</template>

<script>
export default {
  data() {
    return {
      listData: Array.from({ length: 1000 }, (_, i) => `Élément ${i + 1}`),
    }
  },
}
</script>

<template>
  <LhVirtualList
    :data="listData"
    :item-height="40"
    :height="200"
    :overscan="8"
  />
</template>

API

LhVirtualList Props

Prop	Description	Type	Valeur par défaut
data	Source de données (le rendu des éléments est assuré par le slot default)	any[]	—
height	Hauteur du conteneur (un nombre correspond à des px)	string | number	—
itemHeight	Hauteur des éléments en mode hauteur fixe	number	—
itemSize	Mode hauteur dynamique : l'appelant renvoie la hauteur de chaque élément	(index: number) => number	—
overscan	Nombre d'éléments sur-rendus (overscan)	number	LH_VIRTUAL_OVERSCAN
sx	Propriétés de mise en page rapide sx	LhSxProps	—

Slots : default (portée { item, index }).

Accessibilité

• Le conteneur a overflow: auto et est défilable au clavier ; les éléments hors fenêtre ne sont pas dans le DOM, les lecteurs d'écran les récupèrent à la demande (compromis inhérent aux longues listes : il est recommandé de combiner avec une recherche/un filtrage pour restreindre la portée)
• Pour un tableau sémantique complet, utilisez le composant Table (dont le défilement virtuel est également piloté par des fonctions pures de la couche core)

Définitions de types

Les structures de types TypeScript exportées par ce composant sont les suivantes (extraites automatiquement de packages/components/virtual-list/src/types.ts et de @lh-ui/share/core/* ; cliquez sur chaque entrée pour afficher la définition complète ; les descriptions des props se trouvent dans le tableau Props ci-dessus) :

LhVirtualListProps

export interface LhVirtualListProps {
  /** Source de données (le rendu des éléments est assuré par le slot default) */
  data: any[]
  /** Hauteur du conteneur (un nombre correspond à des px) */
  height: number | string
  /** Hauteur des éléments en mode hauteur fixe (alternative à itemSize ; lorsque itemSize est fournie, le mode dynamique s'applique) */
  itemHeight?: number
  /** Mode hauteur dynamique : l'appelant renvoie la hauteur de chaque élément */
  itemSize?: (index: number) => number
  /** Nombre d'éléments sur-rendus (overscan) */
  overscan?: number
  /** Propriétés de mise en page rapide sx */
  sx?: LhSxProps
}

Constantes

Les constantes publiques utilisées par ce composant sont les suivantes (vous pouvez cliquer sur l'entrée correspondante dans la colonne « Type / Valeur par défaut » du tableau Props pour y accéder) :

LH_VIRTUAL_ITEM_SIZE _{(provenant de @lh-ui/share/core/virtual-list)}

/** Hauteur estimée par défaut d'un élément */
export const LH_VIRTUAL_ITEM_SIZE = 40