147 lines
5.8 KiB
Markdown
147 lines
5.8 KiB
Markdown
# 进度条动画配置文档
|
||
|
||
> 文件路径：`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; /* 光柱更高 */
|
||
```
|