# taro-virtual-scroll

**Repository Path**: ocean_vane/taro-virtual-scroll

## Basic Information

- **Project Name**: taro-virtual-scroll
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Taro 虚拟滚动示例项目

> **框架**: Taro 4.1.8 + React 18 | **语言**: TypeScript | **平台**: 多端小程序 / H5 / RN

本项目演示了在 Taro 中实现页面级虚拟滚动评论列表的完整方案，包含动态高度、分页加载、性能监控与多项性能优化。项目同时保留了产品详情区域，实现“商品介绍 + 评论列表”的首页展示效果。

此外，新增了 **话题广场 (Topics Page)**，展示了更复杂的虚拟列表应用场景，包括分类筛选和吸顶效果。详情请参阅 [话题广场文档](./TOPICS_PAGE_README.md)。

---

## ✨ 主要特性

- **页面级虚拟滚动**：不依赖 `ScrollView`，直接监听页面滚动，支持长列表渲染。
- **动态高度支持**：评论内容长度不一，通过高度缓存 + 前缀和计算确保滚动稳定无抖动。
- **分页加载**：每次上拉自动加载 20 条评论，总量 100 条，模拟真实网络延迟。
- **性能优化**：批量 DOM 查询、前缀和缓存、RAF 批处理、懒加载头像等多项优化方案。
- **实时调试面板**：展示可见范围、总高度、缓存命中等关键指标，可随时开启/关闭。
- **组件化架构**：虚拟列表、评论项、加载状态、调试面板均拆分为独立组件，类型定义与配置常量集中管理。

---

## 🧱 项目结构

```
myApp/
├── src/
│   ├── pages/
│   │   └── index/
│   │       ├── components/
│   │       │   ├── CommentItem.tsx
│   │       │   ├── DebugPanel.tsx
│   │       │   ├── LoadMore.tsx
│   │       │   ├── VirtualCommentList.tsx
│   │       │   └── index.ts
│   │       ├── constants.ts          # 虚拟滚动配置与评论模板
│   │       ├── index.tsx             # 页面入口，负责数据与状态
│   │       ├── index.css
│   │       └── types.ts              # Comment、VirtualScrollMetrics 等类型
│   ├── app.ts / app.config.ts
│   └── ...
├── PERFORMANCE_OPTIMIZATION.md       # 性能优化实施细节
├── COMPONENT_REFACTORING.md          # 组件拆分记录
├── DYNAMIC_HEIGHT_README.md          # 动态高度方案说明
├── FLICKER_FIX.md                    # 闪烁问题解决记录
├── PAGINATION_README.md              # 分页实现说明
├── VIRTUAL_SCROLL_README.md          # 初版虚拟滚动方案
└── README.md                         # 本文档
```

---

## 🧩 核心组件简介

| 组件/文件                | 职责说明                                                                      |
| ------------------------ | ----------------------------------------------------------------------------- |
| `VirtualCommentList.tsx` | 虚拟滚动核心逻辑：可见范围计算、批量高度测量、分页触发、性能指标回调          |
| `CommentItem.tsx`        | 单条评论渲染，使用 `transform: translateY` 绝对定位并懒加载头像               |
| `LoadMore.tsx`           | 加载中 / 无更多 / 空态的统一展示                                              |
| `DebugPanel.tsx`         | 调试面板，实时显示滚动指标，可一键隐藏                                        |
| `constants.ts`           | 虚拟滚动配置、评论模板集中管理                                                |
| `types.ts`               | `Comment`、`VirtualItem`、`VirtualScrollMetrics`、`DebugPanelData` 等类型定义 |

---

## ⚙️ 运行与构建

```bash
# 安装依赖
yarn install

# 小程序 / H5 开发模式（根据需求选择平台）
yarn dev:weapp     # 微信小程序
# yarn dev:h5     # H5
# yarn dev:rn     # React Native

# 构建生产包
yarn build:weapp
# 可根据平台执行 build:swan / build:alipay / build:h5 等脚本
```

> 详细脚本位于 `package.json` 的 `scripts` 字段中，覆盖 Taro 支持的主流平台。

---

## 🚀 已实施的性能优化

| 优化项                 | 描述                                                | 效果                           |
| ---------------------- | --------------------------------------------------- | ------------------------------ |
| **批量 DOM 查询**      | 将逐元素的 `createSelectorQuery` 合并为一次批量查询 | DOM 查询次数 **20-30 倍下降**  |
| **前缀和高度缓存**     | 使用累积高度数组计算 `top` 与总高度                 | 位置计算复杂度 **O(n) → O(1)** |
| **只测量未缓存项目**   | 过滤已知高度列表                                    | 测量次数减少 **50-90%**        |
| **RAF 批处理高度更新** | 使用 `requestAnimationFrame` 聚合更新               | 避免重复重算，提高帧率         |
| **头像懒加载**         | `Image` 组件开启 `lazyLoad`                         | 首屏图片请求减少 **70-80%**    |
| **常量集中管理**       | `MEASURE_DELAY`、`LOAD_MORE_THRESHOLD` 等统一配置   | 改善可维护性、便于调优         |

详细对比数据与代码片段请参阅 `PERFORMANCE_OPTIMIZATION.md`。

---

## 📚 功能实现要点

### 1. 页面级虚拟滚动

- 直接监听 `usePageScroll`，无需包裹在 `ScrollView` 内，避免平台限制。
- 使用 `requestAnimationFrame` 节流，提高滚动同步性。
- 通过 `commentListTop` + `scrollTop` 计算列表相对位置，实现按需渲染。

### 2. 动态高度与缓存

- 首次渲染使用 `estimatedItemHeight` 作为预估高度，避免首屏空白。
- 渲染后批量测量真实高度，存入 `itemHeightsRef`。
- 前缀和数组和懒更新机制确保滚动稳定、计算高效。

### 3. 分页加载

- 每次加载 20 条评论，最多 100 条。
- 距底部 `LOAD_MORE_THRESHOLD`（默认 200px）触发 `onLoadMore`。
- 使用函数式 `setComments` 更新，避免闭包陷阱。

### 4. 调试与监控

- `DebugPanel` 展示滚动位置、可见区间、总高度、缓存命中、分页状态等信息。
- 通过 `onMetricsChange` 回调实时同步指标，可随时折叠。

---

## 🗂️ 操作历史时间线

1. **需求分析**：确定需要在首页实现“商品介绍 + 页面级虚拟滚动评论列表”。
2. **初版虚拟列表**：完成基础的绝对定位虚拟滚动，实现可见区计算（见 `VIRTUAL_SCROLL_README.md`）。
3. **修复闪烁问题**：定位到随机数据导致的抖动，并改为稳定数据源（记录于 `FLICKER_FIX.md`）。
4. **消除跳动**：将 padding 改为绝对定位 + top 计算，消除滚动回弹。
5. **增加缓冲区**：在可见区上下各增加 10 条缓冲，解决快速滚动出现空白（记录于 `IMPROVEMENTS_SUMMARY.md` 早期部分）。
6. **动态高度支持**：实现高度缓存、重新测量、动态 top 计算，彻底解决长短评论混排（`DYNAMIC_HEIGHT_README.md`）。
7. **分页加载**：引入分页，每页 20 条，模拟网络延迟，滚动到底部自动加载（`PAGINATION_README.md`）。
8. **调试面板**：新增实时监控面板，显示滚动指标和状态，支持折叠。
9. **组件拆分**：将评论项、虚拟列表、加载状态、调试面板拆分为独立组件，类型 + 常量集中管理（详见 `COMPONENT_REFACTORING.md`）。
10. **性能优化 (v2.1)**：完成批量查询、前缀和缓存、RAF 批处理、懒加载等优化，性能显著提升（详见 `PERFORMANCE_OPTIMIZATION.md`）。

---

## 🔮 后续可拓展方向

- 使用 `IntersectionObserver` 优化可见区域检测（视平台支持情况）。
- 引入骨架屏或占位符，优化首屏加载体验。
- 支持评论展开/折叠、点赞等交互，验证高度缓存的稳定性。
- 接入真实接口，替换本地模拟数据，验证实际网络环境表现。
- 将可见指标上报埋点，为性能监控提供数据基础。

---

## 🤝 开发协作建议

- 新增功能时，优先补充 `types.ts` 和 `constants.ts`，确保类型与配置一致。
- 修改虚拟滚动核心逻辑时，请同步更新 `PERFORMANCE_OPTIMIZATION.md` 中的说明。
- 联调真实接口前，可在 `generateComments` 函数中保留模拟数据逻辑作为兜底。
- 如需扩展到多页面，可将虚拟滚动组件、类型、常量迁移到更高层级的 shared 目录。

---

## 📄 许可证

本项目用于演示与学习，可根据实际业务需求自由修改与扩展。