91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
# 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 宽度和浅/深色主题下无溢出。
|