diff --git a/docs/plans/2026-10-17-K10.md b/docs/plans/2026-10-17-K10.md new file mode 100644 index 0000000..ac111bf --- /dev/null +++ b/docs/plans/2026-10-17-K10.md @@ -0,0 +1,90 @@ +# 2026-10-17 K10 统一空列表占位(EmptyState) + +## 一、目标与边界 + +新建统一 `EmptyState` 组件,替换任务书列出的 10 处纯文字空态,保留现有空态 +文案、按钮行为和错误态逻辑。只改空态视觉、三语 l10n 与测试,不改数据、接口、 +列表加载/失败逻辑或页面信息架构。 + +- 客户端分支:`feature/flutter-k10-empty-states`,基线 `develop 19babb8`。 +- 文档分支:`docs/k10-empty-states`,FruitServer 基线 K10 任务书 `3f84bc6`。 +- 不引入图片、SVG、字体或第三方依赖。 +- 不跑真机,设备侧深色/浅色、小屏和页面状态由用户验收。 + +## 二、组件设计 + +`lib/core/widgets/empty_state.dart`: + +1. 默认居中,最大宽度 280,外层 Padding 24。 +2. 默认图形 96x96、圆角 28,背景 `AppColors.blue` 透明度 0.11;图标 42。 +3. 深色图标色 `AppColors.blueSoft`,浅色图标色 `AppColors.blue`。 +4. compact 图形 64x64、圆角 18、图标 28,用于评论弹窗。 +5. 标题 16/w600(compact 14)、最多 2 行;可选副标题 13、`muted`、最多 2 行。 +6. 可选主色 TextButton,最小点击区域 44x44;保留调用方动作。 +7. 外层 `Semantics(label: title)`;图形、标题和副标题文本使用 + `ExcludeSemantics`,避免重复朗读,操作按钮仍保持可访问。 +8. 稳定 Key:`empty-state-art`、`empty-state-icon`、`empty-state-title`、 + `empty-state-action`。 + +新增通用副标题 `emptyHint`: + +- zh:有新内容时会显示在这里。 +- en:New content will appear here. +- id:Konten baru akan muncul di sini. + +## 三、10 处替换与图标 + +| 位置 | 图标 | 行为 | +|---|---|---| +| 首页 noStories | `movie_outlined` | 保留重试 | +| 首页分类空 | `grid_view_rounded` | 无新增动作 | +| 首页搜索空 | `search_off_rounded` | 无新增动作 | +| 收藏 noFavorites | `favorite_border_rounded` | 原按钮不变 | +| 通知 noNotices | `notifications_none_rounded` | 原下拉刷新不变 | +| 详情 noEpisodesYet | `video_library_outlined` | 保留重试 | +| 我的-片单 noSavedShows | `bookmark_border_rounded` | 无新增动作 | +| 我的-最近剧目 noStories | `history_rounded` | 无新增动作 | +| 下载 noDownloads | `download_outlined` | 原清空按钮不变 | +| 观看记录 noWatchRecords | `history_rounded` | 原清空/刷新逻辑不变 | +| 评论 noComments | `chat_bubble_outline_rounded` | compact | + +首页错误态继续使用 `error_outline_rounded` 和 `catalogError`;分类、收藏、通知、 +记录、评论等失败态继续使用原错误图标/重试,不允许用 `EmptyState` 冒充失败。 + +## 四、影响文件 + +- `lib/core/widgets/empty_state.dart`(新增) +- `lib/pages/home/home_view.dart` +- `lib/pages/discover/widgets/home_drama_grid.dart` +- `lib/pages/favorites/favorites_page.dart` +- `lib/pages/notices/notices_page.dart` +- `lib/pages/drama_detail/drama_detail_view.dart` +- `lib/pages/mine/mine_view.dart` +- `lib/pages/downloads/downloads_page.dart` +- `lib/pages/watch_records/watch_records_page.dart` +- `lib/pages/player/widgets/drama_comments_sheet.dart` +- `lib/l10n/app_en.arb`、`app_zh.arb`、`app_id.arb` 与生成文件 +- 组件测试及收藏/下载/记录/通知/评论页面空态测试 +- `FruitServer/docs/plans/2026-10-17-K10.md` +- `FruitServer/docs/plans/PROGRESS.md` +- `FruitServer/docs/plans/INBOX.md` + +## 五、TDD 与门禁 + +1. 先新增 `EmptyState` 组件测试和五处页面空态测试,确认组件不存在时红灯。 +2. 实现组件并替换 10 处空态后跑定向测试绿灯。 +3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。 +4. 构建前检查并发 `flutter run/build`;当前有用户 iOS `flutter run` 会话, + 不主动终止,若仍未结束则等待其退出后再构建。 +5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push;FruitServer 文档同样 + 合并推送。作者与提交者统一为 + `Zhou Weidong <502333560@qq.com>`。 + +## 六、风险与待确认 + +- 首页当前把 `catalog.error` 与空列表放在同一分支,需先拆出错误态,再单独用 + `EmptyState` 渲染 noStories,避免错误态被误认为空态。 +- 部分空态位于 Sliver、固定高度滚动区或弹窗内,需保持可滚动和居中。 +- 组件外层统一读标题,若操作按钮位于同一 Semantics 容器内,必须确保按钮自身 + 语义未被 `ExcludeSemantics` 吞掉。 +- 最大宽度 280 与 compact 64 图标容器需在 320px 宽度和浅/深色主题下无溢出。