From 9a607544019d06f0cefbaf943f1b513dbf5f4e40 Mon Sep 17 00:00:00 2001
From: Jz0ojiang <0ojixueseno0@gmail.com>
Date: Fri, 4 Sep 2026 16:38:34 +0800
Subject: [PATCH] =?UTF-8?q?contract:=20FontEntry=20=E5=8A=A0=20subfamily?=
 =?UTF-8?q?=EF=BC=8Cfamily=20=E6=94=B9=E7=94=A8=20name=20=E8=A1=A8?=
 =?UTF-8?q?=E7=9A=84=E6=8E=92=E7=89=88=E6=97=8F=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

注册表值名不是字体身份。实测阿里巴巴普惠体 H：
  注册表「阿里巴巴普惠体-H」、nameID 1「阿里巴巴普惠体 H」— 浏览器都解析不到
  nameID 16「阿里巴巴普惠体」+ nameID 17「Heavy」— 能解析

subfamily 退回 nameID 2 是有损的：该族五个字重的 nameID 2 全是 Regular。

(cherry picked from commit 44b98102741af90620871156d60edf54326df78d)
---
 src/types.ts | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/types.ts b/src/types.ts
index cc12ead..b84d37c 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -32,8 +32,27 @@ export interface CanvasSize {
 export interface FontEntry {
   /** 稳定 id，用于取文件；不要假设它等于文件名。 */
   id: string;
-  /** 用于 CSS font-family 和界面显示的字族名，如 "阿里巴巴普惠体-H"。 */
+  /**
+   * 排版字族名，用作 CSS `font-family`。来源是字体文件 `name` 表的 **nameID 16**，
+   * 缺失才退回 nameID 1。**不是注册表的值名**——那是安装程序起的标签，不是字体身份。
+   *
+   * 反例（2026-09-04 实测）：阿里巴巴普惠体 H 的注册表值名是「阿里巴巴普惠体-H」，
+   * nameID 1 是「阿里巴巴普惠体 H」，两者在浏览器里都解析不到；
+   * 只有 nameID 16 的「阿里巴巴普惠体」能解析。
+   *
+   * `name` 表里同一个 nameID 有中英两份记录（langID 2052 / 1033）。
+   * 取中文那份，没有中文再取英文——本机两者都能解析，中文在下拉里更好认。
+   */
   family: string;
+  /**
+   * 样式名，如 `Heavy` / `Bold` / `Regular` / `斜体`。来源是 **nameID 17**，
+   * 缺失才退回 nameID 2。用来在下拉里区分同族多字重，并映射到 `fontWeight` / `fontStyle`。
+   *
+   * **退回 nameID 2 是有损的**：阿里巴巴普惠体五个字重的 nameID 2 全是 `Regular`，
+   * 只有 nameID 17 才区分得出 Heavy / Bold / Medium / Regular / Light。
+   * 退回时同族多档会塌成一个，界面上要能看出这种情况。
+   */
+  subfamily: string;
   /** 字体文件绝对路径（仅供调试与配方记录，前端不直接读）。 */
   path: string;
   /** 文件后缀，小写不带点：ttf / otf / ttc / woff2 … */