react-resize-demo 2.0.3 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,372 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [4.1.0] - 2026-01-17
+
+### 🔧 改进
+
+- **代码优化与重构**
+  - 移除未使用的变量：`prePanelEl`、`nextPanelEl`（Basic 策略），`nextPanelEl`（Flex 策略）
+  - 优化 `startResize` 方法：统一处理逻辑，先处理前面的面板，再处理 prePanel 和 nextPanel，最后处理后面的面板
+  - 优化虚拟化节点位置更新逻辑：基于文档算法的简化实现，从 O(n²) 优化到 O(n)，代码从 65 行减少到约 50 行
+
+- **代码质量提升**
+  - 修复所有 lint 错误和警告
+  - 改进代码可读性和可维护性
+  - 统一代码风格和注释规范
+
+### 📝 技术细节
+
+**代码冗余优化**：
+- 移除了仅用于初始化的 `prePanelEl` 和 `nextPanelEl` 变量，后续通过 `getPanelInfo` 获取
+- 提取公共方法 `recordPanelInitialState`，减少虚拟化和非虚拟化模式的重复代码
+
+**虚拟化位置更新优化**：
+- 简化位置计算逻辑：从 `allPanelsCurrentSizes` 获取所有面板索引，按顺序遍历
+- 复用已有数据结构：使用 `allPanelsCurrentSizes` 获取当前尺寸（不读取DOM），使用 `panelInfosCache` 获取面板信息
+- 核心逻辑：位置 = 前一个面板的位置 + 前一个面板的尺寸 + handle尺寸
+
+**性能影响**：
+- 无性能损失，代码更简洁
+- 保持 O(n) 时间复杂度
+- 减少代码维护成本
+
+## [4.0.0] - 2026-01-17
+
+### 🎉 重大版本更新
+
+这是一个重大版本更新，移除了链表优化策略，简化了代码库和文档。
+
+### 🗑️ 移除
+
+- **移除链表优化策略（Linked Strategy）**
+  - 移除了 `ResizePanelGroupLinked`、`ResizePanelLinked`、`ResizeHandleLinked` 组件
+  - 移除了 `ResizeAbleCoreLinked` 核心类
+  - 移除了 `src/strategies/linked/` 目录及其所有文件
+
+- **移除 Flex-Linked 策略（Flex-Linked Strategy）**
+  - 移除了 `ResizePanelGroupFlexLinked`、`ResizePanelFlexLinked`、`ResizeHandleFlexLinked` 组件
+  - 移除了 `ResizeAbleCoreFlexLinked` 核心类
+  - 移除了 `src/strategies/flex-linked/` 目录及其所有文件
+
+- **移除链表相关类型和工具**
+  - 移除了 `ResizeAbleCoreLinkedOptions` 接口
+  - 移除了 `ResizeAbleCoreFlexLinkedOptions` 接口
+  - 移除了 `PanelNode` 和 `PanelManagerInterface` 的公共导出（保留在内部实现中）
+  - 移除了 `OptimizationStrategy` 中的 `'linked'` 选项
+
+### 🔄 变更
+
+- **策略简化**
+  - 从 4 种策略简化为 2 种策略：Basic 和 Flex
+  - Basic 策略：适合面板数量较少的简单场景
+  - Flex 策略：推荐使用，提供精确控制和优秀性能
+
+- **文档更新**
+  - 更新了 README.md，移除所有链表策略的说明和示例
+  - 重写了策略对比文档（STRATEGY_COMPARISON.md），只保留 Basic 和 Flex 策略
+  - 更新了性能优化时间线（PERFORMANCE_TIMELINE.md），保留历史记录但移除推荐内容
+  - 所有文档现在推荐使用 Flex 策略
+
+- **导出更新**
+  - 从 `src/index.ts` 移除了链表相关组件的导出
+  - 从 `src/components/index.tsx` 移除了链表相关组件的导出
+  - 从 `src/utils/index.ts` 移除了链表相关工具的导出
+
+### 🔧 改进
+
+- **代码简化**
+  - 移除了约 2000+ 行链表相关代码
+  - 简化了项目结构，更易于维护
+  - 减少了代码复杂度
+
+- **性能优化**
+  - 优化尺寸调整算法：采用"预先计算 + 边界检查"策略
+  - 添加预先计算可操作空间，避免无效操作
+  - 实现三重约束取最小值，确保不超出边界限制
+  - 所有策略现在都支持最大值限制（`maxSize`）
+  - 保证数值守恒，无累积误差
+
+### 📝 技术细节
+
+**移除原因**：
+- 在实际业务场景中，面板数量通常较少（2-10 个），链表优化的收益不明显
+- 链表策略增加了代码复杂度和维护成本
+- 对于少量面板，数组索引访问的性能已经足够好
+
+**迁移指南**：
+- 如果之前使用 `ResizePanelGroupLinked`，请迁移到 `ResizePanelGroupFlex`
+- 如果之前使用 `ResizePanelGroupFlexLinked`，请迁移到 `ResizePanelGroupFlex`
+- Flex 策略提供了更好的性能和精确控制
+
+### 🚨 破坏性变更
+
+- **移除的组件**（不再可用）：
+  - `ResizePanelGroupLinked`、`ResizePanelLinked`、`ResizeHandleLinked`
+  - `ResizePanelGroupFlexLinked`、`ResizePanelFlexLinked`、`ResizeHandleFlexLinked`
+  - `ResizableContextLinked`、`useResizableContextLinked`
+
+- **移除的类型**（不再导出）：
+  - `ResizeAbleCoreLinkedOptions`
+  - `ResizeAbleCoreFlexLinkedOptions`
+  - `PanelNode`（公共导出）
+  - `PanelManagerInterface`（公共导出）
+
+- **API 变更**：
+  - `createResizeAbleCore` 函数不再接受 `strategy: 'linked'` 参数
+  - `OptimizationStrategy` 类型只保留 `'normal'` 选项
+
+### 📚 文档
+
+- 更新了所有文档以反映新的策略结构
+- 移除了指向性推荐内容，但保留了历史变更记录
+- 更新了性能优化时间线，标记链表策略为"已移除"
+
+### ⚠️ 升级建议
+
+1. **检查代码中的链表策略使用**
+   ```bash
+   # 搜索项目中的链表策略使用
+   grep -r "ResizePanelGroupLinked\|ResizePanelFlexLinked" src/
+   ```
+
+2. **迁移到 Flex 策略**
+   ```tsx
+   // 之前
+   import { ResizePanelGroupFlexLinked, ResizePanelFlexLinked } from 'react-resize-demo';
+   
+   // 之后
+   import { ResizePanelGroupFlex, ResizePanelFlex } from 'react-resize-demo';
+   ```
+
+3. **更新导入路径**
+   - 所有链表相关的导入都需要更新
+   - 类型定义也需要更新
+
+---
+
+## [3.1.2] - 2026-01-13
+
+### ✨ 新增
+
+- **自定义拖拽器功能**
+  - 所有策略（Basic、Linked、Flex、Flex-Linked）现在都支持自定义拖拽器渲染
+  - 新增 `renderHandle` prop，允许通过渲染函数自定义拖拽器的外观和内容
+  - 支持拖拽状态反馈：`isResizing` 参数可在拖拽时动态更新样式
+  - 完全向后兼容：未提供 `renderHandle` 时使用默认的黑色拖拽器
+
+### 🔧 改进
+
+- **用户体验**
+  - 允许开发者完全自定义拖拽器的样式和交互效果
+  - 支持根据拖拽状态（`isResizing`）动态改变拖拽器外观
+  - 提供完整的 TypeScript 类型支持（`ResizeHandleRenderProps`）
+
+### 📝 技术细节
+
+**自定义拖拽器实现**：
+- 在所有策略的 `ResizePanelGroup` 组件中添加 `renderHandle` prop
+- 在所有策略的 `ResizeHandle` 组件中支持接收并渲染自定义内容
+- 添加 `isResizing` 状态跟踪，实时反馈拖拽状态
+- 使用自定义渲染时，容器背景自动设为透明，避免样式冲突
+- 所有策略统一导出 `ResizeHandleRenderProps` 类型，便于类型检查
+
+**使用示例**：
+```tsx
+<ResizePanelGroupFlexLinked
+  renderHandle={({ prePanelIndex, nextPanelIndex, direction, isResizing }) => (
+    <div className="custom-resize-handle" style={{
+      backgroundColor: isResizing ? '#0066cc' : '#cccccc',
+    }}>
+      自定义拖拽器
+    </div>
+  )}
+>
+  {/* panels */}
+</ResizePanelGroupFlexLinked>
+```
+
+## [3.1.1] - 2026-01-13
+
+### ✨ 新增
+
+- **Flex 策略配置化**
+  - 新增 `FlexStrategyConfig` 配置接口，支持自定义计算参数
+  - 可在 `ResizePanelGroupFlex` 和 `ResizePanelGroupFlexLinked` 中通过 `flexConfig` prop 配置
+  - 支持配置的参数包括：
+    - `minDeltaThreshold`: 最小拖拽变化阈值（默认 0.1 像素）
+    - `sizeChangeThreshold`: 尺寸变化误差阈值（默认 0.1 像素）
+    - `growChangeThreshold`: grow 值变化阈值（默认 0.0001）
+    - `growNormalizeBase`: grow 值归一化基数（默认 100）
+    - `growPrecisionMultiplier`: grow 值精度倍数（默认 1000，保留3位小数）
+    - `flexGrowPrecisionMultiplier`: flex-grow 精度倍数（默认 100，保留2位小数）
+
+### 🔧 改进
+
+- **代码可维护性**
+  - 将 Flex 和 Flex-Linked 策略中的硬编码常量提取为可配置项
+  - 提供默认配置值，确保向后兼容
+  - 优化代码结构，便于后续扩展
+
+### 📝 技术细节
+
+**配置化实现**：
+- 在 `types/index.ts` 中新增 `FlexStrategyConfig` 接口和 `DEFAULT_FLEX_STRATEGY_CONFIG` 默认配置
+- 在 `ResizeAbleCoreFlex` 和 `ResizeAbleCoreFlexLinked` 中支持配置参数
+- 通过 Context 传递配置到 ResizeHandle 组件
+- 所有配置项都有合理的默认值，无需配置即可使用
+
+## [3.1.0] - 2026-01-11
+
+### ✨ 新增
+
+- **RAF 优化（RequestAnimationFrame）**
+  - 在所有策略的 ResizeHandle 组件中应用 RAF 优化
+  - 鼠标移动时只更新 delta 值，不立即计算
+  - 使用 `requestAnimationFrame` 在每帧结束时计算一次
+  - 与浏览器渲染同步，避免快速拖拽时的位置偏移
+
+- **基于位置的计算方法（Flex 和 Flex-Linked 策略）**
+  - 重构计算逻辑，改为基于初始位置和当前 delta 值计算
+  - 每次计算都基于初始状态，避免累积误差
+  - 根据起始位置、方向、最小值和移动距离，一次性计算所有面板的位置
+  - 被压缩的面板减小尺寸，扩大的面板恢复尺寸
+
+### 🔧 改进
+
+- **性能优化**
+  - 减少计算频率：从每次鼠标移动计算改为每帧计算一次
+  - 避免累积误差：基于初始状态计算，而不是基于当前状态累积
+  - 解决快速拖拽位置偏移：每帧更新的都是当前帧应得的位置
+  - 提升拖拽流畅度：与浏览器渲染同步，更平滑
+
+- **代码质量**
+  - 统一所有策略的优化方式
+  - 改进代码注释，说明优化思路
+  - 优化清理逻辑，确保 RAF 正确取消
+
+### 📝 技术细节
+
+**RAF 优化实现**：
+- 在 `startResize` 时记录初始位置和重置 delta
+- 在 `onResizeMove` 中只更新 `currentDelta`，不立即计算
+- 使用 `requestAnimationFrame` 在每帧结束时调用 `onResize`
+- 在 `endResize` 时确保最终位置正确（使用最新的 delta 值）
+
+**基于位置的计算（Flex/Flex-Linked）**：
+- 在 `startResize` 时记录所有面板的初始位置和尺寸
+- 在 `calculatePanelsByPosition` 中根据 delta 值一次性计算所有面板的新尺寸
+- 使用 `adjustSizesForPositiveDelta` 和 `adjustSizesForNegativeDelta` 处理正向和负向拖拽
+- 根据新尺寸计算新的 grow 值，一次性更新所有面板
+
+### 🐛 修复
+
+- 修复 flex-linked 策略在快速拖拽时位置不正确的问题
+  - 将 flex-linked 策略的计算逻辑改为与 flex 策略一致的基于位置的计算方法
+  - 解决了快速拖拽时的位置偏移问题
+
+## [3.0.0] - 2026-01-10
+
+### 🎉 重大版本更新
+
+这是一个重大版本更新，引入了策略分类架构、性能优化和完整的文档体系。
+
+### ✨ 新增
+
+- **策略分类架构**
+  - 重构为按策略分类的目录结构（`src/strategies/`）
+  - 提供 4 种 resize 策略：
+    - **Basic 策略**：适合面板数量 < 10 的简单场景
+    - **Linked 策略**：适合面板数量 ≥ 10 的场景
+    - **Flex 策略**：适合需要精确控制占比的场景
+    - **Flex-Linked 策略**：适合大量面板 + 精确控制的场景（**推荐**）
+
+- **性能优化**
+  - **节流优化**：使用 `requestAnimationFrame` 节流，减少 DOM 操作 50-70%
+  - **面板变化通知**：通过 `onPanelsChange` 回调，只重新渲染变化的面板
+  - **自动冻结**：自动冻结未变化面板，减少布局计算 85%
+  - **链表优化**：大量面板场景下性能提升 42.9%
+
+- **核心工具模块化**
+  - 新增 `src/core/` 目录，存放所有策略共享的核心工具
+  - `PanelManager.ts`：面板管理器（链表策略使用）
+  - `virtualNode.ts`：虚拟节点管理
+  - `throttle.ts`：节流工具
+
+- **完整文档体系**
+  - [策略对比文档](./docs/STRATEGY_COMPARISON.md)：详细对比 4 种策略
+  - [性能优化时间线](./docs/PERFORMANCE_TIMELINE.md)：记录所有性能优化措施
+  - [节流优化文档](./docs/THROTTLE_OPTIMIZATION.md)：节流优化详细说明
+  - [面板变化通知文档](./docs/PANEL_CHANGE_NOTIFICATION.md)：面板变化通知机制
+
+### 🔄 变更
+
+- **项目结构重构**
+  - 从单一组件结构重构为按策略分类的结构
+  - `src/components/` → `src/strategies/{strategy}/components/`
+  - `src/utils/` → `src/core/`（核心工具）+ `src/strategies/{strategy}/`（策略特定）
+
+- **构建产物结构**
+  ```
+  dist/
+  ├── index.js              # CJS 主入口
+  ├── strategies/           # 策略目录
+  │   ├── basic/
+  │   ├── linked/
+  │   ├── flex/
+  │   └── flex-linked/
+  ├── core/                 # 核心工具
+  │   ├── PanelManager.js
+  │   ├── virtualNode.js
+  │   └── throttle.js
+  └── esm/                  # ESM 模块
+  ```
+
+- **移除废弃策略**
+  - 移除了 `ResizeAbleCoreOptimized` 和相关的 `Optimized` 组件
+  - 统一使用 `Flex-Linked` 策略作为最终版本
+
+- **构建优化**
+  - 构建前自动清空 `dist` 目录
+  - 更新 `package.json` 的 `exports` 字段，支持策略和核心工具的导出路径
+
+### 🔧 改进
+
+- **性能提升**
+  - FPS 从 30-40 提升到 50-55（+66.7%）
+  - CPU 占用从 80-100% 降低到 40-60%（-50%）
+  - DOM 操作减少 60-70%
+  - React 渲染优化 85%
+
+- **代码质量**
+  - 修复了最小尺寸限制的 bug（Flex-Linked 策略）
+  - 优化了面板变化检测逻辑
+  - 改进了链表遍历性能
+
+- **开发体验**
+  - 更清晰的策略分类，便于维护和扩展
+  - 完整的文档体系，便于理解和使用
+  - 详细的性能对比和优化建议
+
+### 📝 向后兼容
+
+- 保留了 Basic 策略的组件导出（`ResizePanelGroup`、`ResizePanel`、`ResizeHandle`）
+- 保留了旧的导出名称（`ResizablePanelGroup`、`ResizeablePanelGroup` 等）
+- 主入口导入方式保持不变
+
+### 🚨 破坏性变更
+
+- 如果直接导入子模块路径，需要更新导入路径
+- `Optimized` 相关组件已移除，请使用 `Flex-Linked` 策略替代
+- 内部 API 结构发生变化，但公共 API 保持兼容
+
+### 📚 文档
+
+- 新增策略对比文档，帮助选择最适合的策略
+- 新增性能优化时间线，记录所有优化措施
+- 更新所有文档以反映新的目录结构
+- 更新 README，添加策略说明和性能优化介绍
+
 ## [2.0.3] - 2026-01-10
 
 ### 🚀 性能优化