Files
FruitServer/docs/plans/2026-10-17-K10.md

4.5 KiB
Raw Permalink Blame History

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 宽度和浅/深色主题下无溢出。