displaying-timelines

显示时间线和活动组件

用途

此技能可帮助系统地创建时间线和活动组件，从简单的垂直时间线到复杂的交互式甘特图。它根据用例和数据特征提供清晰的决策框架，确保实现具备最佳性能、实时更新能力和良好的可访问性。

适用场景

在以下情况下启用此技能：

• 创建活动动态（社交内容、通知、审计日志）
• 显示时间线（垂直、水平、交互式）
• 构建甘特图或项目计划
• 实现日历界面（月、周、日视图）
• 显示按时间顺序排列的事件或历史数据
• 处理实时活动更新
• 需要格式化时间戳（相对时间、绝对时间）
• 确保时间线的可访问性或响应式行为

快速决策框架

根据用例选择组件类型：

Social Activity        → Activity Feed (infinite scroll, reactions)
System Events          → Audit Log (searchable, exportable, precise timestamps)
User Notifications     → Notification Feed (read/unread, grouped by date)
Historical Events      → Vertical Timeline (milestones, alternating sides)
Project Planning       → Gantt Chart (dependencies, drag-to-reschedule)
Scheduling             → Calendar Interface (month/week/day views)
Interactive Roadmap    → Horizontal Timeline (zoom, pan, filter)

如需了解详细的选择标准，请参阅 references/component-selection.md。

核心实现模式

活动动态

社交动态模式：

• 用户头像 + 姓名 + 操作说明
• 相对时间戳（“2 小时前”）
• 反应和评论
• 带分页的无限滚动
• 通过 WebSocket 实时更新
• 参阅 references/activity-feeds.md

通知动态模式：

• 按日期分组
• 通过指示器显示已读/未读状态
• 全部标记为已读功能
• 按通知类型筛选
• 操作按钮（查看、忽略）
• 参阅 references/notification-feeds.md

审计日志模式：

• 带精确时间戳的系统事件
• 用户操作跟踪
• 支持高级筛选的搜索
• 可导出（CSV、JSON）
• 注重安全性的显示方式
• 参阅 references/audit-logs.md

示例：examples/social-activity-feed.tsx

时间线可视化

垂直时间线：

• 事件按时间顺序堆叠
• 带标记点的连接线
• 日期标记和事件卡片
• 可选的交替布局
• 适用于：历史事件、项目里程碑
• 参阅 references/vertical-timelines.md

水平时间线：

• 事件沿水平轴排列
• 通过滚动或缩放进行导航
• 密度随缩放级别变化
• 适用于：项目时间线、路线图
• 参阅 references/horizontal-timelines.md

交互式时间线：

• 点击事件可查看详情
• 按类别/类型筛选
• 缩放控制
• 平移和滚动导航
• 适用于：数据探索、丰富的交互体验
• 参阅 references/interactive-timelines.md

示例：examples/milestone-timeline.tsx

甘特图

项目规划功能：

• 任务以水平条形图表示
• 依赖关系以箭头表示
• 突出显示关键路径
• 拖动以重新安排时间
• 进度指示器
• 里程碑标记（菱形）
• 资源分配
• 今日标记线
• 缩放级别（日/周/月/年）

生成甘特图数据：

python scripts/generate_gantt_data.py --tasks 50 --dependencies auto

实现详情请参阅 references/gantt-patterns.md。

示例：examples/project-gantt.tsx

日历界面

月视图：

• 传统日历网格
• 日期单元格中的事件
• 点击以创建/编辑
• 按颜色区分类别
• 多日历叠加显示

周视图：

• 时间段（按小时）
• 可拖动的事件块
• 调整大小以更改时长
• 多日历叠加显示

日视图/日程视图：

• 详细的每日安排
• 按时长显示的列表格式
• 地点和参与者
• 可滚动时间线

所有视图的详细信息请参阅 references/calendar-patterns.md。

示例：examples/calendar-scheduler.tsx

时间戳格式

重要的时间戳模式：

相对时间（近期事件）：

• “刚刚”（< 1 分钟）
• “5 分钟前”
• “3 小时前”
• “昨天 3:42 PM”

绝对时间（较早的事件）：

• “2025 年 1 月 15 日”
• “2025 年 1 月 15 日 3:42 PM”
• API 使用 ISO 8601

实现注意事项：

• 时区处理（显示用户的本地时间）
• 根据地区设置格式
• 悬停时显示精确时间戳
• 自动更新相对时间

如需统一格式化时间戳：

node scripts/format_timestamps.js --locale en-US --timezone auto

完整模式请参阅 references/timestamp-formatting.md。

实时更新

实时动态流：

• 使用 WebSocket 或 SSE 获取新事件
• 添加平滑的插入动画
• 显示“X 条新内容”通知横幅
• 点击以加载新内容
• 对用户操作进行乐观更新

实现模式：

1. 立即显示用户操作
2. 将时间戳更新为“刚刚”
3. 在后台发送到服务端
4. 如果出错则回滚

WebSocket 模式请参阅 references/real-time-updates.md。

示例：examples/realtime-activity.tsx

性能优化

关键性能阈值：

<100 events       → Client-side rendering, no virtualization
100-1,000 events  → Virtual scrolling recommended
1,000+ events     → Virtual scrolling + server pagination
Real-time         → Debounce updates, batch insertions

优化策略：

• 对时间线项目组件进行记忆化
• 延迟加载事件详情
• 对较长的时间线使用虚拟滚动
• 对实时更新进行防抖（每 500ms 批量处理）
• 优化时间戳计算

如需对性能进行基准测试：

node scripts/benchmark_timeline.js --events 10000

详情请参阅 references/performance-optimization.md。

无障碍要求

WCAG 合规要点：

语义化 HTML：

• 时间线使用 <ol> 或 <ul>
• 使用恰当的标题层级
• 使用语义化的时间元素

ARIA 模式：

• 动态消息流使用 role="feed"
• 时间线项目使用 role="article"
• 时间戳使用 aria-label
• 加载期间使用 aria-busy

键盘导航：

• 使用 Tab 键遍历可交互项目
• 使用方向键浏览时间线
• 使用 Enter/Space 展开项目
• 提供跳转到最新/最早内容的控件

屏幕阅读器支持：

• 在动态消息流中播报新项目
• 使用描述性时间戳标签
• 为甘特图提供进度更新

如需验证无障碍性：

node scripts/validate_timeline_accessibility.js

完整要求请参阅 references/accessibility-patterns.md。

响应式设计

三种经过验证的策略：

1. 垂直堆叠（移动设备）

• 将水平布局转换为垂直布局
• 保持时间顺序
• 调整间距和字体大小

2. 简化显示

• 仅显示必要信息
• 展开以查看详情
• 降低视觉复杂度

3. 水平滚动

• 保持布局不变
• 支持触控滚动
• 添加滚动指示器

实现方式请参阅 references/responsive-strategies.md。

示例：examples/responsive-timeline.tsx

库推荐

时间线：react-chrono（灵活）

适用于内容丰富的时间线可视化：

• 支持水平、垂直和交替布局
• 支持图像和视频
• 自定义项目渲染
• 支持 TypeScript
• 开箱即支持响应式布局

npm install react-chrono

配置方法请参阅 examples/react-chrono-timeline.tsx。

替代方案：react-vertical-timeline-component

• 简洁清晰的垂直时间线
• 轻量（约 10KB）
• 支持图标
• 适用于基础时间线

甘特图：SVAR React Gantt

适用于项目管理：

• 现代化，无依赖
• 支持拖放任务
• 支持依赖关系和里程碑
• 外观可自定义
• 已支持 TypeScript

npm install @svar/gantt

企业级替代方案：Bryntum Gantt

• 功能齐全的解决方案
• 需要商业许可证
• 可处理复杂项目
• 高级资源管理

日历：react-big-calendar

适用于日程安排界面：

• 提供月、周、日和议程视图
• 支持拖放事件
• 样式可自定义
• 社区支持广泛

npm install react-big-calendar

替代方案：FullCalendar

• 提供高级功能
• 文档出色
• 支持多种框架

详细比较请参阅 references/library-comparison.md。

设计令牌集成

时间线使用 design-tokens 技能实现一致的主题：

时间线专用令牌：

• --timeline-line-color - 连接线颜色
• --timeline-dot-color - 事件标记颜色
• --timeline-dot-active-color - 当前／活动事件
• --event-card-bg - 事件卡片背景
• --timestamp-color - 时间戳文本颜色

标准令牌类别：

• 用于背景和状态的颜色令牌
• 用于间距和内边距的间距令牌
• 用于文本层级的排版令牌
• 用于卡片立体效果的阴影令牌
• 用于动画的动效令牌

支持浅色、深色、高对比度和自定义主题。 主题切换请参考 design-tokens 技能。

可用示例

从符合需求的示例开始：

social-activity-feed.tsx       # Social feed with reactions
notification-center.tsx        # Notification system with filters
audit-log-viewer.tsx           # System audit log
milestone-timeline.tsx         # Vertical timeline with milestones
project-gantt.tsx              # Gantt chart with dependencies
calendar-scheduler.tsx         # Full calendar with all views
realtime-activity.tsx          # Live updates via WebSocket
responsive-timeline.tsx        # Mobile-optimized timeline

测试工具

生成模拟时间线数据：

python scripts/generate_timeline_data.py --events 500 --realtime

测试实时更新：

node scripts/simulate_realtime.js --rate 5/sec --duration 60s

验证无障碍功能：

node scripts/validate_timeline_accessibility.js

对性能进行基准测试：

node scripts/benchmark_timeline.js --events 10000 --virtual

后续步骤

1. 确定时间线的使用场景（活动、事件、日程安排）
2. 选择合适的组件类型
3. 选择一个库，或使用令牌构建自定义组件
4. 从匹配的示例文件开始
5. 实现核心功能
6. 根据需要添加实时更新
7. 使用大型数据集测试性能
8. 验证无障碍合规性
9. 为移动设备应用响应式策略