# 进度条动画配置文档

> 文件路径：`apps/miniprogram/miniprogram/pages/task-list/`

---

## 概览

进度条动画由两段独立动画组成，通过 `animation-delay` 精确衔接，形成「高光扫过 → 点燃火花」的连续叙事效果。

```
┌──────────────────┐  SHINE_SPARK_GAP  ┌──────────────────┐  SPARK_SHINE_GAP  ┌──────────────────┐
│   高光从左扫到右   │ ────────────────▶ │   火花爆发消散    │ ────────────────▶ │   高光（下一循环）  │
│   SHINE_DUR(s)   │                   │   SPARK_DUR(s)   │                   │                  │
└──────────────────┘                   └──────────────────┘                   └──────────────────┘
```

**核心机制**：两段动画共享同一 `animation-duration`（totalDur），火花通过负值 `animation-delay` 在循环内偏移到正确时刻。`@keyframes` 只描述各自行为，**修改时间轴参数永远不需要改 CSS 百分比**。

---

## 第一层：时间轴参数

**位置**：`task-list.ts` 文件顶部常量区

```ts
const SHINE_DUR       = 1.6   // 秒
const SPARK_DUR       = 1.4   // 秒
const SHINE_SPARK_GAP = -200  // 毫秒
const SPARK_SHINE_GAP = 400   // 毫秒
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `SHINE_DUR` | 秒（正数） | 高光从进度条**左端**扫到**右端**的时长。值越小扫得越快。 |
| `SPARK_DUR` | 秒（正数） | 火花从**爆发**到**完全消散**的时长。值越大火花飞得越慢。 |
| `SHINE_SPARK_GAP` | 毫秒（正/负） | 高光结束 → 火花开始的偏移。**正数** = 高光结束后停顿再爆发；**负数** = 高光尚未结束，火花提前爆发（产生重叠的点燃感）。 |
| `SPARK_SHINE_GAP` | 毫秒（正/负） | 火花消散后 → 下次高光从左端启动的延迟。**正数** = 停顿一段时间后重新开始；**负数** = 火花尚未消散，高光已从左端出发（自然流畅衔接）。 |

> ✅ **修改这四个常量后，不需要改任何 CSS**，totalDur 和 sparkDelayCss 由 `calcAnimTimeline()` 自动计算并注入 WXML style。

### 总循环时长计算公式

```
totalDur = SHINE_DUR + SHINE_SPARK_GAP/1000 + SPARK_DUR + SPARK_SHINE_GAP/1000
```

当前默认值：`1.6 + (-0.2) + 1.4 + 0.4 = 3.2 秒`

---

## 第二层：高光外观

**位置**：`task-list.wxss` → `.tier-shine` 选择器顶部

```css
.tier-shine {
  --shine-width:   50%;           /* 光束宽度 */
  --shine-opacity: 1.0;           /* 峰值亮度 */
  --shine-color:   255, 255, 255; /* RGB 颜色 */
}
```

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `--shine-width` | `50%` | 光束宽度，相对于进度条填充区域。越大光晕越宽，`30%` 偏细锐，`80%` 偏宽柔。 |
| `--shine-opacity` | `1.0` | 光束中心峰值亮度，范围 `0~1`。`0.5` = 半透明柔光，`1.0` = 最亮。 |
| `--shine-color` | `255, 255, 255` | 光束颜色，RGB 三通道逗号分隔。`255,220,100` = 暖黄；`255,180,80` = 橙；`200,230,255` = 冷白蓝。 |

---

## 第三层：火花外观

**位置**：`task-list.wxss` → `.tier-edge-glow` 选择器顶部

```css
.tier-edge-glow {
  --spark-scale:  0.7;    /* 整体缩放 */
  --spark-pole-h: 30rpx;  /* 光柱高度 */
}
```

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `--spark-scale` | `0.7` | **整体缩放比**，同时等比缩放：光柱尺寸 + 全部粒子大小 + 飞射距离。`0.5` = 缩小一半，`1.0` = 原始大小，`2.0` = 放大一倍。 |
| `--spark-pole-h` | `30rpx` | 光柱（白色竖线）高度，宽度自动 = 高度 / 2。调大使光柱更醒目。 |

---

## 火花粒子参数

6 粒火花固定写在 `task-list.wxss`，各自方向/颜色/大小不同。如需微调单个粒子，直接修改对应的 `.spark-N` 和 `@keyframes sparkN`。

| 粒子 | 颜色 | 方向 | 大小 | 爆发时刻 |
|------|------|------|------|----------|
| `spark-1` | 亮白 `#ffffff` | 右上 | 10×10rpx | 8%（较早）|
| `spark-2` | 橙色 `#fb923c` | 右下 | 12×12rpx | 12% |
| `spark-3` | 黄色 `#fde68a` | 正上 | 8×8rpx | 6%（最早）|
| `spark-4` | 红橙 `#ef4444` | 右斜上（带旋转） | 16×6rpx | 10% |
| `spark-5` | 黄白 `#fbbf24` | 正右 | 10×10rpx | 5%（最早）|
| `spark-6` | 淡橙 `#fed7aa` | 右下斜 | 14×14rpx | 15%（最晚）|

> 爆发时刻百分比 = 粒子自身 `@keyframes` 内的时刻，与总循环时长无关。

---

## 进度末端位置逻辑

火花始终显示在进度条末端，位置由 `perfData.clampedSparkPct` 控制：

```ts
clampedSparkPct = Math.max(0, Math.min(100, filledPct))
```

| 场景 | 火星位置 |
|------|----------|
| 0h（未开始） | 进度条**最左端**（0%）|
| 任意进行中 | 对应进度处 |
| 220h（满档） | 进度条**最右端**（100%）|

---

## 快速调参示例

### 想要「高光快、火花慢」
```ts
const SHINE_DUR       = 0.8   // 高光加速
const SPARK_DUR       = 2.0   // 火花放慢
const SHINE_SPARK_GAP = 0     // 高光结束立即爆发
const SPARK_SHINE_GAP = 600   // 火花消散后停顿
```

### 想要「高光和火花完全重叠」
```ts
const SHINE_DUR       = 1.6
const SPARK_DUR       = 1.4
const SHINE_SPARK_GAP = -800  // 高光还差 0.8s 结束时，火花就开始了
const SPARK_SHINE_GAP = -600  // 火花还差 0.6s 消散时，高光已从左端出发
```

### 想要「更大更明显的火花」
```css
/* task-list.wxss → .tier-edge-glow */
--spark-scale:  1.4;    /* 放大到原来的 2 倍 */
--spark-pole-h: 50rpx;  /* 光柱更高 */
```