wushu/docs/superpowers/specs/2026-04-03-home-poetry-card-skeleton-design.md

主页诗词卡片骨架屏设计文档

问题描述

当前主页诗词卡片在点击加载下一条时会出现闪白现象，原因是：

1. poetryData.value = newPoetryData 触发整个卡片重建
2. 重建过程中卡片内容短暂消失，显示白色背景
3. 用户体验不佳，应该有平滑的过渡效果

解决方案

方案：骨架屏过渡（推荐）

在加载新数据时，保持卡片容器显示，使用骨架屏（Skeleton）代替实际内容，实现平滑过渡。

核心思路：

1. 卡片容器始终存在，不随数据变化而销毁重建
2. 每个区域（标题、诗句、原文、关键词、译文）独立控制加载状态
3. 加载时使用骨架屏动画，加载完成后显示实际内容
4. 避免整个卡片的闪白现象

技术实现：

1. 修改 PoetryCard 组件，添加骨架屏支持
2. 使用 Shimmer 效果或自定义骨架动画
3. 保持卡片背景色在加载过程中不变
4. 分区域加载，逐步显示内容

文件修改

1. home_part.dart

• 修改 PoetryCard 组件
• 添加骨架屏 Widget
• 优化加载状态的显示逻辑

2. home_controller.dart（如有需要）

• 调整加载状态的管理
• 确保骨架屏在正确时机显示

设计要点

1. 骨架屏样式

   • 使用与卡片背景对比的颜色
   • 添加脉冲动画效果
   • 保持与内容区域相同的尺寸

2. 过渡动画

   • 骨架屏到实际内容的淡入淡出
   • 避免突兀的切换

3. 深色模式支持

   • 骨架屏颜色适配深色/浅色模式
   • 保持视觉一致性

预期效果

• 点击下一条时，卡片保持显示
• 各区域显示骨架屏动画
• 数据加载完成后，内容平滑过渡显示
• 无闪白现象，用户体验流畅