diff --git a/frontend/pages/square/components/StarGalaxy/README.md b/frontend/pages/square/components/StarGalaxy/README.md new file mode 100644 index 0000000..ba6196a --- /dev/null +++ b/frontend/pages/square/components/StarGalaxy/README.md @@ -0,0 +1,79 @@ +# StarGalaxy 组件 + +square 页「星河」tab 的排行榜组件，渲染 TOP 1-12 的 3D 倾斜椭圆轨道 + 顺时针旋转动画。 + +## 视觉特征 + +- 65° 倾斜椭圆轨道（rx=130, ry=55） +- TOP 1-3 颁奖台（cover + 下方标签 + 钻石外框 + 金/银/铜渐变） +- TOP 4-12 9 个散落 item（cover + 上方标签 + 蓝白钻石渐变） +- 9 item 顺时针 36s 旋转一圈（单组 @keyframes + 9 个不同 animation-delay 错开） +- 近大远小（scale 0.75→1.15，TOP 4 最大，TOP 8/9 最小） +- 装饰层：粉红渐变 overlay + 樱花粉/暖黄双光晕 +- 标题「★ 星河 ★」+ 底部提示「每日 0:00 更新榜单」 + +## 数据来源 + +复用现有 `getHotRankingApi("displaying", null, 1, 12)` — 与「星榜」共用 API，取前 12 条。 + +## 文件 + +| 文件 | 职责 | +|----|----| +| `index.vue` | 容器：数据加载、装饰层、4 状态分支、子组件编排 | +| `PodiumCard.vue` | TOP 1-3 大卡（cover + 下方 TOP N 标签 + 可选皇冠） | +| `ScatteredRanks.vue` | TOP 4-12 9 散落 item（共享 36s 旋转动画） | +| `config.js` | 9 slot 位置/translate/scale 公式 + RING_DELAYS | + +## 可调参数 + +| 参数 | 位置 | 默认值 | 说明 | +|----|----|----|----| +| 椭圆倾斜度 | `config.js: RING.ry` | 55 (cos⁻¹ 65°) | 改 ry 调整倾斜度（越小越斜） | +| 旋转周期 | `ScatteredRanks.vue: animation` | 36s | 改秒数调整速度 | +| 近大远小范围 | `config.js: yFactor + 0.40 * yFactor` | 0.75→1.15 | 改 0.75/1.15 调整 | +| TOP 6/11 位置 | `config.js: OVERRIDES` | x:321 / x:8 | 边缘推拉 | +| Podium 位置/尺寸 | `index.vue: PODIUM_SIZES/POSITIONS` | 240×260 等 | 调整 1-3 大卡 | + +## 跨端兼容性 + +| CSS 特性 | H5 | APP | 微信小程序 | 备注 | +|----|----|----|----|----| +| `transform: scale/translate` | ✅ | ✅ | ✅ | 全支持 | +| `filter: blur(Nrpx)` | ✅ | ✅ | ⚠️ 部分 | 光晕效果用，MP 可能降级 | +| `radial-gradient` | ✅ | ✅ | ⚠️ 有限 | 渐变背景，部分 MP 降级为线性 | +| `@keyframes` + `animation` | ✅ | ✅ | ✅ | 全支持 | +| `mask-composite: exclude` | ✅ | ⚠️ | ❌ | 仅 WebKit；MP 需 border-image 替代 | +| `backdrop-filter` | ✅ | ⚠️ | ❌ | 仅 H5；装饰层用 `opacity` 兜底 | + +**降级策略**： +- 微信小程序：如 `mask-composite` 不渲染，钻石边框会变成无边框（不致命，cover 仍可见） +- 微信小程序：如 `radial-gradient` 降级为 linear，标签渐变变为纯色（视觉略降级） + +## 可访问性 + +- `prefers-reduced-motion: reduce` 媒体查询关闭 `.ring-item` 和 `.crown` 的动画 +- 标签文字使用高对比度的 `#FFFABD` + 红色 `text-shadow` +- TOP 1 卡片有皇冠装饰作为「第一名」视觉提示 + +## 状态管理 + +| 状态 | 触发条件 | 表现 | +|----|----|----| +| Loading | 初次加载 | 12 个骨架占位（3 大 + 9 小）+ shimmer 动画 | +| Error | API 失败 | 「加载失败，点击重试」+ 重试按钮 | +| Empty | API 返回空数组 | 「暂无星河数据」 | +| Success | 12 条数据加载完成 | 完整布局 | + +## 已知限制 + +1. `prefers-reduced-motion` 触发时 9 个 item 会堆叠在 slot 0 位置（spec §6.4 已说明） +2. `ORBIT_KEYFRAMES` 模板字符串无法在 Vue `