// 渲染 10000 條數(shù)據(jù)
const items = Array.from({ length: 10000 }, (_, i) => i)

// ? 傳統(tǒng)方式：創(chuàng)建 10000 個 DOM 節(jié)點
<div v-for="item in items" :key="item">{{ item }}</div>
// 結(jié)果：首次渲染緩慢、滾動卡頓、內(nèi)存占用高

npm install @vueuse/core
# 或
pnpm add @vueuse/core

import { useVirtualList } from '@vueuse/core'

const { list, containerProps, wrapperProps } = useVirtualList(
  items,    // 數(shù)據(jù)源
  options   // 配置選項
)

// 方式 1: 響應式引用
const items = ref([1, 2, 3, ...])

// 方式 2: 普通數(shù)組
const items = [1, 2, 3, ...]

// 方式 3: computed
const items = computed(() => originalData.filter(...))

interface ListItem<T> {
  index: number    // 在原數(shù)組中的索引
  data: T         // 原始數(shù)據(jù)
}

<div v-for="item in list" :key="item.index">
  <div>索引: {{ item.index }}</div>
  <div>數(shù)據(jù): {{ item.data }}</div>
</div>

<div v-bind="containerProps" style="height: 400px; overflow-y: auto;">
  <!-- 內(nèi)容 -->
</div>

<div v-bind="containerProps">
  <div v-bind="wrapperProps">
    <!-- 列表項 -->
  </div>
</div>

<script setup>
import { ref } from "vue";
import { useVirtualList } from "@vueuse/core";

const props = defineProps({
  items: {
    type: Array,
    default: () => [],
    required: true,
  },
  itemHeight: {
    type: Number,
    default: 50,
  },
  containerHeight: {
    type: Number,
    default: 400,
  },
});

const container = ref(null);

// ?? 關(guān)鍵配置：itemHeight 為固定數(shù)值
const { list, containerProps, wrapperProps } = useVirtualList(props.items, {
  itemHeight: props.itemHeight,  // 固定高度
  overscan: 5,
});
</script>

<template>
  <div
    ref="container"
    class="virtual-list-container"
    :style="{ height: `${containerHeight}px` }"  <!-- 固定容器高度 -->
    v-bind="containerProps"
  >
    <div class="virtual-list-wrapper" v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="virtual-list-item"
        :style="{ height: `${itemHeight}px` }"  <!-- 固定項目高度 -->
      >
        <div class="item-content">
          <span class="item-index">{{ item.data.id }}</span>
          <span class="item-text">{{ item.data.name }}</span>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.virtual-list-container {
  overflow: hidden;  /* ?? 關(guān)鍵：overflow hidden */
  border: 1px solid #e8e8e8;
  border-radius: 8px;
}

.virtual-list-item {
  display: flex;
  align-items: center;
  border-bottom: 1px solid #f0f0f0;
}
</style>

<script setup>
import { ref } from 'vue'
import FixedHeightVirtualList from './components/FixedHeightVirtualList.vue'

const items = ref(
  Array.from({ length: 1000 }, (_, index) => ({
    id: index + 1,
    name: `項目 ${index + 1}`
  }))
)
</script>

<template>
  <FixedHeightVirtualList
    :items="items"
    :item-height="50"
    :container-height="400"
  />
</template>

<script setup>
import { ref } from "vue";
import { useVirtualList } from "@vueuse/core";

const props = defineProps({
  items: {
    type: Array,
    default: () => [],
    required: true,
  },
  itemHeight: {
    type: Number,
    default: 50,
  },
  maxHeight: {
    type: Number,
    default: 500,
  },
});

const container = ref(null);

// ?? 關(guān)鍵配置：itemHeight 為固定數(shù)值
const { list, containerProps, wrapperProps } = useVirtualList(props.items, {
  itemHeight: props.itemHeight,
  overscan: 5,
});
</script>

<template>
  <div
    ref="container"
    class="virtual-list-container"
    :style="{ maxHeight: `${maxHeight}px` }"  <!-- ?? max-height 實現(xiàn)動態(tài) -->
    v-bind="containerProps"
  >
    <div class="virtual-list-wrapper" v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="virtual-list-item"
        :style="{ height: `${itemHeight}px` }"
      >
        <div class="item-content">
          <span class="item-index">{{ item.data.id }}</span>
          <span class="item-text">{{ item.data.name }}</span>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.virtual-list-container {
  overflow-y: auto;  /* ?? 關(guān)鍵：overflow-y auto */
  border: 1px solid #e8e8e8;
  border-radius: 8px;
}
</style>

<script setup>
import { ref } from 'vue'
import DynamicHeightVirtualList from './components/DynamicHeightVirtualList.vue'

// 數(shù)據(jù)量少
const fewItems = ref(
  Array.from({ length: 4 }, (_, index) => ({
    id: index + 1,
    name: `項目 ${index + 1}`
  }))
)

// 數(shù)據(jù)量多
const manyItems = ref(
  Array.from({ length: 1000 }, (_, index) => ({
    id: index + 1,
    name: `項目 ${index + 1}`
  }))
)
</script>

<template>
  <!-- 數(shù)據(jù)少時，容器高度 = 4 * 50 = 200px -->
  <DynamicHeightVirtualList
    :items="fewItems"
    :item-height="50"
    :max-height="400"
  />

  <!-- 數(shù)據(jù)多時，容器高度 = max-height = 400px，出現(xiàn)滾動條 -->
  <DynamicHeightVirtualList
    :items="manyItems"
    :item-height="50"
    :max-height="400"
  />
</template>

<script setup>
import { ref } from "vue";
import { useVirtualList } from "@vueuse/core";

const props = defineProps({
  items: {
    type: Array,
    default: () => [],
    required: true,
  },
  containerHeight: {
    type: Number,
    default: 400,
  },
});

const container = ref(null);

// ?? 關(guān)鍵：動態(tài)計算每個項的高度
const getItemHeight = (index) => {
  // 方式 1: 根據(jù)索引模式
  const heightPattern = index % 3;
  if (heightPattern === 0) return 60;  // 小項
  if (heightPattern === 1) return 80;  // 中項
  return 100;                          // 大項
  
  // 方式 2: 根據(jù)數(shù)據(jù)內(nèi)容
  // const item = props.items[index];
  // return item.type === 'large' ? 100 : 50;
  
  // 方式 3: 根據(jù)文本長度
  // const textLength = props.items[index].text.length;
  // return Math.max(50, Math.ceil(textLength / 20) * 30);
};

// ?? 關(guān)鍵配置：itemHeight 為函數(shù)
const { list, containerProps, wrapperProps } = useVirtualList(props.items, {
  itemHeight: getItemHeight,  // 函數(shù)，不是數(shù)值！
  overscan: 5,
});
</script>

<template>
  <div
    ref="container"
    class="virtual-list-container"
    :style="{ height: `${containerHeight}px` }"
    v-bind="containerProps"
  >
    <div class="virtual-list-wrapper" v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="virtual-list-item"
        :style="{ height: `${getItemHeight(item.index)}px` }"  <!-- 動態(tài)高度 -->
        :data-height="getItemHeight(item.index)"
      >
        <div class="item-content">
          <span class="item-index">{{ item.data.id }}</span>
          <div class="item-info">
            <span class="item-text">{{ item.data.name }}</span>
            <span class="item-height-tag">高度: {{ getItemHeight(item.index) }}px</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.virtual-list-container {
  overflow: hidden;
}

/* 根據(jù)高度添加不同的視覺樣式 */
.virtual-list-item[data-height="60"] {
  background: linear-gradient(135deg, #fff9e6 0%, #ffffff 100%);
}

.virtual-list-item[data-height="80"] {
  background: linear-gradient(135deg, #e6f7ff 0%, #ffffff 100%);
}

.virtual-list-item[data-height="100"] {
  background: linear-gradient(135deg, #f0f9ff 0%, #ffffff 100%);
}
</style>

<script setup>
import { ref } from 'vue'
import VariableHeightVirtualList from './components/VariableHeightVirtualList.vue'

const items = ref(
  Array.from({ length: 400 }, (_, index) => ({
    id: index + 1,
    name: `項目 ${index + 1}`
  }))
)
</script>

<template>
  <VariableHeightVirtualList
    :items="items"
    :container-height="450"
  />
</template>

// 示例 1: 基于索引的規(guī)律模式
const getItemHeight = (index) => {
  return 50 + (index % 3) * 25;  // 50, 75, 100 循環(huán)
};

// 示例 2: 基于數(shù)據(jù)類型
const getItemHeight = (index) => {
  const item = props.items[index];
  switch(item.type) {
    case 'header': return 80;
    case 'content': return 120;
    case 'footer': return 60;
    default: return 50;
  }
};

// 示例 3: 基于內(nèi)容長度
const getItemHeight = (index) => {
  const item = props.items[index];
  const textLength = item.description?.length || 0;
  const lines = Math.ceil(textLength / 40);  // 假設(shè)每行 40 字符
  return 50 + (lines - 1) * 20;  // 基礎(chǔ)高度 + 額外行高度
};

// 示例 4: 基于屬性組合
const getItemHeight = (index) => {
  const item = props.items[index];
  let height = 60;  // 基礎(chǔ)高度
  if (item.hasImage) height += 200;
  if (item.hasTags) height += 30;
  if (item.hasActions) height += 40;
  return height;
};

// ? 錯誤：隨機高度（不可預測）
const getItemHeight = (index) => {
  return 50 + Math.random() * 50;  // 每次調(diào)用結(jié)果不同！
};

// ? 錯誤：異步計算
const getItemHeight = async (index) => {
  const data = await fetchData(index);  // 不支持異步！
  return data.height;
};

// ? 正確：可預測、同步
const getItemHeight = (index) => {
  return props.items[index].preCalculatedHeight;  // 提前計算好的高度
};

<script setup>
import { ref } from "vue";
import { useVirtualList } from "@vueuse/core";

const props = defineProps({
  items: {
    type: Array,
    default: () => [],
    required: true,
  },
  maxHeight: {
    type: Number,
    default: 500,
  },
});

const container = ref(null);

// ?? 關(guān)鍵：動態(tài)計算每個項的高度
const getItemHeight = (index) => {
  const heightPattern = index % 3;
  if (heightPattern === 0) return 60;
  if (heightPattern === 1) return 80;
  return 100;
};

// ?? 關(guān)鍵配置：itemHeight 為函數(shù) + 容器使用 max-height
const { list, containerProps, wrapperProps } = useVirtualList(props.items, {
  itemHeight: getItemHeight,
  overscan: 5,
});
</script>

<template>
  <div
    ref="container"
    class="virtual-list-container"
    :style="{ maxHeight: `${maxHeight}px` }"  <!-- ?? max-height 動態(tài)容器 -->
    v-bind="containerProps"
  >
    <div class="virtual-list-wrapper" v-bind="wrapperProps">
      <div
        v-for="item in list"
        :key="item.index"
        class="virtual-list-item"
        :style="{ height: `${getItemHeight(item.index)}px` }"
        :data-height="getItemHeight(item.index)"
      >
        <div class="item-content">
          <span class="item-index">{{ item.data.id }}</span>
          <div class="item-info">
            <span class="item-text">{{ item.data.name }}</span>
            <span class="item-height-tag">高度: {{ getItemHeight(item.index) }}px</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.virtual-list-container {
  overflow-y: auto;  /* ?? 關(guān)鍵：overflow-y auto */
  border: 1px solid #e8e8e8;
  border-radius: 8px;
}
</style>

<script setup>
import { ref } from 'vue'
import FullyDynamicVirtualList from './components/FullyDynamicVirtualList.vue'

const items = ref(
  Array.from({ length: 200 }, (_, index) => ({
    id: index + 1,
    name: `項目 ${index + 1}`
  }))
)
</script>

<template>
  <FullyDynamicVirtualList
    :items="items"
    :max-height="600"
  />
</template>

<template>
  <!-- 數(shù)據(jù)少：容器自動縮小 -->
  <FullyDynamicVirtualList
    :items="[1, 2, 3]"
    :max-height="400"
  />
  <!-- 實際高度約: 60 + 80 + 100 = 240px -->

  <!-- 數(shù)據(jù)多：容器達到最大高度，顯示滾動條 -->
  <FullyDynamicVirtualList
    :items="Array(200)"
    :max-height="400"
  />
  <!-- 實際高度: 400px (max-height) -->
</template>

// 基礎(chǔ)配置
overscan: 5  // 默認值，適合大多數(shù)場景

// 快速滾動場景
overscan: 10  // 增加預渲染，防止白屏

// 性能敏感場景
overscan: 3  // 減少預渲染，降低開銷

// 移動端
overscan: 8  // 移動端滾動更快，建議增加

// ? 不推薦：每次都計算
const getItemHeight = (index) => {
  const item = props.items[index];
  return calculateComplexHeight(item);  // 復雜計算
};

// ? 推薦：緩存計算結(jié)果
const heightCache = new Map();

const getItemHeight = (index) => {
  if (heightCache.has(index)) {
    return heightCache.get(index);
  }
  
  const item = props.items[index];
  const height = calculateComplexHeight(item);
  heightCache.set(index, height);
  return height;
};

// 數(shù)據(jù)變化時清除緩存
watch(() => props.items, () => {
  heightCache.clear();
}, { deep: true });

// ? 不推薦：直接傳入響應式對象
const items = reactive([...]);

// ? 推薦：使用 ref
const items = ref([...]);

// ? 更好：使用 shallowRef（大數(shù)據(jù)量）
const items = shallowRef([...]);

// 數(shù)據(jù)量 > 50,000 時的優(yōu)化策略

// 1. 使用 shallowRef
const items = shallowRef(largeDataArray);

// 2. 增加 overscan
overscan: 15

// 3. 防抖滾動事件（如果需要自定義處理）
const handleScroll = useDebounceFn(() => {
  // 處理滾動
}, 16);  // 約 60fps

// 4. 虛擬滾動條（可選）
// 使用自定義滾動條替代原生滾動條

// ? 錯誤 1：在模板中直接訪問原數(shù)組
<template>
  <div v-for="item in items">  <!-- 錯誤！應該用 list -->
    {{ item }}
  </div>
</template>

// ? 正確：使用 list
<template>
  <div v-for="item in list">  <!-- 正確！-->
    {{ item.data }}
  </div>
</template>

// ? 錯誤 2：忘記綁定 props
<div class="container">  <!-- 錯誤！缺少 v-bind -->
  <div class="wrapper">  <!-- 錯誤！缺少 v-bind -->

// ? 正確：綁定 containerProps 和 wrapperProps
<div v-bind="containerProps">
  <div v-bind="wrapperProps">

// ? 錯誤 3：高度計算不準確
.item {
  height: 50px;
  padding: 10px;  /* 實際高度 = 50 + 20 = 70px */
}

// ? 正確：確保計算高度包含 padding/border
itemHeight: 70  // 或使用 box-sizing: border-box

// 1. 使用 box-sizing: border-box
.virtual-list-item {
  box-sizing: border-box;
  height: 50px;  /* 包含 padding 和 border */
  padding: 10px;
}

// 2. 確保高度計算準確
const getItemHeight = (index) => {
  const baseHeight = 50;
  const padding = 20;  // top + bottom
  const border = 2;    // top + bottom
  return baseHeight + padding + border;
};

// 1. 增加 overscan
overscan: 10

// 2. 添加骨架屏
<template>
  <div v-if="loading">
    <SkeletonItem v-for="i in 10" :key="i" />
  </div>
  <div v-else v-bind="containerProps">
    <!-- 虛擬列表 -->
  </div>
</template>

// 3. 預加載數(shù)據(jù)
onMounted(async () => {
  loading.value = true;
  items.value = await fetchData();
  loading.value = false;
});

// 方法 1: 計算滾動位置（固定高度）
const scrollToIndex = (index) => {
  const scrollTop = index * itemHeight;
  container.value.scrollTop = scrollTop;
};

// 方法 2: 計算滾動位置（動態(tài)高度）
const scrollToIndex = (index) => {
  let scrollTop = 0;
  for (let i = 0; i < index; i++) {
    scrollTop += getItemHeight(i);
  }
  container.value.scrollTop = scrollTop;
};

// 方法 3: 使用 scrollIntoView
const scrollToIndex = (index) => {
  // 需要在 list 中找到對應的元素
  const element = document.querySelector(`[data-index="${index}"]`);
  element?.scrollIntoView({ behavior: 'smooth', block: 'start' });
};

// ? 錯誤：直接賦值新數(shù)組
items.value = newData;  // 引用變化，滾動位置重置

// ? 正確：保持引用，修改內(nèi)容
// 方法 1: 使用 splice
items.value.splice(0, items.value.length, ...newData);

// 方法 2: 逐項更新
newData.forEach((item, index) => {
  items.value[index] = item;
});

// 方法 3: 記錄并恢復滾動位置
const scrollTop = container.value.scrollTop;
items.value = newData;
nextTick(() => {
  container.value.scrollTop = scrollTop;
});

import { ref, Ref } from 'vue'
import { useVirtualList, UseVirtualListOptions } from '@vueuse/core'

interface ListItem {
  id: number
  name: string
  description?: string
}

const items: Ref<ListItem[]> = ref([
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' }
])

const options: UseVirtualListOptions = {
  itemHeight: 50,
  overscan: 5
}

const { list, containerProps, wrapperProps } = useVirtualList(items, options)

// list 的類型是 ComputedRef<{ index: number; data: ListItem }[]>

// 在 SSR 環(huán)境中，需要注意以下幾點：

// 1. 容器高度必須明確
<div :style="{ height: '400px' }">  <!-- SSR 需要明確高度 -->

// 2. 避免在服務端計算滾動
import { onMounted } from 'vue'

const setupVirtualList = () => {
  if (typeof window === 'undefined') return  // SSR 環(huán)境跳過
  
  const { list, containerProps, wrapperProps } = useVirtualList(...)
  return { list, containerProps, wrapperProps }
}

// 3. 使用 ClientOnly 組件（Nuxt.js）
<ClientOnly>
  <VirtualList :items="items" />
</ClientOnly>

// useVirtualList 配置
const { list, containerProps, wrapperProps } = useVirtualList(items, {
  itemHeight: 50 | ((index: number) => number),  // 必需
  overscan: 5                                     // 可選，默認 5
})

itemHeight: 50

itemHeight: (index) => {
  return index % 2 === 0 ? 60 : 80
}

<div :style="{ height: '400px' }" v-bind="containerProps">

<div :style="{ maxHeight: '400px' }" v-bind="containerProps">

<div v-bind="containerProps" :style="{ height: '400px' }">
  <div v-bind="wrapperProps">
    <div v-for="item in list" :key="item.index">
      {{ item.data }}
    </div>
  </div>
</div>

# 1. 克隆項目
git clone https://github.com/ilcherry/virtuallist-examples

# 2. 安裝依賴
cd vue3-sample
pnpm install

# 3. 運行開發(fā)服務器
pnpm dev

# 4. 訪問
# 打開瀏覽器訪問 http://localhost:5173