قائمة افتراضية VirtualList

لا يُعالَج للعرض سوى العناصر داخل النافذة المرئية، مع دعم وضعين: ارتفاع ثابت وارتفاع ديناميكي (يعتمد الوضع الديناميكي على إزاحات محسوبة مسبقًا مع بحث ثنائي للتحديد).

ارتفاع ثابت

ارتفاع ثابت

العنصر 0 · عنصر 1

العنصر 1 · عنصر 2

العنصر 2 · عنصر 3

العنصر 3 · عنصر 4

<script setup lang="ts">
const listData = Array.from({ length: 1000 }, (_, i) => `عنصر ${i + 1}`)
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-height="40">
    <template #default="{ item, index }">
      <div>العنصر {{ index }} · {{ item }}</div>
    </template>
  </LhVirtualList>
</template>

<script>
export default {
  data() {
    return {
      listData: Array.from({ length: 1000 }, (_, i) => `عنصر ${i + 1}`),
    }
  },
}
</script>

<template>
  <LhVirtualList :data="listData" :height="200" :item-height="40">
    <template #default="{ item, index }">
      <div>العنصر {{ index }} · {{ item }}</div>
    </template>
  </LhVirtualList>
</template>

ارتفاع ديناميكي

يُعيد itemSize ارتفاع كل عنصر (ويمكن أن يعيده بناءً على نتيجة قياس).

ارتفاع ديناميكي

عنصر 1

عنصر 2

عنصر 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) => `عنصر ${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>

ذاكرة العرض المسبق

يحدِّد overscan عدد الصفوف التي يُعالَج لها مسبقًا فوق النافذة المرئية وتحتها، لتقليل وميض الشاشة أثناء التمرير السريع.

overscan

العنصر 0 · عنصر 1

العنصر 1 · عنصر 2

العنصر 2 · عنصر 3

العنصر 3 · عنصر 4

العنصر 4 · عنصر 5

العنصر 5 · عنصر 6

العنصر 6 · عنصر 7

العنصر 7 · عنصر 8

العنصر 8 · عنصر 9

العنصر 9 · عنصر 10

العنصر 10 · عنصر 11

العنصر 11 · عنصر 12

العنصر 12 · عنصر 13

العنصر 13 · عنصر 14

العنصر 14 · عنصر 15

العنصر 15 · عنصر 16

<script setup lang="ts">
const listData = Array.from({ length: 1000 }, (_, i) => `عنصر ${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) => `عنصر ${i + 1}`),
    }
  },
}
</script>

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

API

LhVirtualList Props

اسم الخاصية	الوصف	النوع	القيمة الافتراضية
data	مصدر البيانات (يتولَّى فتحة default عرض العناصر)	any[]	—
height	ارتفاع الحاوية (الرقم يمثّل px)	string | number	—
itemHeight	ارتفاع العنصر في الوضع ثابت الارتفاع	number	—
itemSize	وضع الارتفاع الديناميكي: يُعيد مُستدعيها ارتفاع كل عنصر	(index: number) => number	—
overscan	عدد العناصر الإضافية للفحص المسبق	number	LH_VIRTUAL_OVERSCAN
sx	خصائص التخطيط السريع sx	LhSxProps	—

الفتحات: default (نطاقها { item, index }).

إتاحة الوصول

• الحاوية overflow: auto قابلة للتمرير بلوحة المفاتيح؛ والعناصر خارج النافذة ليست في DOM، فيحصل قارئ الشاشة عليها حسب الحاجة (وهي مفاضلة متأصلة في القوائم الطويلة، ويُنصح بتضييق النطاق عبر البحث/التصفية)
• وإن احتجت إلى جدول دلالي كامل فاستخدم Table (التي يقود تمريرها الافتراضي أيضًا دوال نقية في الطبقة الأساسية core)

تعريفات الأنواع

بنية الأنواع التي يُصدِّرها هذا المكوّن بلغة TypeScript كالتالي (مستخرجة آليًا من packages/components/virtual-list/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لعرض التعريف الكامل؛ لأوصاف الخصائص انظر جدول Props أعلاه):

LhVirtualListProps

export interface LhVirtualListProps {
  /** مصدر البيانات (يتولَّى فتحة default عرض العناصر) */
  data: any[]
  /** ارتفاع الحاوية (الرقم يمثّل px) */
  height: number | string
  /** ارتفاع العنصر في الوضع ثابت الارتفاع (يُختار بينه وبين itemSize؛ عند تمرير itemSize يُستخدم الارتفاع الديناميكي) */
  itemHeight?: number
  /** وضع الارتفاع الديناميكي: يُعيد مُستدعيها ارتفاع كل عنصر */
  itemSize?: (index: number) => number
  /** عدد العناصر الإضافية للفحص المسبق */
  overscan?: number
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

الثوابت

الثوابت العمومية التي يستخدمها هذا المكوّن كالتالي (يمكنك النقر على العنصر الذي يحمل الاسم نفسه في عمودي «النوع / القيمة الافتراضية» في جدول Props للانتقال إلى هنا):

LH_VIRTUAL_ITEM_SIZE _{(من @lh-ui/share/core/virtual-list)}

/** ارتفاع العنصر المُقدَّر افتراضيًا */
export const LH_VIRTUAL_ITEM_SIZE = 40