xiaoyu/topfans
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f30655ec64
topfans/docs/superpowers/specs/2026-06-10-square-stargalaxy-component-design.md

11 KiB
Raw Blame History

星河（StarGalaxy）组件设计

日期: 2026-06-10 状态: 待评审 目的: 为 square 页面的「星河」tab 设计一个 3D 倾斜椭圆轨道 + 顺时针旋转的排行榜组件 参考文档: docs/figma-analysis-xiaohongshu-stars.md（Figma 节点 94:78「星河新版本」）

1. 背景

square 页面现有 3 个内容 tab（星河 / 星榜 / 广场），其中「星榜」是 12 行的横向列表样式（HotCategoryBlock.vue）。本次新增「星河」tab，沿用 Figma 中的双层结构：

  • 上层：TOP 1-3 颁奖台（cover + 下方标签 + 钻石渐变外框）
  • 下层：TOP 4-12 散落在 65° 倾斜椭圆轨道上，绕中心 3D 旋转

设计追求饭圈甜美梦幻风格（粉红渐变 + 玻璃拟态 + 暖黄光晕 + 渐变描边），不显示用户名/点赞数（保持 cover 纯净）。

2. 文件结构

frontend/pages/square/components/StarGalaxy/
├── index.vue              ← 容器：数据加载、装饰层、TOP 1-3 + ScatteredRanks 编排
├── PodiumCard.vue         ← TOP 1-3 颁奖台卡片（cover + 下方 TOP N 标签 + 钻石外框）
├── ScatteredRanks.vue     ← TOP 4-12 9 个散落 item（cover + 上方 TOP N 标签）
└── config.js              ← 9 slot 位置/translate/scale 公式

square.vue 改动：在星河 tab 分支中渲染 <StarGalaxy @cardClick="handleCardClick" />，复用现有 handleCardClick（单击跳详情 + 双击点赞）。

3. 组件职责

组件 职责 内部状态 输入 Props 事件
StarGalaxy/index.vue 数据加载（getHotRankingApi）、装饰层渲染、3D 椭圆轨道 SVG、布局编排 items、loading — cardClick(item)
PodiumCard.vue 单张 TOP 1-3 大卡：钻石渐变外框 + cover + 下方 TOP N 标签 + 可选皇冠 — rank: 4|5|6 隐式；item: HotRankingItem、size: {w,h} click(item)
ScatteredRanks.vue TOP 4-12 共 9 个 item 散落在椭圆轨道 — items: HotRankingItem[] (length=9) cardClick(item)
config.js 9 个 slot 的绝对位置/translate/scale/zIndex 公式 — — —

4. 数据流

StarGalaxy/index.vue (onMounted)
   │
   ├── getHotRankingApi("displaying", null, 1, 12)
   │       │
   │       └── res.data.items[0..11]
   │
   ├── Promise.all → getAssetCoverRealUrl(item.cover_url)  // 复用 HotCategoryBlock 的模式
   │
   └── items 拆成两段：
         ├── items.slice(0,3)  → PodiumCard × 3
         └── items.slice(3,12) → ScatteredRanks（9 个 item）

事件冒泡：所有 card 点击 → emit('cardClick', item) → square.vue 的 handleCardClick（已有，含单击跳详情 + 双击点赞）。

5. 视觉设计

5.1 容器尺寸

  • 总宽 750rpx × 高约 1440rpx
  • 适配 iPhone 标准 (375×812)
  • 整体分上下两层：上层颁奖台 y=48~700，下层椭圆轨道 y=800~1440

5.2 装饰层（背景 overlay）

  • 粉红渐变：linear-gradient(179deg, #FFE5E5 0%, #F3A0A1 0%, #FF9C9C 86%, #FF2024 100%)（覆盖 square 现有渐变之上）
  • 樱花粉光晕：圆形 #F3D3E3 + filter: blur(60px)，居中（top 580）
  • 暖黄光晕：圆形 #FFFABD + filter: blur(50px)，top 50
  • ⚠️ 不动 square.vue 现有渐变背景，星河只画自己的装饰层

5.3 PodiumCard 三个实例

排名 位置 (left, top) 卡片尺寸 标签尺寸 装饰图
TOP 1 (50%, 400) translateX(-50%) 240×260 (cover 240×260) 192×44 (金渐变) 钻石外框 + 皇冠
TOP 2 (60, 120) 200×200 (cover 200×200) 156×36 (银渐变) 钻石外框
TOP 3 (470, 150) 192×192 (cover 192×192) 156×36 (铜渐变) 钻石外框

PodiumCard 内部层级（从下到上）：

┌─ 钻石渐变外框（filter: blur(8-12px)，不规则圆角 8px 22px 8px 19px）
│  ├─ 藏品主图（不规则圆角 6px 20px 6px 17px）
│  ├─ 青绿色高光 overlay（180deg #53F4D3 → 透明）
│  └─ 钻石渐变边框层（4px 渐变描边）
└─ TOP N 标签（绝对定位 bottom: -4px，居中）

皇冠（仅 TOP 1）：绝对定位 top: -44px; left: 50%; transform: translateX(-50%)，font-size: 44rpx，2s 循环 pulse 动画。

5.4 ScatteredRanks 9 个 slot 位置

9 个 item 在 65° 倾斜椭圆上，等角度 40° 间隔（顺时针），起始角 180°（TOP 4 在正下方 = 最前）。

椭圆参数：

  • 圆心 (cx, cy) = (187, 510)
  • 水平半径 rx = 130
  • 垂直半径 ry = 55（cos(65°) ≈ 0.423，模拟向后倾斜 65°）
  • 起始角 startAngle = 180°（slot 0 在正下方）
  • 间隔角 step = -40°（顺时针 = 负方向）
Slot Rank 中心 (x, y) 渲染尺寸 (w×h) scale z-index
0 TOP 4 (187, 565) 46×70 1.15 10
1 TOP 5 (271, 552) 46×70 1.05 9
2 TOP 6 (321, 488) 46×70 0.95 6
3 TOP 7 (300, 482) 46×70 0.85 3
4 TOP 8 (232, 458) 46×70 0.75 0
5 TOP 9 (142, 458) 46×70 0.75 0
6 TOP 10 (74, 482) 46×70 0.85 3
7 TOP 11 (8, 488) 46×70 0.95 6
8 TOP 12 (80, 518) 46×70 1.05 9

OVERRIDES：TOP 6 / TOP 11 推到边缘 (8, 488) 和 (321, 488)，避免与 TOP 5/7、TOP 12/10 重叠。

5.5 单个 item 结构（ScatteredRanks）

尺寸 46×70 = label 14 + gap 2 + cover 56：

<view class="ring-item">
  <view class="top-label">TOP 4</view>   <!-- 14rpx，label 在 cover 上方 -->
  <image class="cover" src="..." />      <!-- 56rpx，cover 在 label 下方 -->
</view>
  • label（顶部 14rpx）：
    • 背景：radial-gradient(ellipse, #C8E6FF, #fff 50%, #4D9AF8)（蓝白钻石）
    • TOP 4 label 用金渐变：#FFFFFF, #FFFABD 30%, #4D9AF8 100%
    • 圆角 7rpx
    • 文字：14rpx Baloo Bhai（fallback monospace），色 #FFFABD，text-shadow: -1px 1px 2px rgba(206,9,9,0.84)
  • cover（下方 56rpx）：
    • 圆角 5rpx
    • box-shadow：3px 3px 6px rgba(198,13,13,0.45)（按 scale 调整）

5.6 颜色 / 渐变 / 阴影

Token 值 用途
主背景 linear-gradient(179deg, #FFE5E5 0%, #F3A0A1 0%, #FF9C9C 86%, #FF2024 100%) 装饰层渐变
樱花粉光晕 #F3D3E3 + blur(60px) 椭圆中心光晕
暖黄光晕 #FFFABD + blur(50px) 顶部装饰光晕
钻石渐变（外框） radial-gradient(ellipse at -10% 5%, #86BEFF, #FF3939 32%, #88FFCE 59%, #4D9AF8) PodiumCard 描边
蓝白钻石（标签） radial-gradient(ellipse, #C8E6FF, #fff 50%, #4D9AF8) 9 item label
金渐变（TOP 4 label） radial-gradient(ellipse, #FFFFFF, #FFFABD 30%, #4D9AF8 100%) TOP 4 label
金渐变（TOP 1 标签） radial-gradient(ellipse, #FFD700, #FFF6A8 30%, #DAA520 100%) TOP 1 标签
银渐变（TOP 2 标签） radial-gradient(ellipse, #C0C0C0, #E8E8E8 50%, #7A7A7A) TOP 2 标签
铜渐变（TOP 3 标签） radial-gradient(ellipse, #CD7F32, #E8A45C 50%, #A0522D) TOP 3 标签
TOP 数字字色 #FFFABD + text-shadow: -1px 1px 2px rgba(206,9,9,0.84) label 文字
卡片阴影 3px 3px 6px rgba(198,13,13,0.45)（随 scale 微调） cover 阴影

5.7 字体

字体 用途 Fallback
Baloo Bhai label 数字（TOP 4、TOP 5 等） monospace
HYQiHei 不使用（已移除用户名显示） PingFang
C800 不使用（已移除 TOP 排名文字） system bold sans

6. 动画设计

6.1 9 item 顺时针旋转

@keyframes orbit {
  0%      { transform: translate(0,0)         scale(1.15); }   /* slot 0: front */
  11.11%  { transform: translate(84px,-13px)  scale(1.05); }   /* slot 1 */
  22.22%  { transform: translate(157px,-43px) scale(0.95); }   /* slot 2 */
  33.33%  { transform: translate(113px,-83px) scale(0.85); }   /* slot 3 */
  44.44%  { transform: translate(45px,-107px) scale(0.75); }   /* slot 4 */
  55.55%  { transform: translate(-45px,-107px) scale(0.75); }  /* slot 5 */
  66.66%  { transform: translate(-113px,-83px) scale(0.85); }  /* slot 6 */
  77.77%  { transform: translate(-156px,-43px) scale(0.95); }  /* slot 7 */
  88.88%  { transform: translate(-84px,-13px) scale(1.05); }   /* slot 8 */
  100%    { transform: translate(0,0)         scale(1.15); }   /* loop */
}
  • 总周期 36s，4s 一步
  • 线性 timing，匀速旋转
  • infinite 循环

6.2 9 个 item 的 delay 错开

.ring-item { animation: orbit 36s linear infinite; }
.r0 { animation-delay:  0s; }     /* TOP 4 起始 slot 0 */
.r1 { animation-delay: -4s; }     /* TOP 5 起始 slot 1 */
.r2 { animation-delay: -8s; }     /* TOP 6 起始 slot 2 */
...
.r8 { animation-delay: -32s; }    /* TOP 12 起始 slot 8 */

负值 delay 让每个 item 起始位置 = 对应的 slot，9 个 item 静态分布在 9 个 slot 上。

6.3 皇冠脉冲

@keyframes crownPulse {
  0%, 100% { transform: translateX(-50%) scale(1); }
  50%      { transform: translateX(-50%) scale(1.15); }
}
.crown { animation: crownPulse 2s ease-in-out infinite; }

6.4 可访问性

@media (prefers-reduced-motion: reduce) {
  .ring-item { animation: none; }
  .crown { animation: none; }
  /* item 用 inline transform 写到元素上，作为静态位置 */
}

7. 状态管理

状态 显示
Loading 12 个骨架占位（3 大 + 9 小）+ shimmer 动画
Success 完整布局
Empty (items.length < 3) 「数据加载中」+ 重试按钮
Error 居中提示「加载失败，点击重试」+ 重试按钮

8. 交互细节

  • 单击 PodiumCard / ScatteredRank 缩略图：emit('cardClick', item) → square.vue 已有逻辑 → 跳 pages/asset-detail/asset-detail
  • 双击：同样走 square.vue 的 handleCardClick → doubleTapLike + 波纹动画
  • TOP 1 奖牌/皇冠：CSS keyframes 微脉冲（scale 1.0 → 1.15 → 1.0，2s 循环）

9. 性能/可访问性

  • 图片懒加载用 uni-app <image lazy-load>（与现有 HotCategoryBlock 一致）
  • prefers-reduced-motion: reduce 关闭旋转和脉冲
  • 9 item 动画使用 GPU 加速（transform）
  • 椭圆轨道 SVG 装饰层 pointer-events: none

10. 风险与备选

风险 缓解
旋转动画在低端机上卡顿 可降级到 60s 周期；或加 will-change: transform
椭圆轨道的虚线 SVG 在某些小程序不渲染 提供 v-if 兜底，仅 H5 显示
数据 < 9 条时 ScatteredRanks 渲染异常 用 v-for 配合 length 校验，< 9 时只渲染实际条数

11. 验收标准

  1. ✅ square 页点击「星河」tab，显示 12 个 item 的 3D 排行榜
  2. ✅ TOP 1-3 在上方颁奖台位置，cover 下方有金/银/铜 TOP N 标签
  3. ✅ TOP 4-12 在下方椭圆轨道，9 个 item 等大 46×70，标签在 cover 上方
  4. ✅ 9 item 顺时针连续旋转（36s 一圈）
  5. ✅ 近大远小（scale 0.75→1.15）表达 3D 透视
  6. ✅ 点击任一卡片跳 asset-detail
  7. ✅ 双击点赞 + 波纹动画
  8. ✅ Loading / Empty / Error 状态都正常显示
  9. ✅ prefers-reduced-motion: reduce 时关闭旋转
  10. ✅ H5 + 小程序 + APP 三端视觉一致