JavaScript CSS Font Loading API 怎样只等待指定字体加载

只等待某个字体匹配范围，可以调用 await document.fonts.load('700 30px "Orchard Head"', "仓储月报")，明确家族、字重、字号和文本。它返回匹配并加载的 FontFace 数组；不要为了一个标题直接等待整份 document.fonts.ready，也不要把同步 check() 当作加载请求。

MDN 接口文档地址：https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/load

先区分三种等待需求

假设报告页面的标题使用专用粗体，正文和图标还使用另外的字体。业务只需要为标题准备后续工作，等待范围就应该围绕标题声明，而不是把不相关字体都作为显式前置条件。这里的“只等待”指调用方等待选中的匹配集合，不会禁止页面其他字体继续加载。

ready 文档说明其 Promise 与文档字体及布局完成有关。它也不是页面未来所有动态字体的永久承诺。选择接口前应先确定后续操作依赖单个标题字体，还是当前文档的整体状态。

声明目标字重并传入实际文本

/* 示例资源需替换为项目合法提供的700字重字体文件。 */
@font-face {
  font-family: "Orchard Head";
  src: url("/fonts/orchard-head-bold.woff2") format("woff2");
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}
.report-title {
  font: normal 700 30px "Orchard Head", sans-serif;
}

async function waitTitleFont() {
  // 同时指定字重、字号、家族，以及真正用于标题的文本。
  const faces = await document.fonts.load(
    'normal 700 30px "Orchard Head"', "仓储月报"
  );
  if (faces.length === 0) {
    throw new Error("没有匹配的可加载 FontFace");
  }
  return faces;
}
// 调用者应使用 await 或 catch 处理拒绝，不能只发起后立即继续。

上述代码为原创示例，字体路径需要读者提供资源；本文没有加载字体、运行浏览器或制作实测截图。样式表需先被加载并让规则生效，再发起查询。仅写字体家族名而漏掉必需的字号，不是这里要求的 font 简写语法。

第二个参数应采用后续实际使用的文字。默认文本是空格，对分片字体而言可能匹配不到标题所需范围。根据 load 方法文档，文本参数限制的是 Unicode 范围有交集的字体面，并不检查每个字形是否确实存在。

为一个标题封装有期限的等待

界面不能总是无限等待网络。下面把可用、未匹配、错误、超时和不支持区分开，方便调用方决定后续动作。等待期限为示例业务值，不是浏览器推荐阈值。

async function waitReportTitleFont(text, timeoutMs = 2500) {
  if (typeof text !== "string" || text.length === 0) {
    throw new TypeError("需要非空标题文本");
  }
  if (!Number.isFinite(timeoutMs) || timeoutMs 
    document.fonts.load('normal 700 30px "Orchard Head"', text)
  ).then(
    (faces) => ({ status: faces.length ? "loaded" : "unmatched", faces }),
    (error) => ({ status: "error", faces: [], error })
  );
  const deadline = new Promise((resolve) => {
    timer = setTimeout(() => {
      resolve({ status: "timeout", faces: [] });
    }, timeoutMs);
  });
  try {
    // 期限只限制业务等待，不会取消浏览器里的字体请求。
    return await Promise.race([loading, deadline]);
  } finally {
    clearTimeout(timer);
  }
}

async function prepareReportTitle() {
  const state = await waitReportTitleFont("仓储月报");
  if (state.status === "loaded") {
    // 在这里继续依赖目标字体的业务工作；不表示整页已排版完成。
    return state;
  }
  // 由产品决定降级还是提示重试，保留失败类别供调用方使用。
  console.warn("标题字体未就绪：", state.status);
  return state;
}

这份函数适用于浏览器文档环境，不是服务端通用函数。loaded 只表示本次匹配集合完成，unmatched 则提醒调用方没有得到目标字体面。返回错误而不统一退化成成功，可以避免字体声明拼错时仍误以为已完成目标字体准备。

Promise.race 不会取消落后的一方。超时后请求可能仍在进行，字体后来加载完成时页面也可能发生字体替换；如果产品要求整个任务不再接受迟到结果，需要在调用方加入自己的任务状态判断，不能把 timeout 解释为浏览器撤销了加载。

解释匹配成功不能证明什么

没有相应字体面时，调用可能以空数组完成，所以仅有 Promise fulfilled 不足以宣称目标字体存在。另一方面，多个 Unicode 分片可能同时匹配；数组多于一项也不意味着加载了所有不相关家族。匹配及加载语义可参考 CSS Font Loading 规范草案。

等待一个 FontFaceSet.load 不等同于对目标 DOM 元素的最终渲染做确认。元素可能另有更高优先级样式，文字也可能部分回退到其他家族；loaded 状态不能替代这些呈现条件，更不能代表整页尺寸已经稳定。

check 更容易被误用：即使家族不存在，也可能返回 true，因此不应把它当成“这个品牌字体已安装”的证明。这个限制在 check 方法说明中有明确解释。这里直接以 load 的结果数组与失败类别组织业务，而不是先 check 为真就跳过所有判断。

常见问题

等待 400 字重后，700 标题就一定准备好了吗？

不一定。应按目标标题实际使用的字重与样式传入匹配条件，避免把常规体的结果当作粗体资源的承诺。

为什么字体声明存在仍返回空数组？

检查规则是否已进入当前文档、家族名是否对应，以及文本是否与声明范围匹配。字体名称写在代码里并不自动为它建立 FontFace。

动态添加标题后需要再次等待吗？

如果字重、家族或实际文字范围改变，就需要重新明确此次依赖。旧的成功结果只回答旧条件，不能覆盖后来引入的新字体面。