掌机前端的媒体数据管理: SteamGridDB 封面抓取、图片规格与元数据源选择

Tue, 08 Sep 2026 16:00:00 +0000

掌机前端 iiSU 的界面是那种偏视觉的样式: 进游戏库是一格格方形封面, 选中某个游戏后整个背景换成一张横版大图, 大图正中再浮着游戏的文字 logo。我这个库里有四十多个 Switch 游戏, 一开始封面缺了一大半, 有图的也尺寸、比例、透明通道各不相同; 标题、发行信息这些元数据同样是缺的。手动去网上找图、一张张裁、再一个个填, 换到第十个游戏我就放弃了, 于是把它写成了一条批量流水线。封面和元数据看起来是两件事, 其实都是同一类活: 把外部的媒体数据整理成前端能直接用的格式。

前端要的三张图, 各管一块界面

最开始的误区是把三种图当成同一种封面。实际上它们各管界面的一块区域, 规格也不一样。

icon.png 是方格列表里那张方形封面, 也是游戏卡片的主图, 规格是 512×512、不透明的 RGB。hero_1.jpg 是选中游戏后的全屏背景, 横版 16:9, 我统一成 1280×720, 居中裁剪, 避免拉伸变形。title.png 最容易被搞错——它不是封面, 而是浮在背景之上的文字 logo 浮层, 必须是透明背景的 PNG(RGBA), 只在游戏 logo 处不透明, 同样 1280×720。

分辨方法很直接: 把这张图单独放在白底上看。如果它占满整张、有背景色, 那就是封面; 如果只有中间一行游戏名字、四周透明, 那是 logo 浮层。这个区分做对了, 界面才不会出现"方形 logo 糊在背景中间"或者"背景被拉成方块"的怪样子。有些游戏在 SteamGridDB 上根本没有横版 logo, 硬塞一张方形的进去只会变成中间一块糊图, 这种情况我干脆删掉 title.png, 让它不显示浮层, 反而干净。

flowchart TB
 A["ROM 目录名 / TitleID"] --> B["SteamGridDB API<br/>grids / logos / heroes"]
 B --> C["下载原图"]
 C --> D["统一规格<br/>居中裁剪 / 去黑图 / 透明通道"]
 D --> E["adb push 到<br/>consoles/&lt;平台&gt;/&lt;ROM名&gt;/"]
 E --> F["删除 rom_asset_index.fb<br/>重启前端重建索引"]

SteamGridDB 的三个端点

三种图对应 SteamGridDB 的三个资源端点, 用同一个游戏 ID 分别请求。方形封面走 grids/game/{id} 并带上 types=static&dimensions=512x512, 直接拿到接近目标规格的方图; 透明文字 logo 走 logos/game/{id}, 这里要注意挑横版比例大于 1.8 的那张, 否则会拿到偏方形的 logo, 浮在背景上很难看; 背景横幅走 heroes/game/{id}, 原始图通常是 1920×620, 需要自己裁成 16:9。

元数据 on Time Friend

掌机前端的媒体数据管理: SteamGridDB 封面抓取、图片规格与元数据源选择

前端要的三张图, 各管一块界面

SteamGridDB 的三个端点