Topcoat fontsource_font_face! 宏:编译期校验的 Fontsource 字体面与 @font-face 生成指南

原创2026-11-11 15:50:571,892 阅读
文章标签:后端Web框架前端

Topcoat fontsource_font_face! 宏:编译期校验的 Fontsource 字体面与 @font-face 生成指南

在 Topcoat 中通过 Fontsource 字体目录引入网络字体时,fontsource_font_face! 宏是创建单个 FontFace 的入口:以编译期校验的方式从 vendored 目录中选定 family、weight、style 等组合,并展开为可直接渲染 CSS @font-face 规则的类型安全构造代码。本文完整覆盖该宏的书写格式、全部参数及其默认值,并结合 宏入口、语法解析与展开实现、目录元数据 和 测试用例 说明其底层工作原理。

基本用法

fontsource_font_face! 从 Fontsource 目录创建一个 FontFace。书写规则是:family 名写在最前,其后是顺序任意的 name: value 参数,其中必须包含 weight 和 style 来选定具体的字体面:

use topcoat::font::*;
use topcoat::font::fontsource::*;

let face = fontsource_font_face!(
    ROBOTO,
    weight: 400,
    style: Normal,
);

所有取值都会在编译期对照 vendored 目录(crates/topcoat-font/fonts.json 经 build.rs 生成)进行校验,写错会直接得到编译错误而不是运行期问题。

参数详解

family(必需,第一个参数)

family 以 families 模块中常量的名字书写,例如 ROBOTO、JETBRAINS_MONO。每个常量是一个 SCREAMING_SNAKE_CASE 命名的 Family 元数据,包含该 family 的 Fontsource id、可读名、可用 subsets、权重、样式、默认 subset、是否 variable font、类别、SPDX 许可证、上游 provider 以及各 subset 的 unicode-range,定义见 Family 结构。

从源码结构看,宏展开时会把 ROBOTO 这样的标识符改写为 topcoat_font::fontsource::families::ROBOTO 路径,并通过 FamilyName::family() 调用 Family::by_ident 反查元数据,供后续所有校验与 URL 拼接使用。

weight(必需)

取值为该 family 实际提供的权重之一,范围在 100..=900。从 WeightValue::check 的实现可以确认:若 family 不提供该权重,宏会展开出一条 compile_error!,错误信息形如:

`Roboto` does not ship weight `600`; available: 100, 300, 400, 500, 700, 900

即直接把该 family 的全部可用权重列在错误信息里。

style(必需)

取值为 Style 枚举的 Normal 或 Italic,且 family 必须提供该样式(由 Family::has_style 校验,缺失同样触发 compile_error!)。

subset(可选,默认 family 默认 subset)

subset 选择字符集,如 Latin 或 Cyrillic,同时决定该字体面的 unicode-range 描述符。省略时取 family 的 default_subset。subset 枚举 subset.rs 本身也是从 vendored 目录生成的。

subset 有两个作用:其一,它进入 CDN URL 的文件名(latin-400-normal.woff2);其二,目录中为每个命名 subset 附带 unicode-range,宏会将其展开为 .with_unicode_range(...) 调用。测试用例 fontsource_font_face.rs 中给出了 Roboto 两个 subset 的真实 unicode-range 常量,例如 cyrillic 对应 U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116。

display(可选,默认 Swap)

display 设置字体加载期间文本的呈现方式,接受 FontDisplay 值,省略时宏会填入 FontDisplay::Swap。FontDisplay 共五个变体,均直接映射 CSS font-display 关键字:

变体 CSS 关键字 行为
Auto auto 由用户代理决定(Default 实现)
Block block 短阻塞期 + 无限交换期
Swap swap 极短阻塞期 + 无限交换期(宏的默认值)
Fallback fallback 极短阻塞期 + 短交换期
Optional optional 极短阻塞期 + 无交换期

host(可选,默认 JsDelivr)

host 选择字体文件的来源,取值为 Host 枚举:

  • JsDelivr(默认):字体文件直接从 jsDelivr CDN 加载;
  • Asset:把 Fontsource 字体文件下载并打包为 Topcoat asset,由自己的服务器提供。该变体被 #<a href="https://link.gitcode.com/i/7cfdb634522a6eed3ea677bfc7878785" target="_blank">cfg(feature = "asset")] 保护,即需要启用 asset feature(见 [topcoat-font 的 Cargo.toml 中 asset = ["dep:topcoat-asset"])。

完整参数示例

use topcoat::font::*;
use topcoat::font::fontsource::*;

let face = fontsource_font_face!(
    ROBOTO,
    weight: 700,
    style: Italic,
    subset: Cyrillic,
    display: Optional,
    host: Asset,
);

宏展开机制与生成的 CSS

fontsource_font_face 是一个 proc macro,入口在 macro/src/lib.rs,它把输入解析为 FontsourceFontFace 语法节点。解析阶段的规则(见该文件的 impl Parse):

  • weight 与 style 缺失时分别报错:`fontsource_font_face!` requires a `weight` / requires a `style`;
  • 同一参数重复出现时报 duplicate weight`` 等错误;
  • 未知关键字时报 expected weight, style, subset, display, or host``。

展开阶段的核心逻辑(impl ToTokens)可以分四步理解:

  1. 默认值填充:subset 未写时展开为 FAMILY.default_subset,display 未写时展开为 topcoat_font::FontDisplay::Swap,host 未写时按 Host::JsDelivr 处理。
  2. 编译期目录校验:当 family 解析成功时,对 weight、style、subset 逐一生成 compile_error! 检查(组合在展开体中随构造一起输出,保证编辑器中展开依然可用)。
  3. 来源构造:若 family、weight、style、subset 全部在展开期可解析,则通过 Family::jsdelivr_url 把 CDN URL 直接烘焙(bake)为字符串字面量,形如 https://cdn.jsdelivr.net/fontsource/fonts/roboto@latest/latin-400-normal.woff2;host: Asset 时则额外展开一个 const ASSET: topcoat_asset::Asset = topcoat_asset::asset!(#url);,让 Topcoat 把该文件下载进 asset bundle 并自行分发。若某项无法在展开期解析,则回退为运行期调用 FAMILY.jsdelivr_url(SUBSET, WEIGHT, STYLE) 构造 URL,保证展开体类型正确。
  4. Face 构造链:最终展开为 FontFace::new(FAMILY.name, src).with_weight(FontWeightRange::from_u16(WEIGHT, WEIGHT)).with_style(STYLE.as_font_style()).with_display(DISPLAY),并在目录提供了该 subset 的 unicode-range 时追加 .with_unicode_range(UnicodeRanges::new(&[UnicodeRange::from_u32(..), ..]))。

渲染侧由 FontFace::fmt 负责:写出完整的 @font-face { ... } 块,未设置的描述符(weight/style/display/unicode-range 均为 Option)自动省略。以测试中 Roboto 默认参数面为例,实际渲染结果是:

@font-face { font-family: "Roboto"; src: url("https://cdn.jsdelivr.net/fontsource/fonts/roboto@latest/latin-400-normal.woff2") format(woff2); font-weight: 400; font-style: normal; font-display: swap; unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD }

其中 src 附带 format(woff2) 提示,这正是 ToTokens 里 FontSource::url(.., Some(FontFormat::Woff2), None) 的产物。

用测试验证的行为边界

crates/topcoat-font/macro/tests/fontsource_font_face.rs 覆盖了该宏的关键语义,可作为行为依据:

  • minimal_face_uses_the_default_subset:只写 weight/style 时 URL 使用 latin 文件且带上 vendored 的 latin unicode-range;
  • explicit_subset_drives_the_url_and_unicode_range:subset: Cyrillic 同时驱动 URL 文件名(cyrillic-700-italic)与 unicode-range;
  • arguments_in_any_order:参数顺序任意;
  • display_defaults_to_swap 与 explicit_display_overrides_the_default:默认 swap、显式 Fallback 可覆盖;
  • host_defaults_to_jsdelivr:默认 host 与显式 host: JsDelivr 生成等价的 FontFace;
  • self_hosting_changes_the_source:host: Asset 生成的源与 CDN 源不同(指向自家 bundle)。

在页面中集成

单个 FontFace 通常作为 fontsource_font! 创建的整体 Font 的一部分使用;后者会为每个请求的 weight/style/subset 组合各生成一个 face。把字体接入页面时,只需在 <head> 中渲染 topcoat::font::link,它会输出字体所需的 preload 与 style 元素。仓库自带示例 examples/font/src/main.rs 展示了两种 host 的完整用法:

// `host: Asset` 会把字体文件下载进 asset bundle,由 Topcoat 自己分发
const LAVISHLY_YOURS: Font = fontsource_font!(LAVISHLY_YOURS, host: Asset);

#[page]
async fn home(cx: &Cx) -> Result<impl View> {
    Ok(view! {
        <!DOCTYPE html>
        <html>
            <head>
                <title>"Fonts"</title>
                topcoat::dev::script()
                // 渲染字体所需的 preload 与 style 元素
                topcoat::font::link(font: LAVISHLY_YOURS)
            </head>
            <body>
                <h1 style=(format!("font-family: {:?}", LAVISHLY_YOURS.family()))>
                    "Self-hosted via Topcoat assets!"
                </h1>
            </body>
        </html>
    })
}

该示例同时在 examples/font/README.md 所在目录中给出了完整工程,可直接 cargo run 查看效果(需启用 asset feature 才会编译 host: Asset 路径)。

目录数据从何而来

families、Subset 等模块的内容由构建脚本生成:crates/topcoat-font/build.rs 读取 vendored 的 fonts.json,写出 OUT_DIR 下的 families.rs、subset.rs 等文件,再被 src/fontsource/families.rs 与 src/fontsource/subset.rs 通过 include! 引入。此外,Cargo.toml 中的 fontsource-refresh feature 会启用 refresh 二进制,它从 Fontsource API 拉取最新数据——这是目录数据的上游刷新手段,日常使用只需 fontsource feature。

小结

fontsource_font_face! 用“family 常量 + 任意顺序的 name: value 参数”这一极简语法,覆盖了创建单个 Fontsource 字体面所需的全部决策:weight 与 style 必填,subset 默认取 family 默认字符集,display 默认 Swap,host 默认 JsDelivr(或启用 asset feature 后以 Asset 自托管)。所有取值在编译期对照 vendored 目录校验,URL 与 unicode-range 在可解析时直接烘焙进展开代码,最终由 FontFace::fmt 渲染为带 format(woff2) 提示的 @font-face 规则——类型安全、错误前置,且与 Topcoat 的 asset、link 机制天然衔接。

登录后查看全文
topcoat