MindGuard UI组件文档

字数

2240 字

阅读时间

10 分钟

基于实际工程结构与业务需求的完整组件体系文档，确保设计一致性与开发效率。

📋 组件清单总览

组件分类与统计

组件类型	数量	用途	包体归属
导航与头部	2	页面导航、用户信息展示	主包
内容展示	6	帖子、报告、徽章等核心业务内容	主包/分包
状态反馈	4	空/错误/风险/隐私等状态提示	主包
交互组件	2	菜单、标签等交互元素	主包
加载组件	2	骨架屏、加载效果	主包
专业功能	1	REBT心理疗法组件	主包

详细组件清单

1. 导航与头部组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
custom-navbar	自定义导航栏	页面顶部导航，支持返回、标题、操作按钮	通用	无	所有页面	主包	✅ 公共
profile-header	个人资料头部	个人信息展示，包含头像、统计数据、操作按钮	个人中心	user.js	我的Tab	主包	❌ 业务特定

2. 内容展示组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
post-card	帖子卡片	树洞帖子完整展示，包含图片、互动、风险提示	社区	forum.js	树洞Tab	主包	❌ 业务特定
report-card	报告卡片	护心周报展示，包含图表、统计数据	个人中心	reports.js	我的Tab	主包	❌ 业务特定
badge-carousel	徽章轮播	用户获得的护心徽章展示，支持滑动查看	个人中心	badges.js	我的Tab	主包	❌ 业务特定
rebt-inline	REBT内联	理性情绪行为疗法内联编辑器	心理随笔	journals.js	心情随笔	主包	❌ 业务特定
stats-row	统计数据行	健康摘要统计数据展示	通用	user.js	今天Tab/我的Tab	主包	✅ 公共
topic-chip	话题标签	话题标签展示和选择	社区	forum.js	树洞Tab	主包	✅ 公共

3. 状态反馈组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
empty-state	空状态	各种场景的空状态展示	通用	无	所有页面	主包	✅ 公共
error-state	错误状态	错误状态展示，支持重试和刷新	通用	无	所有页面	主包	✅ 公共
risk-banner	风险横幅	风险等级提示横幅，支持自动跳转	通用	forum.js	树洞Tab	主包	✅ 公共
privacy-banner	隐私横幅	隐私授权提醒横幅	通用	user.js	所有页面	主包	✅ 公共

4. 交互组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
menu-list	菜单列表	网格布局的菜单列表	通用	无	个人中心	主包	✅ 公共
topic-chip	话题标签	话题标签展示和选择	社区	forum.js	树洞Tab	主包	✅ 公共

5. 加载组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
skeleton-feed	骨架屏信息流	信息流的骨架屏加载效果	通用	无	树洞Tab	主包	✅ 公共
skeleton-profile	骨架屏个人资料	个人资料的骨架屏加载效果	通用	无	个人中心	主包	✅ 公共

6. 专业功能组件

组件名	中文名	用途	所属域	依赖服务	所在页面	分包	是否公共
rebt-inline	REBT内联	理性情绪行为疗法内联编辑器	心理随笔	journals.js	心情随笔	主包	❌ 业务特定

📊 页面 × 组件覆盖矩阵

主包页面（Tab页面）

页面\组件	custom-navbar	profile-header	post-card	report-card	badge-carousel	rebt-inline	stats-row	topic-chip	empty-state	error-state	risk-banner	privacy-banner	menu-list	skeleton-feed	skeleton-profile
今天	✅	❌	❌	❌	❌	❌	✅	❌	✅	✅	❌	✅	❌	❌	❌
心情随笔	✅	❌	❌	❌	❌	✅	❌	❌	✅	✅	❌	✅	❌	❌	❌
任务	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌
树洞	✅	❌	✅	❌	❌	❌	❌	✅	✅	✅	✅	✅	❌	✅	❌
我的	✅	✅	❌	✅	✅	❌	✅	❌	✅	✅	❌	✅	✅	❌	✅

分包页面

页面\组件	custom-navbar	profile-header	post-card	report-card	badge-carousel	rebt-inline	stats-row	topic-chip	empty-state	error-state	risk-banner	privacy-banner	menu-list	skeleton-feed	skeleton-profile
帖子详情	✅	❌	✅	❌	❌	❌	❌	✅	✅	✅	✅	✅	❌	❌	❌
发布帖子	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌
周报详情	✅	❌	❌	✅	❌	❌	✅	❌	✅	✅	❌	✅	❌	❌	❌
徽章详情	✅	❌	❌	❌	✅	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌
隐私中心	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	✅	✅	❌	❌
资料编辑	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌
SOS主页	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	✅	❌	❌	❌

关键链路标注

🚦 首屏关键路径（今天页）

1. custom-navbar → 页面导航
2. stats-row → 今日状态展示
3. empty-state → 首次使用引导
4. privacy-banner → 隐私授权提醒

🌳 树洞发帖关键路径

1. post-card → 帖子展示
2. topic-chip → 话题标签
3. risk-banner → 风险提示
4. skeleton-feed → 加载状态

📋 任务管理关键路径

1. custom-navbar → 页面导航
2. error-state → 错误处理
3. empty-state → 空状态处理

🔍 差异与重构建议

发现的问题

1. 组件命名不一致

• 问题: skeleton-feed vs skeleton-profile 命名风格不统一
• 建议: 统一为 skeleton-{type} 格式，如 skeleton-post-list, skeleton-user-profile

2. 功能重叠组件

• 问题: stats-row 在多个页面功能类似但实现略有差异
• 建议: 提取为通用统计组件，通过配置实现不同展示

3. 缺失的组件

根据页面文档分析，以下组件需要开发：

组件名	中文名	用途	优先级
mood-card	情绪卡片	情绪打卡展示和录入	🔴 高
suggestion-card	建议卡片	微建议展示和操作	🔴 高
task-card	任务卡片	任务展示和管理	🔴 高
tool-grid	工具网格	工具箱网格布局	🟡 中
resource-card	资源卡片	推荐资源展示	🟡 中
community-highlight	社区高亮	社区动态展示	🟡 中
emotion-thermometer	情绪温度条	情绪可视化	🟢 低

4. API 一致化问题

组件	当前问题	建议方案
post-card	事件命名不统一	统一为 on{Action} 格式
topic-chip	属性命名冗余	简化属性名，增加类型检查
stats-row	数据格式不统一	统一数据结构，增加类型定义

5. 样式 Token 不合规点

组件	问题	修复建议
privacy-banner	使用了硬编码颜色值	替换为 --color-warning-500 Token
report-card	部分颜色未使用Token	替换为 --color-brand-500 系列Token
rebt-inline	CBT颜色未定义	添加 --color-cbt-purple Token

重构建议

🎯 短期重构（高优先级）

1. 统一组件命名规范
2. 修复样式Token问题
3. 补充缺失的核心组件
4. API接口一致化

🔄 中期重构（中优先级）

1. 组件类型定义完善
2. 错误处理机制统一
3. 无障碍支持增强
4. 性能优化（懒加载等）

🚀 长期重构（低优先级）

1. 组件库独立化
2. 国际化支持
3. 主题系统完善
4. 单元测试覆盖

📄 组件规范条目

通用规范

命名规范

• 组件文件名: kebab-case (如 post-card)
• 组件类名: PascalCase (如 PostCard)
• 事件名: camelCase (如 onItemTap)
• 属性名: camelCase (如 isLoading)

样式规范

• 颜色: 必须使用CSS Token，禁止硬编码颜色值
• 间距: 使用 4/8/12/16/24/32rpx 系列
• 圆角: 使用 8/12/16/24/32rpx 系列
• 字体: 使用 24/28/32rpx 系列

数据规范

• 属性类型: 明确类型定义，支持默认值
• 事件参数: 统一事件对象结构
• 数据流: 单向数据流，避免双向绑定

📝 校验报告

Token映射表

裸色值	对应Token	使用场景
#3A7BD5	--color-brand-500	品牌主色
#2C3640	--color-ink-900	主要文字
#5A6672	--color-ink-600	次要文字
#EEF5FF	--color-brand-50	主色背景
#F59E0B	--color-warning-500	警告色
#DC2626	--color-danger-500	危险色
#2AC28D	--color-success-500	成功色

对比度检查

所有组件文本对比度均满足 WCAG 2.1 AA 标准（≥ 4.5:1）。

埋点缺失检查

组件	缺失埋点	建议补充
menu-list	菜单项点击事件	添加 clk_menu_item 埋点
stats-row	统计项点击事件	添加 clk_stats_item 埋点
topic-chip	标签选择事件	添加 act_topic_select 埋点

📚 附录

相关文档

• MindGuard色彩系统
• 前端样式规范
• 分包规划方案
• 页面文档

工具与资源

• TDesign组件库
• 微信小程序自定义组件
• WCAG 2.1 无障碍指南

---

文档版本: v1.0.0 最后更新: 2025-09-22 维护者: MindGuard设计与前端团队

贡献者

Cai Hongyu

文件历史

最后编辑于 5 个月前查看完整历史

f67c2-refactor: 重组项目目录结构，将文档迁移到notes文件夹

03774-docs(faq): 重新整理并扩充 MindGuard FAQ 与用户反馈文档

9b66b-docs(docs): 更新MindGuard文档与样式规范以支持心情随笔与任务Tab

18e56-2025-09-19 16:11:17