瀑布流异常处理

四种异常情况类型

1. 图片加载失败

• 触发条件：原始内容（如图片）加载失败
• 对应状态：ORIGINAL_FAILED
• 事件来源：loaded(event) 函数中 event?.type !== 'load'

2. 占位图加载失败

• 触发条件：在显示占位图时，占位图也加载失败
• 对应状态：FINAL_FALLBACK
• 事件来源：onPlaceholderError() 函数

3. 重试后仍然失败

• 触发条件：在重试模式下，达到最大重试次数后仍然失败
• 对应状态：FINAL_FALLBACK
• 事件来源：handleFailureRetry() 中 retryCount <= 0

4. 超时

• 触发条件：在 MAX_WAIT 时间内未完成加载
• 对应状态：TIMEOUT
• 事件来源：useTimeout 回调函数

四种处理模式对异常的响应策略

errorHandlingMode?: 'none' | 'placeholder' | 'retry' | 'fallback'

异常类型	none 模式	placeholder 模式	retry 模式	fallback 模式
图片加载失败	直接结束，使用默认高度	显示占位图	重试 N 次	重试 N 次
占位图加载失败	❌ 不涉及	显示文字兜底	❌ 不涉及	显示文字兜底
重试后仍失败	❌ 不涉及	❌ 不涉及	使用默认高度	显示占位图
超时	使用默认高度	使用默认高度	使用默认高度	使用默认高度

异常处理流程图

原始内容加载
     ↓
   成功？
   ↙   ↘
  是     否
  ↓      ↓
 完成   根据模式处理
        ↓
    ┌─────────────────┐
    │  none: 直接结束  │
    │  placeholder:   │
    │    显示占位图    │
    │  retry: 重试    │
    │  fallback:     │
    │    重试→占位图   │
    └─────────────────┘

状态枚举与异常类型的映射

const ItemStatus = {
  NONE: 'none',                    // 正常状态
  ORIGINAL_FAILED: 'fail',        // 异常类型1: 图片加载失败
  PLACEHOLDER_SUCCESS: 'phok',     // 占位图成功（非异常）
  TIMEOUT: 'timeout',              // 异常类型4: 超时
  FINAL_FALLBACK: 'final',         // 异常类型2,3: 占位图失败/重试失败
}

关键设计思想

1. 异常类型是客观事实：无论什么模式，异常类型都是固定的
2. 处理模式是主观策略：根据业务需求选择不同的应对方式
3. 渐进式降级：从最理想的状态逐步降级到可接受的兜底方案
4. 统一超时保护：所有模式都有超时机制，防止无限等待

这样的设计既保证了异常情况的完整覆盖，又提供了灵活的处理策略选择。