Topcoat fontsource_font_face! 宏:编译期校验的 Fontsource 字体面与 @font-face 生成指南
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")]保护,即需要启用assetfeature(见 [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`;- 同一参数重复出现时报
duplicateweight`` 等错误; - 未知关键字时报
expectedweight,style,subset,display, orhost``。
展开阶段的核心逻辑(impl ToTokens)可以分四步理解:
- 默认值填充:
subset未写时展开为FAMILY.default_subset,display未写时展开为topcoat_font::FontDisplay::Swap,host未写时按Host::JsDelivr处理。 - 编译期目录校验:当 family 解析成功时,对
weight、style、subset逐一生成compile_error!检查(组合在展开体中随构造一起输出,保证编辑器中展开依然可用)。 - 来源构造:若 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,保证展开体类型正确。 - 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 的 latinunicode-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 机制天然衔接。