4.5 KiB
4.5 KiB
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:
- 默认居中,最大宽度 280,外层 Padding 24。
- 默认图形 96x96、圆角 28,背景
AppColors.blue透明度 0.11;图标 42。 - 深色图标色
AppColors.blueSoft,浅色图标色AppColors.blue。 - compact 图形 64x64、圆角 18、图标 28,用于评论弹窗。
- 标题 16/w600(compact 14)、最多 2 行;可选副标题 13、
muted、最多 2 行。 - 可选主色 TextButton,最小点击区域 44x44;保留调用方动作。
- 外层
Semantics(label: title);图形、标题和副标题文本使用ExcludeSemantics,避免重复朗读,操作按钮仍保持可访问。 - 稳定 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.dartlib/pages/discover/widgets/home_drama_grid.dartlib/pages/favorites/favorites_page.dartlib/pages/notices/notices_page.dartlib/pages/drama_detail/drama_detail_view.dartlib/pages/mine/mine_view.dartlib/pages/downloads/downloads_page.dartlib/pages/watch_records/watch_records_page.dartlib/pages/player/widgets/drama_comments_sheet.dartlib/l10n/app_en.arb、app_zh.arb、app_id.arb与生成文件- 组件测试及收藏/下载/记录/通知/评论页面空态测试
FruitServer/docs/plans/2026-10-17-K10.mdFruitServer/docs/plans/PROGRESS.mdFruitServer/docs/plans/INBOX.md
五、TDD 与门禁
- 先新增
EmptyState组件测试和五处页面空态测试,确认组件不存在时红灯。 - 实现组件并替换 10 处空态后跑定向测试绿灯。
- 运行
dart analyze lib test、flutter test、flutter build apk --debug。 - 构建前检查并发
flutter run/build;当前有用户 iOSflutter run会话, 不主动终止,若仍未结束则等待其退出后再构建。 - 完成后
merge --no-ff回客户端develop并 push;FruitServer 文档同样 合并推送。作者与提交者统一为Zhou Weidong <502333560@qq.com>。
六、风险与待确认
- 首页当前把
catalog.error与空列表放在同一分支,需先拆出错误态,再单独用EmptyState渲染 noStories,避免错误态被误认为空态。 - 部分空态位于 Sliver、固定高度滚动区或弹窗内,需保持可滚动和居中。
- 组件外层统一读标题,若操作按钮位于同一 Semantics 容器内,必须确保按钮自身
语义未被
ExcludeSemantics吞掉。 - 最大宽度 280 与 compact 64 图标容器需在 320px 宽度和浅/深色主题下无溢出。