面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## FontSpec

```cpp
struct FontSpec {
    std::wstring familyName = L"Segoe UI";
    float size = 14.0f;
    DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
    DWRITE_FONT_STYLE  style  = DWRITE_FONT_STYLE_NORMAL;
    DWRITE_FONT_STRETCH stretch = DWRITE_FONT_STRETCH_NORMAL;
    std::wstring locale = L"en-us";
    bool operator==/!=(...) const;
};
```

## FontManager(单例,文本布局缓存)

```cpp
static FontManager& Instance();
IDWriteFactory* GetFactory();
IDWriteTextFormat* GetFormat(const FontSpec&);
bool SetAppFontCollection(IDWriteFontCollection*);   // install once, before formats
ComPtr<IDWriteTextLayout> GetRawLayout(text, fmt, maxW, maxH, noWrap);
ComPtr<IDWriteTextLayout> GetDisplayLayout(origText, fmt, maxW, maxH, noWrap);   // 带省略号
ComPtr<IDWriteTextLayout> GetStyledLayout(text, fmt, w, h, noWrap, hAlign, vAlign, lineSpacing, maxLines);
ComPtr<IDWriteTextLayout> GetStyledDisplayLayout(...);
void CacheDisplayLayout(...); void CacheStyledDisplayLayout(...);
void SetGlobalFont(const FontSpec&);
ZSignal<> GlobalFontChanged;
```
- `SetAppFontCollection` 必须在任何 format/layout 创建之前调用;已有缓存或已安装时返回 `false`。内部持有集合引用;菜单直接 `CreateTextFormat` 的路径仍用系统字体。
- 布局缓存**有上限**(400 条,FIFO 淘汰 ¼);返回强引用(`ComPtr`),调用期间不会被淘汰。

###block_red_start
**易错**

- 返回的 layout 是**共享只读**对象,**不要**对它 `SetTextAlignment/SetLineSpacing/SetTrimming`——缓存 key 会与对象不一致。
- `GetFormat` 返回的 `IDWriteTextFormat*` **永不淘汰**,请勿修改它。
- `GetFormat` 的共享 format 把 `ParagraphAlignment` 设成了 `CENTER`。**不要直接拿它画多行自绘文本**,否则会被垂直居中到高盒外(看起来“没字”);用 `GetStyledLayout(..., vAlign)` 或自建 format 并设 `NEAR`。
###block_red_end

- **`版本`**:`GetStyledLayout` 与全局布局缓存在 `v1.10.1` 强化;有界缓存/强引用契约在 `v1.15.0` 前后定型。

## 图标 Icon(字体字形)

```cpp
enum class Icon : unsigned short { None=0x0000, Add=0xE710, Remove=0xE738, ..., Pin=0xE718, View=0xE890, ... };
inline const std::wstring& IconFontFamily();   // Segoe Fluent Icons → 回退 Segoe MDL2 Assets
inline std::wstring IconGlyph(Icon);           // 码点 → 单字宽字符串
```

###block_red_start
**易错**

- 枚举值**就是字体码点**(无独立映射表)。字体回退**只在首次静态探测**,运行期换系统字体不会重探;个别 Win11 专有字形在两版字体里缺失会显示方框。
###block_red_end

- **`版本`**:`v1.13.0` 起 `Icon` 下沉到 `ZufyUIWidgets.h`,所有 `Label` 派生控件获得 `SetIcon`。
第 5 章

字体与图标

FontSpec、FontManager、Icon

FontSpec

cpp
struct FontSpec {
    std::wstring familyName = L"Segoe UI";
    float size = 14.0f;
    DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
    DWRITE_FONT_STYLE  style  = DWRITE_FONT_STYLE_NORMAL;
    DWRITE_FONT_STRETCH stretch = DWRITE_FONT_STRETCH_NORMAL;
    std::wstring locale = L"en-us";
    bool operator==/!=(...) const;
};

FontManager(单例,文本布局缓存)

cpp
static FontManager& Instance();
IDWriteFactory* GetFactory();
IDWriteTextFormat* GetFormat(const FontSpec&);
bool SetAppFontCollection(IDWriteFontCollection*);   // install once, before formats
ComPtr<IDWriteTextLayout> GetRawLayout(text, fmt, maxW, maxH, noWrap);
ComPtr<IDWriteTextLayout> GetDisplayLayout(origText, fmt, maxW, maxH, noWrap);   // 带省略号
ComPtr<IDWriteTextLayout> GetStyledLayout(text, fmt, w, h, noWrap, hAlign, vAlign, lineSpacing, maxLines);
ComPtr<IDWriteTextLayout> GetStyledDisplayLayout(...);
void CacheDisplayLayout(...); void CacheStyledDisplayLayout(...);
void SetGlobalFont(const FontSpec&);
ZSignal<> GlobalFontChanged;

易错

  • 返回的 layout 是共享只读对象,不要对它 SetTextAlignment/SetLineSpacing/SetTrimming——缓存 key 会与对象不一致。
  • GetFormat 返回的 IDWriteTextFormat* 永不淘汰,请勿修改它。
  • GetFormat 的共享 format 把 ParagraphAlignment 设成了 CENTER。不要直接拿它画多行自绘文本,否则会被垂直居中到高盒外(看起来“没字”);用 GetStyledLayout(..., vAlign) 或自建 format 并设 NEAR。

图标 Icon(字体字形)

cpp
enum class Icon : unsigned short { None=0x0000, Add=0xE710, Remove=0xE738, ..., Pin=0xE718, View=0xE890, ... };
inline const std::wstring& IconFontFamily();   // Segoe Fluent Icons → 回退 Segoe MDL2 Assets
inline std::wstring IconGlyph(Icon);           // 码点 → 单字宽字符串

易错

  • 枚举值就是字体码点(无独立映射表)。字体回退只在首次静态探测,运行期换系统字体不会重探;个别 Win11 专有字形在两版字体里缺失会显示方框。
↑