205 lines
6.9 KiB
Markdown
205 lines
6.9 KiB
Markdown
# 自动刷新倒计时功能说明
|
|
|
|
## 功能概述
|
|
|
|
为缠论分析系统的自动刷新功能添加了实时倒计时显示，用户可以清楚地看到距离下次自动刷新还有多少时间。
|
|
|
|
## 功能特性
|
|
|
|
### 🕐 实时倒计时显示
|
|
- **每秒更新**: 倒计时每秒实时更新
|
|
- **精确提示**: 显示格式为"还有 X 秒"
|
|
- **即将刷新提示**: 当剩余时间≤1秒时显示"即将刷新..."
|
|
- **未启用状态**: 自动刷新未启用时显示"--"
|
|
|
|
### ⚡ 智能时间管理
|
|
- **自动重置**: 每次自动刷新后倒计时自动重置
|
|
- **时间同步**: 与自动刷新间隔设置完全同步
|
|
- **精确计算**: 考虑已发生的刷新次数进行时间校正
|
|
|
|
## 界面显示
|
|
|
|
### 倒计时状态展示
|
|
|
|
#### 未启用状态
|
|
```
|
|
┌─ 自动刷新控制行 ─────────────────────────────────────┐
|
|
│ [自动刷新:] [刷新间隔:] [状态:] [下次刷新:] │
|
|
│ ☐ 启用 [15秒 ▼] 未启用 -- │
|
|
└──────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
#### 已启用倒计时
|
|
```
|
|
┌─ 自动刷新控制行 ─────────────────────────────────────┐
|
|
│ [自动刷新:] [刷新间隔:] [状态:] [下次刷新:] │
|
|
│ ☑ 启用 [15秒 ▼] 已启用-每15秒刷新 还有 8 秒 │
|
|
└──────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
#### 即将刷新状态
|
|
```
|
|
┌─ 自动刷新控制行 ─────────────────────────────────────┐
|
|
│ [自动刷新:] [刷新间隔:] [状态:] [下次刷新:] │
|
|
│ ☑ 启用 [15秒 ▼] 已启用-每15秒刷新 即将刷新... │
|
|
└──────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 技术实现
|
|
|
|
### 组件架构
|
|
|
|
#### 新增组件
|
|
```python
|
|
# 倒计时定时器
|
|
dcc.Interval(
|
|
id='countdown-timer',
|
|
interval=1000, # 每秒更新
|
|
n_intervals=0,
|
|
disabled=False # 始终启用
|
|
)
|
|
|
|
# 刷新开始时间存储
|
|
dcc.Store(id='refresh-start-time')
|
|
```
|
|
|
|
#### 回调函数
|
|
```python
|
|
@app.callback(
|
|
Output('next-refresh-time', 'children'),
|
|
[Input('countdown-timer', 'n_intervals'),
|
|
Input('auto-refresh-settings', 'data'),
|
|
Input('refresh-start-time', 'data'),
|
|
Input('auto-refresh-interval', 'n_intervals')]
|
|
)
|
|
def update_countdown(timer_intervals, settings, start_time, auto_refresh_intervals):
|
|
# 倒计时逻辑实现
|
|
```
|
|
|
|
### 核心算法
|
|
|
|
#### 时间计算逻辑
|
|
1. **获取基准时间**: 记录自动刷新启用时间或上次刷新时间
|
|
2. **计算经过时间**: 当前时间 - 基准时间
|
|
3. **考虑刷新次数**: 根据已发生的自动刷新次数调整基准时间
|
|
4. **计算剩余时间**: 刷新间隔 - (经过时间 % 刷新间隔)
|
|
5. **显示倒计时**: 向上取整获得剩余秒数
|
|
|
|
#### 关键代码片段
|
|
```python
|
|
# 计算剩余时间
|
|
interval_seconds = settings.get('interval', 15000) / 1000
|
|
current_time = datetime.now().timestamp()
|
|
elapsed_time = current_time - start_time
|
|
|
|
# 考虑自动刷新次数
|
|
if auto_refresh_intervals > 0:
|
|
adjusted_start_time = start_time + (auto_refresh_intervals * interval_seconds)
|
|
elapsed_time = current_time - adjusted_start_time
|
|
|
|
# 计算倒计时
|
|
remaining_time = interval_seconds - (elapsed_time % interval_seconds)
|
|
remaining_seconds = math.ceil(remaining_time)
|
|
```
|
|
|
|
### 状态管理
|
|
|
|
#### 时间状态存储
|
|
- `refresh-start-time`: 存储刷新开始的时间戳
|
|
- `auto-refresh-settings`: 存储自动刷新配置
|
|
- `countdown-timer`: 每秒触发的倒计时定时器
|
|
|
|
#### 状态同步机制
|
|
1. **启用时**: 记录当前时间戳作为开始时间
|
|
2. **刷新后**: 自动重置开始时间为当前时间
|
|
3. **禁用时**: 清除开始时间，显示"--"
|
|
4. **间隔变更**: 立即更新倒计时计算
|
|
|
|
## 用户体验
|
|
|
|
### 直观反馈
|
|
- **实时性**: 用户可以实时看到倒计时变化
|
|
- **预期性**: 明确知道下次刷新的确切时间
|
|
- **提醒性**: "即将刷新..."提供即时提醒
|
|
|
|
### 交互逻辑
|
|
1. **启用自动刷新**: 倒计时立即开始
|
|
2. **更改间隔**: 倒计时根据新间隔重新计算
|
|
3. **禁用功能**: 倒计时停止，显示"--"
|
|
4. **页面刷新**: 状态保持，倒计时继续
|
|
|
|
## 性能优化
|
|
|
|
### 定时器管理
|
|
- **精确间隔**: 1秒更新间隔，确保倒计时流畅
|
|
- **智能计算**: 避免累积误差的时间计算方法
|
|
- **资源控制**: 只在需要时进行复杂计算
|
|
|
|
### 内存管理
|
|
- **时间戳存储**: 仅存储必要的时间戳数据
|
|
- **状态清理**: 禁用时及时清理相关状态
|
|
- **回调优化**: 使用prevent_initial_call避免不必要的初始调用
|
|
|
|
## 测试场景
|
|
|
|
### 功能测试
|
|
1. **启用测试**: 勾选自动刷新，观察倒计时是否开始
|
|
2. **间隔测试**: 更改刷新间隔，验证倒计时是否重新计算
|
|
3. **刷新测试**: 等待自动刷新触发，确认倒计时重置
|
|
4. **禁用测试**: 取消勾选，确认倒计时停止
|
|
|
|
### 边界测试
|
|
1. **快速切换**: 快速启用/禁用自动刷新
|
|
2. **短间隔**: 测试5秒等短间隔的倒计时
|
|
3. **长间隔**: 测试5分钟等长间隔的倒计时
|
|
4. **页面刷新**: 刷新页面后倒计时是否正常
|
|
|
|
### 精度测试
|
|
1. **时间准确性**: 验证倒计时与实际刷新时间的一致性
|
|
2. **跨刷新周期**: 验证多次自动刷新后的时间准确性
|
|
3. **误差控制**: 确保累积误差在可接受范围内
|
|
|
|
## 故障排除
|
|
|
|
### 常见问题
|
|
|
|
#### 倒计时不显示
|
|
- 检查自动刷新是否已启用
|
|
- 确认countdown-timer组件是否正常工作
|
|
- 验证refresh-start-time是否有数据
|
|
|
|
#### 倒计时不准确
|
|
- 检查系统时间是否正确
|
|
- 确认刷新间隔设置是否正确
|
|
- 验证时间计算逻辑是否有误
|
|
|
|
#### 倒计时卡住
|
|
- 刷新页面重新初始化
|
|
- 检查浏览器console是否有错误
|
|
- 确认定时器是否正常运行
|
|
|
|
### 调试方法
|
|
1. **浏览器控制台**: 查看JavaScript错误信息
|
|
2. **网络面板**: 检查回调请求是否正常
|
|
3. **开发者工具**: 观察组件状态变化
|
|
4. **日志输出**: 查看服务器端日志信息
|
|
|
|
## 未来改进
|
|
|
|
### 增强功能
|
|
- [ ] 添加视觉进度条显示
|
|
- [ ] 支持暂停/恢复倒计时
|
|
- [ ] 添加声音提醒功能
|
|
- [ ] 支持自定义倒计时样式
|
|
|
|
### 性能优化
|
|
- [ ] 优化定时器精度
|
|
- [ ] 减少不必要的重新渲染
|
|
- [ ] 添加防抖机制
|
|
- [ ] 支持离线模式下的倒计时
|
|
|
|
### 用户体验
|
|
- [ ] 添加动画效果
|
|
- [ ] 支持倒计时颜色变化
|
|
- [ ] 添加键盘快捷键
|
|
- [ ] 支持移动端手势操作 |