D2 字体嵌入机制全解析SVG 内嵌字体、自定义字体接入与跨平台回退【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2D2d2lang/d2是一款把文本变成图表的现代图表脚本语言其 SVG 渲染器会把字体文件直接以 base64 数据的形式内嵌进 SVG从而保证输出结果确定、且无需任何网络请求即可在浏览器中完整呈现。本篇指南以d2renderers/d2fonts/README.md为核心骨架结合仓库源码系统讲解 D2 的内嵌字体机制、如何为 D2 接入自己的字体如 Helvetica、内置字体家族的资源组织方式以及主字体缺字时的回退策略读完你就能自行定制 D2 输出中的字体并理解其底层原理。为什么要把字体直接嵌进 SVGd2renderers/d2fonts/README.md开篇就给出了这一设计的两个核心动机确定性输出deterministic outputs字体随 SVG 一起打包不依赖查看端机器上是否安装了对应字体同一份.d2源码在任何环境渲染出的字形完全一致无网络调用load without a network callSVG 打开即完整渲染不依赖外链的字体 CDN也不受离线场景限制。因此D2 的 SVG 输出中会携带形如data:application/font-woff;base64,AAAA...的字体 data URI见 d2fonts_common.go这些 base64 字符串正是嵌入字体的载体。内置字体家族与资源目录布局d2fonts包默认内置三个字体家族定义于 d2fonts_common.go字体家族类型用途SourceSansPro无衬线体默认字体对应--theme下的普通文本SourceCodePro等宽字体代码块 / 等宽场景对应monoHandDrawnFuzzyBubbles手绘风格草图/手绘主题每个家族按四种字型style组织常量定义在 d2fonts_common.goregular、bold、semibold、italic。字号从 XS 到 XXXL 共 8 档取值 13、14、16、20、24、28、32见 d2fonts_common.go。资源文件按构建目标分两种形态存放于 d2renderers/d2fonts/encoded/非 WASM原生构建嵌入encoded/*.txt即 base64 编码的 WOFF 文本与ttf/*.ttf原文件见 d2fonts_embed.go 同目录的 d2fonts_embed.go 中//go:embed encoded/SourceSansPro-Regular.txt等指令WASM 构建嵌入encoded/*.txt.brBrotli 压缩后的编码文本运行时解压见 d2fonts_embed_wasm.go 与 d2fonts_embed_wasm.go 中的compression.DecompressBrotli解压逻辑。两种形态的存在是为了压缩 JS/WASM 包的体积源码注释d2fonts_common.go对此有明确说明。每个内嵌字体的字型映射在init()中注册到FontEncodings编码字符串与FontFacesTTF 字节两个全局注册表d2fonts_embed.go。其中HandDrawn家族没有独立的 italic 与 semibold 字型会分别复用 regular 和 boldd2fonts_embed.go。此外D2 还把内置字体含 Noto Color Emoji的 SHA-256 摘要固定注册供光栅化管线做身份校验见 bundled_faces.go 中的bundledFaceSpecs与fontface.RegisterBundledFace调用。如何接入自定义字体以 Helvetica 为例README 以Helvetica为例给出了添加自定义字体的完整要求。第一步提供 Truetype 字形文件.ttf放入d2renderers/d2fonts/ttf/目录./ttf/Helvetica-Bold.ttf ./ttf/Helvetica-Italic.ttf ./ttf/Helvetica-Regular.ttf第二步提供这些字体的编码版本mimetype 必须为application/font-woff放入d2renderers/d2fonts/encoded/目录与 TTF 一一对应./ttf/Helvetica-Bold.txt ./ttf/Helvetica-Italic.txt ./ttf/Helvetica-Regular.txt注意两点其一编码文件内容本质上就是data:application/font-woff;base64,base64形式的 WOFF 数据文本README 中的./ttf/Helvetica-*.txt为相对encoded/目录的示意路径实际目录见 d2renderers/d2fonts/encoded/其二若想贡献字体给 D2 仓库该字体必须具有开源许可证README 明确要求If you include a font to contribute, it must have an open license.。仓库源码为先转 WOFF 再 base64这一流程提供了直接实现AddFontStyle会调用fontlib.Sfnt2Woff(ttf)把 TTF 转成 WOFF再用base64.StdEncoding.EncodeToString编码并拼接data:application/font-woff;base64,前缀d2fonts_common.go。缺失字型的回退行为AddFontFamily是运行时注册自定义字族的入口d2fonts_common.go签名如下func AddFontFamily(name string, regularTTF, italicTTF, boldTTF, semiboldTTF []byte) (*FontFamily, error)传入的四个字型 TTF 均可为空nil某个字型缺失时会自动回退到 SourceSansPro 的对应字型如无 italic 则用 SourceSansPro-Italic保证图表的粗体、斜体仍然成立见 d2fonts_common.go 等处的 fallback 分支注册成功后该自定义家族会被追加进全局FontFamilies列表从而参与后续渲染。运行时的字形子集化D2 并非把整份字体嵌入每个 SVG而是按文本语料做子集化Font.GetEncodedSubset(corpus string)会先去重提取语料中的唯一字符uniqueChars调用font.UTF8CutFont(fontBuf, uniqueChars)裁剪出仅含所需字形的最小 TTF再经fontlib.Sfnt2Woff转 WOFF 并 base64 编码d2fonts_common.go。若子集化失败如字体结构特殊则回退到完整字体的编码FontEncodings.Get(f)保证功能不中断。这解释了为什么最终 SVG 既自带字体、又不会过分臃肿。CLI 层面对字体的配置自定义字体不仅能在仓库内硬编码还可在命令行直接指定 TTF 路径。d2cli提供了 8 个字体相关参数main.go均有环境变量与 flag 两种写法环境变量Flag说明缺省值D2_FONT_REGULAR--font-regular常规字体 TTF 路径Source Sans Pro RegularD2_FONT_ITALIC--font-italic斜体字体 TTF 路径Source Sans Pro ItalicD2_FONT_BOLD--font-bold粗体字体 TTF 路径Source Sans Pro BoldD2_FONT_SEMIBOLD--font-semibold半粗体字体 TTF 路径Source Sans Pro SemiboldD2_FONT_MONO--font-mono等宽常规字体 TTF 路径Source Code Pro RegularD2_FONT_MONO_BOLD--font-mono-bold等宽粗体 TTF 路径Source Code Pro BoldD2_FONT_MONO_ITALIC--font-mono-italic等宽斜体 TTF 路径Source Code Pro ItalicD2_FONT_MONO_SEMIBOLD--font-mono-semibold等宽半粗体 TTF 路径Source Code Pro Semibold例如d2 --font-regular/path/to/Helvetica-Regular.ttf \ --font-bold/path/to/Helvetica-Bold.ttf \ --font-italic/path/to/Helvetica-Italic.ttf \ --font-semibold/path/to/Helvetica-Semibold.ttf \ input.d2 output.svgloadFonts实现main.go会读取各路径的 TTF 字节并调用d2fonts.AddFontFamily(custom, ...)与d2fonts.AddFontFamily(customMono, ...)分别注册主字体族与等宽字体族。也就是说CLI 方式无需预先准备 WOFF 编码文本——TTF 会在加载时由Sfnt2Woff现场转换而 README 所述的*.txt编码文件是为内置/贡献字体这种静态嵌入场景准备的。主字体缺字时的回退解析当文本中的字符超出主字体覆盖范围如中文、阿拉伯文、表情符号时d2fonts提供两级回退内置 Noto Color Emoji 兜底BundledFallbackResolver优先用仓库固定的 Noto Color EmojiNotoColorEmoji-COLRv1-v2.051.ttf.br见 encoded/解析支持的符号与 emoji保证跨机器字形确定bundled_fallback.go。在 js/wasm 构建下该内置字形缺失请求直接透传给下游系统字体回退SystemFallbackResolver按操作系统约定的字体根目录扫描候选字体macOS 的/System/Library/Fonts、/Library/FontsLinux/BSD 的/usr/share/fonts、/usr/local/share/fontsWindows 的%WINDIR%\Fonts见 fallback.go仅当内置字体无法覆盖时才动用。它通过 cmap 探针轻量检查覆盖范围fallback.go并按字形权重、斜体、等宽等属性为候选排序fallback.go同时用SystemFallbackLimits目录条目数、文件数、扫描字节、覆盖检查次数等约束整个检索过程fallback.go避免无界开销。这一两级回退机制在 fallback_test.go 等测试中都有覆盖包括回退字节必须独立拷贝、不得与原文件共享底层数组等细节。小结D2 通过data:application/font-woff;base64,...将字体内嵌进 SVG兼顾确定性输出与离线可用内置家族为 SourceSansPro、SourceCodePro、HandDrawnFuzzyBubbles每个家族含 regular/bold/semibold/italic 四种字型原生构建嵌入encoded/*.txtWASM 构建嵌入 Brotli 压缩的encoded/*.txt.br自定义字体需提供 TTF 及其 WOFF base64 编码文本mimetype 为application/font-woff贡献给仓库的字体必须有开源许可证运行时按语料做字形子集化后再编码避免 SVG 冗余CLI 提供--font-regular等 8 个参数直接加载外部 TTF主字体缺字时先走内置 Noto Color Emoji 兜底再按严格限额扫描系统字体目录保证任意脚本文本都能确定性渲染。相关源码入口d2fonts_common.go、d2fonts_embed.go、d2fonts_embed_wasm.go、fallback.go、bundled_fallback.go、CLI 字体参数。【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考