From bb28f010e359982f2f8114acb3c7b825c04af90e Mon Sep 17 00:00:00 2001
From: sanbuphy <physicoada@gmail.com>
Date: Sun, 18 Jan 2026 23:59:25 +0800
Subject: [PATCH] feat: add virtual scrolling demo and fix build hanging issues

---
 .../VirtualScrollingDemo.vue                  | 185 ++++++++++++++++++
 .../queue-design/DelayedMessageDemo.vue       |   6 +-
 .../tracking-design/DataPipelineDemo.vue      |  14 +-
 docs/.vitepress/theme/index.js                |   2 +
 docs/zh-cn/appendix/frontend-performance.md   |  16 ++
 5 files changed, 219 insertions(+), 4 deletions(-)
 create mode 100644 docs/.vitepress/theme/components/appendix/frontend-performance/VirtualScrollingDemo.vue

diff --git a/docs/.vitepress/theme/components/appendix/frontend-performance/VirtualScrollingDemo.vue b/docs/.vitepress/theme/components/appendix/frontend-performance/VirtualScrollingDemo.vue
new file mode 100644
index 0000000..16bf2a5
--- /dev/null
+++ b/docs/.vitepress/theme/components/appendix/frontend-performance/VirtualScrollingDemo.vue
@@ -0,0 +1,185 @@
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+
+const TOTAL_ITEMS = 10000
+const ITEM_HEIGHT = 50
+const CONTAINER_HEIGHT = 400
+
+// Generate mock data
+const items = Array.from({ length: TOTAL_ITEMS }, (_, i) => ({
+  id: i,
+  content: `Item #${i + 1} - This is a long list item content to simulate real data.`
+}))
+
+const scrollTop = ref(0)
+const containerRef = ref(null)
+
+// Virtual scrolling calculations
+const startIndex = computed(() => Math.floor(scrollTop.value / ITEM_HEIGHT))
+const endIndex = computed(() => Math.min(TOTAL_ITEMS, startIndex.value + Math.ceil(CONTAINER_HEIGHT / ITEM_HEIGHT) + 2))
+const visibleItems = computed(() => {
+  return items.slice(startIndex.value, endIndex.value).map(item => ({
+    ...item,
+    top: item.id * ITEM_HEIGHT
+  }))
+})
+
+const totalHeight = TOTAL_ITEMS * ITEM_HEIGHT
+
+const onScroll = (e) => {
+  scrollTop.value = e.target.scrollTop
+}
+
+// Stats
+const renderedCount = computed(() => visibleItems.value.length)
+</script>
+
+<template>
+  <div class="demo-container">
+    <div class="controls">
+      <div class="stat-box">
+        <div class="stat-label">Total Items</div>
+        <div class="stat-value">{{ TOTAL_ITEMS.toLocaleString() }}</div>
+      </div>
+      <div class="stat-box highlight">
+        <div class="stat-label">Rendered DOM Nodes</div>
+        <div class="stat-value">{{ renderedCount }}</div>
+      </div>
+      <div class="stat-box">
+        <div class="stat-label">Memory Saved</div>
+        <div class="stat-value">~{{ ((1 - renderedCount / TOTAL_ITEMS) * 100).toFixed(1) }}%</div>
+      </div>
+    </div>
+
+    <div 
+      class="scroll-container" 
+      ref="containerRef"
+      @scroll="onScroll"
+      :style="{ height: CONTAINER_HEIGHT + 'px' }"
+    >
+      <div class="scroll-phantom" :style="{ height: totalHeight + 'px' }"></div>
+      <div class="visible-list">
+        <div 
+          v-for="item in visibleItems" 
+          :key="item.id"
+          class="list-item"
+          :style="{ transform: `translateY(${item.top}px)`, height: ITEM_HEIGHT + 'px' }"
+        >
+          <span class="item-index">{{ item.id + 1 }}</span>
+          <span class="item-content">{{ item.content }}</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="explanation">
+      <p>
+        <strong>How it works:</strong> Instead of rendering all {{ TOTAL_ITEMS }} items at once, 
+        we only render the items currently visible in the viewport (plus a small buffer). 
+        As you scroll, we calculate which items should be visible and position them absolutely 
+        to create the illusion of a full list.
+      </p>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.demo-container {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 16px;
+  background-color: var(--vp-c-bg-soft);
+}
+
+.controls {
+  display: flex;
+  gap: 16px;
+  margin-bottom: 16px;
+  flex-wrap: wrap;
+}
+
+.stat-box {
+  background-color: var(--vp-c-bg);
+  padding: 12px;
+  border-radius: 6px;
+  flex: 1;
+  min-width: 120px;
+  text-align: center;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.stat-box.highlight {
+  border-color: var(--vp-c-brand);
+  background-color: var(--vp-c-brand-dimm);
+}
+
+.stat-label {
+  font-size: 12px;
+  color: var(--vp-c-text-2);
+  margin-bottom: 4px;
+}
+
+.stat-value {
+  font-size: 20px;
+  font-weight: bold;
+  color: var(--vp-c-text-1);
+}
+
+.scroll-container {
+  overflow-y: auto;
+  position: relative;
+  background-color: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+}
+
+.scroll-phantom {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: -1;
+}
+
+.visible-list {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 100%;
+  pointer-events: none; /* Let scroll events pass through to container */
+}
+
+.list-item {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  padding: 0 16px;
+  border-bottom: 1px solid var(--vp-c-divider);
+  box-sizing: border-box;
+  background-color: var(--vp-c-bg); /* Ensure background covers phantom */
+}
+
+.item-index {
+  font-weight: bold;
+  color: var(--vp-c-brand);
+  width: 50px;
+  flex-shrink: 0;
+}
+
+.item-content {
+  color: var(--vp-c-text-1);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.explanation {
+  margin-top: 16px;
+  font-size: 14px;
+  color: var(--vp-c-text-2);
+  line-height: 1.5;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/appendix/queue-design/DelayedMessageDemo.vue b/docs/.vitepress/theme/components/appendix/queue-design/DelayedMessageDemo.vue
index d20a20c..5582eaa 100644
--- a/docs/.vitepress/theme/components/appendix/queue-design/DelayedMessageDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/queue-design/DelayedMessageDemo.vue
@@ -177,7 +177,7 @@
 </template>
 
 <script setup>
-import { ref, computed, onUnmounted } from 'vue'
+import { ref, computed, onMounted, onUnmounted } from 'vue'
 
 const selectedScenario = ref('order')
 const sending = ref(false)
@@ -286,7 +286,9 @@ const updateTimers = () => {
   })
 }
 
-timer = setInterval(updateTimers, 1000)
+onMounted(() => {
+  timer = setInterval(updateTimers, 1000)
+})
 
 onUnmounted(() => {
   if (timer) {
diff --git a/docs/.vitepress/theme/components/appendix/tracking-design/DataPipelineDemo.vue b/docs/.vitepress/theme/components/appendix/tracking-design/DataPipelineDemo.vue
index 251abd0..d2cf7f4 100644
--- a/docs/.vitepress/theme/components/appendix/tracking-design/DataPipelineDemo.vue
+++ b/docs/.vitepress/theme/components/appendix/tracking-design/DataPipelineDemo.vue
@@ -139,7 +139,7 @@
 </template>
 
 <script setup>
-import { ref, onMounted } from 'vue'
+import { ref, onMounted, onUnmounted } from 'vue'
 
 const currentStep = ref(-1)
 const isPlaying = ref(false)
@@ -210,6 +210,7 @@ const dataFlow = ref([
 ])
 
 let animationInterval = null
+let dataFlowInterval = null
 
 const startAnimation = () => {
   if (isPlaying.value) return
@@ -241,13 +242,22 @@ const formatNumber = (num) => {
 
 onMounted(() => {
   // 模拟实时数据流
-  setInterval(() => {
+  dataFlowInterval = setInterval(() => {
     dataFlow.value = dataFlow.value.map((item) => ({
       ...item,
       count: item.count + Math.floor(Math.random() * 100) - 50
     }))
   }, 2000)
 })
+
+onUnmounted(() => {
+  if (dataFlowInterval) {
+    clearInterval(dataFlowInterval)
+  }
+  if (animationInterval) {
+    clearInterval(animationInterval)
+  }
+})
 </script>
 
 <style scoped>
diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js
index 7f70489..9a3296d 100644
--- a/docs/.vitepress/theme/index.js
+++ b/docs/.vitepress/theme/index.js
@@ -137,6 +137,7 @@ import ImageOptimizationDemo from './components/appendix/frontend-performance/Im
 import LazyLoadingDemo from './components/appendix/frontend-performance/LazyLoadingDemo.vue'
 import CachingStrategyDemo from './components/appendix/frontend-performance/CachingStrategyDemo.vue'
 import CriticalRenderingPathDemo from './components/appendix/frontend-performance/CriticalRenderingPathDemo.vue'
+import VirtualScrollingDemo from './components/appendix/frontend-performance/VirtualScrollingDemo.vue'
 
 // Canvas Intro Components
 import CanvasBasicsDemo from './components/appendix/canvas-intro/CanvasBasicsDemo.vue'
@@ -375,6 +376,7 @@ export default {
     app.component('LazyLoadingDemo', LazyLoadingDemo)
     app.component('CachingStrategyDemo', CachingStrategyDemo)
     app.component('CriticalRenderingPathDemo', CriticalRenderingPathDemo)
+    app.component('VirtualScrollingDemo', VirtualScrollingDemo)
 
     // Canvas Intro Components Registration
     app.component('CanvasBasicsDemo', CanvasBasicsDemo)
diff --git a/docs/zh-cn/appendix/frontend-performance.md b/docs/zh-cn/appendix/frontend-performance.md
index 7beb70b..4655575 100644
--- a/docs/zh-cn/appendix/frontend-performance.md
+++ b/docs/zh-cn/appendix/frontend-performance.md
@@ -306,6 +306,22 @@ document.body.appendChild(fragment)
 
 **注意**：不要滥用合成层，过多会消耗内存。
 
+### 3.6 虚拟列表 (Virtual List)
+
+当需要展示成千上万条数据时（如长列表、聊天记录），如果直接渲染所有 DOM 节点，会导致：
+- **DOM 节点过多**：占用大量内存
+- **渲染缓慢**：样式计算和布局耗时增加
+- **滚动卡顿**：浏览器无法维持 60fps
+
+**解决方案**：只渲染**可视区域**内的元素，加上少量缓冲区。
+
+<VirtualScrollingDemo />
+
+**核心原理**：
+1. 计算可视区域能容纳多少个元素。
+2. 监听滚动事件，根据 `scrollTop` 计算当前应该渲染数据的 `startIndex` 和 `endIndex`。
+3. 使用 `padding-top` 或 `transform` 将渲染的内容定位到正确位置。
+
 ---
 
 ## 4. JavaScript 优化