@mai-kit/draw

@mai-kit/draw — 舞萌 DX 成绩海报 / Best 板 / 单曲卡 / 升分板绘制。

入口扁平：new Draw({ database }) 后 一种图一个方法（成对 PNG / SVG）。 末位共用 RenderOptions（scale / fonts / 页脚 / assetFallback）。 单曲卡只展示谱面成绩，不画玩家栏。

B50 海报

const draw = new Draw({ database });
const png = await draw.poster(profile, bests, {
  scale: 1,
  footerLeft: "my-app",
});

Best 板（署名 + prober Bests；库内只切割不排序）

const head = { name: profile.name, rating: profile.rating };
const opts = { scale: 1, footerLeft: "my-app" };
await draw.best15(head, bests, opts);
await draw.best35(head, bests, opts);
await draw.best50(head, bests, opts);

单曲卡

const png = await draw.chart(scoreChart, { scale: 1 });

加分板（全曲候选，宿主侧 analysis）

// 全曲 + 定数 + 真实 bests 地板；minRate 定目标评级（如 SSS+）
const candidates = rankBestsUpgradeCandidates(entries, {
  currentBests: bests,
  isNewSong,
  minRate: "sssp",
  limit: 10,
});
const png = await draw.upgrades({ candidates }, { scale: 1 });

• 落盘：只返回 Uint8Array / 字符串，由宿主保存或上传

处理 PNG 结果

Node 落盘：

import { writeFile } from "node:fs/promises";

const png = await draw.poster(profile, bests);
await writeFile("poster.png", png);

Web 预览：

const png = await draw.poster(profile, bests);
const url = URL.createObjectURL(new Blob([png], { type: "image/png" }));
image.src = url;

成绩海报指南 · 包与职责

绘制接口

名称	描述
Draw	成绩海报绘制入口：构造时注入 database，一种图一个方法（成对提供 PNG / SVG）。
AssetSource	素材来源接口。只声明 draw 用到的 getAsset；MaimaiDatabase（方法更多、 AssetType 更宽）可结构化直接传入，用户亦可自定义实现。
ChartTag	draw 聚合雷达图所需的最小社区标签结构
ChartTagSource	draw 与 database 解耦所用的最小标签来源接口
DrawOptions	Draw 构造配置。
MetricItem	个人数据网格一项
PlayerProfile	玩家档案（展示用，prober PlayerProfile 的结构子集）。
PosterData	完整 B50 海报绘制数据（仅 Draw.poster 需要整包）。 通常由 draw.poster(profile, bests) 内部经 buildPosterData 生成；也可自行组装后 draw.poster(data)。
PosterSummary	B50 汇总数字（海报左栏用）。
RadarItem	谱面倾向雷达一项（DXRating 社区标签）
RatingDistributionItem	评级分布饼图一项
RenderOptions	各出图方法共用的渲染选项（末位参数；均可省略）。
ScoreChart	成绩卡片（展示用，prober Score 的结构子集）。
SongListSource	曲目列表来源（可选）。与 ChartTagSource 常由同一 database 实现。 有则 Draw.poster / Best 板等方法 自动填 dx_max / level_value，调用方不必手算 map。
UpgradeBoardData	加分推荐板数据。
UpgradeCandidate	加分推荐列表中的一行。
AssetFallback	封面 / 头像等素材解析失败时的策略。
DrawAssetType	draw 实际需要的素材类型（@mai-kit/database AssetType 的子集，本地定义以解耦）
DrawSource	Draw 构造时的数据源：素材必选，标签与曲目列表按出图方法使用。
PosterDataSource	玩家数据聚合来源：标签必选；曲目列表可选（有则注入物量/定数）。
buildPosterData	将 prober 档案 + Best50 聚合成 PosterData（高级；多数场景直接 draw.poster）。

错误

名称	描述
DrawError	绘制层错误：字体加载、satori、resvg 或玩家数据聚合（如雷达标签不足）失败时抛出。
isDrawError	类型守卫：是否为 DrawError。

布局与格式化

名称	描述
BestBoardLayout	bestBoardLayout 计算出的 Best 板网格与字号几何。 所有尺寸与字号数值的单位都是逻辑像素。
BestPage	横屏 Best 板页种，对应 Draw.best15 / Draw.best35 / Draw.best50。
BEST_HEIGHT	Best 板逻辑画布高（与海报同为 1080）。
BEST_WIDTH	Best 板逻辑画布宽（与海报同为 1920）。
CHART_CARD_HEIGHT	单曲卡逻辑画布高（与 B50 同为 1080）。
CHART_CARD_WIDTH	单曲卡逻辑画布宽（与 B50 同为 1920）。
POSTER_HEIGHT	海报 JSX 布局与尺寸常量。
POSTER_WIDTH	海报 JSX 布局与尺寸常量。
UPGRADES_BOARD_HEIGHT	加分板逻辑画布高（与 B50 同为 1080）。
UPGRADES_BOARD_WIDTH	加分板逻辑画布宽（与 B50 同为 1920）。
B50Poster	海报 JSX 布局与尺寸常量。
BestBoard	Best 板 JSX 布局、尺寸与网格几何。
bestBoardLayout	Best 板 JSX 布局、尺寸与网格几何。
ChartCardPoster	单曲卡 / 升分板布局（高级）。
formatChartRating	布局组件使用的成绩格式化函数。
formatDxScore	布局组件使用的成绩格式化函数。
formatLevelConstant	布局组件使用的成绩格式化函数。
UpgradesBoard	加分推荐板 JSX（16:9，两列）。