高性能虚拟列表实现：从原理到生产级组件

1
class FixedHeightVirtualList {
2
  constructor(container, options) {
3
    this.container = container;
4
    this.itemHeight = options.itemHeight;
5
    this.renderItem = options.renderItem;
6
    this.data = options.data || [];
7
    this.overscan = options.overscan || 5; // 上下各多渲染几个，减少白屏
8

9
    // 创建 DOM 结构
10
    this.phantom = document.createElement('div');
11
    this.phantom.style.position = 'relative';
12
    this.container.appendChild(this.phantom);
13

14
    this.contentWrapper = document.createElement('div');
15
    this.contentWrapper.style.position = 'absolute';
16
    this.contentWrapper.style.top = '0';
17
    this.contentWrapper.style.left = '0';
18
    this.contentWrapper.style.width = '100%';
19
    this.phantom.appendChild(this.contentWrapper);
20

21
    // 状态
22
    this.startIndex = 0;
23
    this.endIndex = 0;
24
    this.visibleItems = [];
25

26
    // 绑定事件
27
    this._onScroll = this._onScroll.bind(this);
28
    this.container.addEventListener('scroll', this._onScroll, { passive: true });
29

30
    this._update();
31
  }
32

33
  setData(data) {
34
    this.data = data;
35
    this._update();
36
  }
37

38
  _onScroll() {
39
    this._update();
40
  }
41

42
  _update() {
43
    const scrollTop = this.container.scrollTop;
44
    const containerHeight = this.container.clientHeight;
45
    const totalCount = this.data.length;
46

47
    // 计算可见范围
48
    let startIndex = Math.floor(scrollTop / this.itemHeight) - this.overscan;
49
    let endIndex =
50
      Math.ceil((scrollTop + containerHeight) / this.itemHeight) + this.overscan;
51

52
    startIndex = Math.max(0, startIndex);
53
    endIndex = Math.min(totalCount, endIndex);
54

55
    // 如果范围没变，跳过渲染
56
    if (startIndex === this.startIndex && endIndex === this.endIndex) return;
57

58
    this.startIndex = startIndex;
59
    this.endIndex = endIndex;
60

61
    // 设置总高度（撑开滚动条）
62
    const totalHeight = totalCount * this.itemHeight;
63
    this.phantom.style.height = totalHeight + 'px';
64

65
    // 设置内容偏移
66
    const offsetTop = startIndex * this.itemHeight;
67
    this.contentWrapper.style.transform = `translateY(${offsetTop}px)`;
68

69
    // 渲染可见项
70
    this._renderItems();
71
  }
72

73
  _renderItems() {
74
    // 清空旧内容
75
    this.contentWrapper.innerHTML = '';
76

77
    const fragment = document.createDocumentFragment();
78
    for (let i = this.startIndex; i < this.endIndex; i++) {
79
      const item = this.renderItem(this.data[i], i);
80
      item.style.height = this.itemHeight + 'px';
81
      item.style.boxSizing = 'border-box';
82
      fragment.appendChild(item);
83
    }
84
    this.contentWrapper.appendChild(fragment);
85
  }
86

87
  destroy() {
88
    this.container.removeEventListener('scroll', this._onScroll);
89
    this.phantom.remove();
90
  }
91
}
92

93
// 使用
94
const container = document.getElementById('virtual-list');
95
const data = Array.from({ length: 100000 }, (_, i) => ({
96
  id: i,
97
  text: `Item #${i} — ${Math.random().toString(36).slice(2)}`,
98
}));
99

100
const list = new FixedHeightVirtualList(container, {
101
  itemHeight: 50,
102
  overscan: 5,
103
  data,
104
  renderItem(item, index) {
105
    const div = document.createElement('div');
106
    div.className = 'list-item';
107
    div.textContent = item.text;
108
    div.style.borderBottom = '1px solid #eee';
109
    div.style.padding = '12px 16px';
110
    div.style.lineHeight = '26px';
111
    return div;
112
  },
113
});

1
class DynamicHeightVirtualList {
2
  constructor(container, options) {
3
    this.container = container;
4
    this.renderItem = options.renderItem;
5
    this.data = options.data || [];
6
    this.estimatedHeight = options.estimatedHeight || 80; // 预估高度
7
    this.overscan = options.overscan || 5;
8

9
    // 缓存每项的实际高度和位置
10
    // positions[i] = { top, bottom, height }
11
    this.positions = [];
12
    this._initPositions();
13

14
    // DOM 结构
15
    this.phantom = document.createElement('div');
16
    this.phantom.style.position = 'relative';
17
    this.container.appendChild(this.phantom);
18

19
    this.contentWrapper = document.createElement('div');
20
    this.contentWrapper.style.position = 'absolute';
21
    this.contentWrapper.style.top = '0';
22
    this.contentWrapper.style.left = '0';
23
    this.contentWrapper.style.width = '100%';
24
    this.phantom.appendChild(this.contentWrapper);
25

26
    // 状态
27
    this.startIndex = 0;
28
    this.endIndex = 0;
29

30
    // 绑定事件
31
    this._onScroll = this._onScroll.bind(this);
32
    this.container.addEventListener('scroll', this._onScroll, { passive: true });
33

34
    this._update();
35
  }
36

37
  _initPositions() {
38
    this.positions = this.data.map((_, index) => ({
39
      index,
40
      height: this.estimatedHeight,
41
      top: index * this.estimatedHeight,
42
      bottom: (index + 1) * this.estimatedHeight,
43
    }));
44
  }
45

46
  // 二分搜索：根据 scrollTop 找到 startIndex
47
  _binarySearch(scrollTop) {
48
    let low = 0;
49
    let high = this.positions.length - 1;
50
    let result = 0;
51

52
    while (low <= high) {
53
      const mid = Math.floor((low + high) / 2);
54
      const midBottom = this.positions[mid].bottom;
55

56
      if (midBottom === scrollTop) {
57
        return mid + 1;
58
      } else if (midBottom < scrollTop) {
59
        low = mid + 1;
60
      } else {
61
        // midBottom > scrollTop
62
        result = mid;
63
        high = mid - 1;
64
      }
65
    }
66
    return result;
67
  }
68

69
  // 渲染后更新实际高度
70
  _updatePositions() {
71
    const items = this.contentWrapper.children;
72

73
    for (let i = 0; i < items.length; i++) {
74
      const item = items[i];
75
      const index = this.startIndex + i;
76
      if (index >= this.positions.length) break;
77

78
      const rect = item.getBoundingClientRect();
79
      const actualHeight = rect.height;
80
      const oldHeight = this.positions[index].height;
81

82
      // 只在高度变化时更新
83
      if (Math.abs(actualHeight - oldHeight) > 0.5) {
84
        const diff = actualHeight - oldHeight;
85
        this.positions[index].height = actualHeight;
86
        this.positions[index].bottom += diff;
87

88
        // 更新后续所有项的位置
89
        for (let j = index + 1; j < this.positions.length; j++) {
90
          this.positions[j].top = this.positions[j - 1].bottom;
91
          this.positions[j].bottom = this.positions[j].top + this.positions[j].height;
92
        }
93
      }
94
    }
95
  }
96

97
  _getTotalHeight() {
98
    const last = this.positions[this.positions.length - 1];
99
    return last ? last.bottom : 0;
100
  }
101

102
  _onScroll() {
103
    this._update();
104
  }
105

106
  _update() {
107
    const scrollTop = this.container.scrollTop;
108
    const containerHeight = this.container.clientHeight;
109

110
    // 二分查找 startIndex
111
    let startIndex = this._binarySearch(scrollTop) - this.overscan;
112
    startIndex = Math.max(0, startIndex);
113

114
    // 从 startIndex 开始，累加高度找到 endIndex
115
    let endIndex = startIndex;
116
    let accHeight = this.positions[startIndex]
117
      ? this.positions[startIndex].top - scrollTop
118
      : 0;
119

120
    while (endIndex < this.data.length && accHeight < containerHeight) {
121
      accHeight += this.positions[endIndex].height;
122
      endIndex++;
123
    }
124
    endIndex = Math.min(this.data.length, endIndex + this.overscan);
125

126
    this.startIndex = startIndex;
127
    this.endIndex = endIndex;
128

129
    // 更新 phantom 总高度
130
    this.phantom.style.height = this._getTotalHeight() + 'px';
131

132
    // 偏移
133
    const offsetTop = this.positions[startIndex]
134
      ? this.positions[startIndex].top
135
      : 0;
136
    this.contentWrapper.style.transform = `translateY(${offsetTop}px)`;
137

138
    // 渲染
139
    this._renderItems();
140

141
    // 渲染后测量实际高度并更新
142
    requestAnimationFrame(() => {
143
      this._updatePositions();
144
      // 重新更新 phantom 高度（可能因为实际高度和预估不同而变化）
145
      this.phantom.style.height = this._getTotalHeight() + 'px';
146
    });
147
  }
148

149
  _renderItems() {
150
    this.contentWrapper.innerHTML = '';
151
    const fragment = document.createDocumentFragment();
152

153
    for (let i = this.startIndex; i < this.endIndex; i++) {
154
      const item = this.renderItem(this.data[i], i);
155
      item.dataset.index = i;
156
      fragment.appendChild(item);
157
    }
158

159
    this.contentWrapper.appendChild(fragment);
160
  }
161

162
  // 滚动到指定索引
163
  scrollToIndex(index) {
164
    if (index >= 0 && index < this.positions.length) {
165
      this.container.scrollTop = this.positions[index].top;
166
    }
167
  }
168

169
  destroy() {
170
    this.container.removeEventListener('scroll', this._onScroll);
171
    this.phantom.remove();
172
  }
173
}

1
// 使用前缀和数组优化位置查询
2
class PrefixSumPositionCache {
3
  constructor(estimatedHeight, count) {
4
    this.heights = new Float64Array(count).fill(estimatedHeight);
5
    this.prefixSum = new Float64Array(count + 1);
6
    this._rebuildPrefixSum();
7
  }
8

9
  _rebuildPrefixSum() {
10
    this.prefixSum[0] = 0;
11
    for (let i = 0; i < this.heights.length; i++) {
12
      this.prefixSum[i + 1] = this.prefixSum[i] + this.heights[i];
13
    }
14
  }
15

16
  // 更新某项高度 —— O(n)，但只在高度变化时调用
17
  updateHeight(index, newHeight) {
18
    const oldHeight = this.heights[index];
19
    if (Math.abs(newHeight - oldHeight) < 0.5) return false;
20

21
    const diff = newHeight - oldHeight;
22
    this.heights[index] = newHeight;
23

24
    // 只更新 index 之后的前缀和
25
    for (let i = index + 1; i <= this.heights.length; i++) {
26
      this.prefixSum[i] += diff;
27
    }
28
    return true;
29
  }
30

31
  // 获取某项的 top 位置 —— O(1)
32
  getTop(index) {
33
    return this.prefixSum[index];
34
  }
35

36
  // 获取某项的 bottom 位置 —— O(1)
37
  getBottom(index) {
38
    return this.prefixSum[index + 1];
39
  }
40

41
  // 总高度 —— O(1)
42
  getTotalHeight() {
43
    return this.prefixSum[this.heights.length];
44
  }
45

46
  // 二分查找 scrollTop 对应的 index —— O(log n)
47
  findIndex(scrollTop) {
48
    let low = 0;
49
    let high = this.heights.length - 1;
50
    let result = 0;
51

52
    while (low <= high) {
53
      const mid = (low + high) >>> 1;
54
      if (this.prefixSum[mid + 1] <= scrollTop) {
55
        low = mid + 1;
56
      } else {
57
        result = mid;
58
        high = mid - 1;
59
      }
60
    }
61
    return result;
62
  }
63
}

1
class AnchoredVirtualList extends ResizeObserverVirtualList {
2
  constructor(container, options) {
3
    super(container, options);
4
    this._lastScrollTop = 0;
5
    this._anchorIndex = 0;
6
    this._anchorOffset = 0;
7
  }
8

9
  _onScroll() {
10
    const scrollTop = this.container.scrollTop;
11

12
    // 记录锚点：当前视口顶部对应的元素和偏移
13
    const anchorIndex = this._binarySearch(scrollTop);
14
    const anchorTop = this.positions[anchorIndex]?.top || 0;
15
    this._anchorIndex = anchorIndex;
16
    this._anchorOffset = scrollTop - anchorTop;
17
    this._lastScrollTop = scrollTop;
18

19
    this._update();
20
  }
21

22
  // 当上方元素高度变化时，修正滚动位置
23
  _recalculatePositions() {
24
    const oldAnchorTop = this.positions[this._anchorIndex]?.top || 0;
25

26
    super._recalculatePositions();
27

28
    const newAnchorTop = this.positions[this._anchorIndex]?.top || 0;
29
    const diff = newAnchorTop - oldAnchorTop;
30

31
    if (Math.abs(diff) > 1) {
32
      // 修正滚动位置，保持锚点元素在视口中的相对位置不变
33
      this.container.scrollTop += diff;
34
      this._lastScrollTop = this.container.scrollTop;
35
    }
36
  }
37
}

1
class InfiniteVirtualList extends AnchoredVirtualList {
2
  constructor(container, options) {
3
    super(container, options);
4
    this.loadMore = options.loadMore; // 加载更多数据的回调
5
    this.isLoading = false;
6
    this.hasMore = true;
7
    this.loadThreshold = options.loadThreshold || 5; // 距离底部多少项时触发
8

9
    // 创建哨兵元素
10
    this.sentinel = document.createElement('div');
11
    this.sentinel.style.height = '1px';
12
    this.sentinel.className = 'infinite-scroll-sentinel';
13
    this.container.appendChild(this.sentinel);
14

15
    // 使用 IntersectionObserver 监听哨兵
16
    this.intersectionObserver = new IntersectionObserver(
17
      (entries) => {
18
        if (entries[0].isIntersecting && !this.isLoading && this.hasMore) {
19
          this._loadMore();
20
        }
21
      },
22
      {
23
        root: this.container,
24
        rootMargin: '0px 0px 200px 0px', // 提前 200px 触发
25
      }
26
    );
27
    this.intersectionObserver.observe(this.sentinel);
28
  }
29

30
  async _loadMore() {
31
    this.isLoading = true;
32
    this._showLoading();
33

34
    try {
35
      const newItems = await this.loadMore(this.data.length);
36

37
      if (!newItems || newItems.length === 0) {
38
        this.hasMore = false;
39
        this._showEndMessage();
40
        return;
41
      }
42

43
      // 追加数据
44
      this.data = [...this.data, ...newItems];
45

46
      // 初始化新项的位置
47
      const lastPos = this.positions[this.positions.length - 1];
48
      const lastBottom = lastPos ? lastPos.bottom : 0;
49

50
      for (let i = 0; i < newItems.length; i++) {
51
        const index = this.positions.length;
52
        this.positions.push({
53
          index,
54
          height: this.estimatedHeight,
55
          top: lastBottom + i * this.estimatedHeight,
56
          bottom: lastBottom + (i + 1) * this.estimatedHeight,
57
        });
58
      }
59

60
      this._update();
61
    } catch (error) {
62
      console.error('加载失败:', error);
63
      this._showError();
64
    } finally {
65
      this.isLoading = false;
66
      this._hideLoading();
67
    }
68
  }
69

70
  _showLoading() {
71
    this.sentinel.textContent = '加载中...';
72
    this.sentinel.style.height = '40px';
73
    this.sentinel.style.textAlign = 'center';
74
    this.sentinel.style.lineHeight = '40px';
75
  }
76

77
  _hideLoading() {
78
    this.sentinel.textContent = '';
79
    this.sentinel.style.height = '1px';
80
  }
81

82
  _showEndMessage() {
83
    this.sentinel.textContent = '没有更多了';
84
    this.sentinel.style.height = '40px';
85
    this.sentinel.style.textAlign = 'center';
86
    this.sentinel.style.lineHeight = '40px';
87
    this.sentinel.style.color = '#999';
88
    this.intersectionObserver.disconnect();
89
  }
90

91
  _showError() {
92
    this.sentinel.innerHTML = '加载失败，<a href="#">点击重试</a>';
93
    this.sentinel.querySelector('a')?.addEventListener('click', (e) => {
94
      e.preventDefault();
95
      this._loadMore();
96
    });
97
  }
98

99
  destroy() {
100
    this.intersectionObserver.disconnect();
101
    this.sentinel.remove();
102
    super.destroy();
103
  }
104
}
105

106
// 使用
107
const list = new InfiniteVirtualList(container, {
108
  estimatedHeight: 80,
109
  overscan: 5,
110
  data: initialData,
111
  renderItem(item, index) {
112
    const div = document.createElement('div');
113
    div.className = 'feed-item';
114
    div.innerHTML = `
115
      <h3>${item.title}</h3>
116
      <p>${item.content}</p>
117
      <span class="meta">${item.author} · ${item.time}</span>
118
    `;
119
    return div;
120
  },
121
  async loadMore(offset) {
122
    const response = await fetch(`/api/feed?offset=${offset}&limit=20`);
123
    const data = await response.json();
124
    return data.items;
125
  },
126
});

1
// ❌ 每次更新都清空重建
2
_renderItems() {
3
  this.contentWrapper.innerHTML = '';
4
  // ... 重新创建所有元素
5
}
6

7
// ✅ DOM 复用（对象池模式）
8
class DOMPool {
9
  constructor(createFn, recycleFn) {
10
    this.pool = [];
11
    this.createFn = createFn;
12
    this.recycleFn = recycleFn;
13
  }
14

15
  acquire() {
16
    return this.pool.pop() || this.createFn();
17
  }
18

19
  release(element) {
20
    this.recycleFn(element);
21
    this.pool.push(element);
22
  }
23
}
24

25
// 使用 DOM 复用
26
const domPool = new DOMPool(
27
  () => {
28
    const div = document.createElement('div');
29
    div.className = 'list-item';
30
    return div;
31
  },
32
  (el) => {
33
    el.textContent = '';
34
    el.style.cssText = '';
35
  }
36
);