ForNeVeR/xaml-math · 上手攻略

• 仓库：ForNeVeR/xaml-math
• 链接：https://github.com/ForNeVeR/xaml-math
• 分类：dotnet / math-rendering
• 作者：spark
• 更新：2026-08-26

1. 是什么

XAML-Math（前身 WPF-Math，2023 年加入 Avalonia 支持后改名）是一组 .NET 库，用于在 WPF 和 Avalonia XAML 应用中以 LaTeX 排版风格渲染数学公式。它不是 LaTeX 编译器，也不依赖外部 TeX 发行版——纯托管代码解析 \frac、\sqrt、\begin{matrix}...\end{matrix} 这类 LaTeX 子集，直接输出矢量或位图。

历史血统：源自 Java 世界的 JMathTeX（2004-2007 Universiteit Gent），由 Alex Regueiro 移植到 .NET（WPF-TeX → WPF-Math），2011-2017 年无人维护，2017 年由 ForNeVeR 复活并持续维护至今。

2. 解决什么问题

典型场景：

• 在 WPF / Avalonia 桌面应用里嵌入 LaTeX 公式（数学编辑器、电子教科书、报表、CAD/CAE 工具）。
• 想生成 PNG/Bitmap 离线渲染公式（服务端批量导出、邮件报表、PDF 占位）。
• 不想拉一个完整的 LaTeX 发行版（MiKTeX/TeX Live 几百 MB+）进部署链路。

XAML-Math 的覆盖范围（README 直接列出）：

• WPF：.NET Framework 4.6.2+ / .NET 8+
• Avalonia：.NET Framework 4.6.2+ / .NET Standard 2.0+ / .NET 8+
• 与 UI 无关的纯渲染部分发布为 NuGet 包 XamlMath.Shared

3. 快速安装

3.1 NuGet（应用开发者）

# WPF 项目
dotnet add package WpfMath

# Avalonia 项目
dotnet add package AvaloniaMath

# 仅渲染（不带 XAML 控件）
dotnet add package XamlMath.Shared

⚠️ 包名可能因版本迭代变动，建议在 nuget.org 搜索 "XamlMath" 确认当前最新版。

3.2 从源码构建（贡献者）

需要 .NET SDK 8.0 或更新：

git clone https://github.com/ForNeVeR/xaml-math
cd xaml-math

dotnet build XamlMath.All.sln --configuration Release
dotnet test  XamlMath.All.sln
# 批准测试结果差异（如果有）
pwsh scripts/approve-all.ps1
# 打 NuGet 包
dotnet pack XamlMath.All.sln --configuration Release

4. 核心用法

4.1 静态公式（XAML 控件，最简方式）

WPF：

<Window …
        xmlns:controls="clr-namespace:WpfMath.Controls;assembly=WpfMath">
    <controls:FormulaControl Formula="\left(x^2 + 2 \cdot x + 2\right) = 0" />
</Window>

Avalonia：

<Window …
        xmlns:controls="clr-namespace:AvaloniaMath.Controls;assembly=AvaloniaMath">
    <controls:FormulaBlock Formula="\left(x^2 + 2 \cdot x + 2\right) = 0" />
</Window>

更完整的示例（数据绑定 / 进阶概念）见 src/WpfMath.Example 目录。

4.2 渲染到 PNG（一行扩展方法）

using System;
using System.IO;
using WpfMath.Parsers;
using WpfMath;
using XamlMath.Exceptions;

const string latex   = @"\frac{2+2}{2}";
const string fileName = @"T:\Temp\formula.png";

try
{
    var parser  = WpfTeXFormulaParser.Instance;
    var formula = parser.Parse(latex);
    var pngBytes = formula.RenderToPng(20.0, 0.0, 0.0, "Arial");
    File.WriteAllBytes(fileName, pngBytes);
}
catch (TexException e)
{
    Console.Error.WriteLine("Error when parsing formula: " + e.Message);
}

parser.Parse 在公式不合法时会抛 XamlMath.Exceptions.TexException。

4.3 完全控制位图渲染（带环境参数）

如果想自己控制字号、字体、像素格式，用 WpfTeXEnvironment + RenderToBitmap：

using System;
using System.IO;
using System.Windows.Media.Imaging;
using WpfMath.Parsers;
using WpfMath.Rendering;
using XamlMath;

const string latex   = @"\frac{2+2}{2}";
const string fileName = @"T:\Temp\formula.png";

var parser     = WpfTeXFormulaParser.Instance;
var formula    = parser.Parse(latex);
var environment = WpfTeXEnvironment.Create(TexStyle.Display, 20.0, "Arial");
var bitmap     = formula.RenderToBitmap(environment);

Console.WriteLine($"Image width: {bitmap.Width}");
Console.WriteLine($"Image height: {bitmap.Height}");

var encoder = new PngBitmapEncoder();
encoder.Frames.Add(BitmapFrame.Create(bitmap));
using var target = new FileStream(fileName, FileMode.Create);
encoder.Save(target);
Console.WriteLine($"File saved to {fileName}");

4.4 自定义渲染后端

需要切换到 SkiaSharp / 其他引擎时，实现 IElementRenderer 并传给 TeXFormulaExtensions::RenderTo——这是给重度集成者留的扩展点。

4.5 文档索引（README 直链）

• Changelog
• Color support in XAML-Math
• Matrices and Matrix-Like Constructs
• Environments (\begin and \end)
• How to improve blurred formulas
• How to prepare DefaultTexFont.xml from the font file
• Licensing history

5. 典型适用场景

• 桌面数学编辑器 / 电子教材：WPF + Avalonia 双框架，覆盖 Windows 与跨平台 UI。
• 报表 / 邮件 / PDF 后端：服务端调 RenderToPng 批量生成公式图片（不需要完整 LaTeX）。
• 科学计算工具：用纯 .NET 渲染避免引入几百 MB 的 TeX 发行版。
• Avalonia 跨平台桌面应用：唯一原生支持 Avalonia 的 LaTeX 风格渲染方案之一。
• WPF 老项目现代化：原 WPF-Math 用户迁移到 XAML-Math（API 兼容 + NuGet 包统一）。

6. 坑与注意

• ⚠️ 不是完整 LaTeX：只支持 LaTeX 数学模式子集（amsmath 风格命令为主），不支持 \documentclass、文档模式、宏包扩展。
• ⚠️ 字体限制：默认使用 Computer Modern 系列（cmex10、cmmi10、cmr10、cmsy10、cmtt10），换字体需要按 docs/prepare-font.md 自己准备 DefaultTexFont.xml。
• ⚠️ 部分环境依赖：某些高级环境（align*、cases 等）行为可能与真实 LaTeX 不一致，遇到边缘情况查 docs/environments.md。
• ⚠️ 模糊字体问题：高 DPI 下可能出现模糊，README 给了专门文档，但未独立核验当前修复状态。
• ⚠️ NuGet 包名历史：原 WPF-Math 时代包名与新 XamlMath.* 时代包名不完全一致，搜 NuGet 时建议以 XamlMath 关键词检索最新。
• ⚠️ Windows / Linux 行为差：WPF 仅 Windows；Avalonia 才能跑 Linux/macOS，跨平台部署前要明确目标框架。
• ⚠️ 字体许可分两类：cm* 系字体用 Knuth License，jlm_msam10.ttf（源自 JLaTeXMath）用 OFL——重新分发时要按 fonts/LICENSES.md 附许可。

7. 与同类对比

CSharpMath / KaTeX / MathJax 数据来自 NuGet 与官方网站摘要，未深入核验最新版本细节。

8. 一句话推荐

要在 .NET 桌面应用里渲染 LaTeX 公式，XAML-Math 是当下最稳的选择——双框架覆盖、纯托管无需 TeX 发行版、十年维护历史。

9. 不确定处 / 待核验

• ⚠️ 当前 NuGet 包最新版本号未在 README 中显式给出，建议直接到 nuget.org/packages/XamlMath.Shared 查。
• ⚠️ "Stars ~720" 来自工作队列卡片（与 W34 持平），未在 GitHub 主页直接 fetch 校验。
• ⚠️ 高 DPI 模糊问题的当前修复状态 README 未给版本号锚定，建议实测前先读 docs/blurred-text-issue.md。
• ⚠️ WpfTeXEnvironment.Create(TexStyle.Display, ...) 中 TexStyle.Display 枚举来自 WpfMath 命名空间，未独立查 NuGet 包元数据确认 8.0+ SDK 兼容性。
• ⚠️ 与上游 JMathTeX 的 GPL→MIT 重授权说明来自仓库 docs/licensing-history.md，本指南未独立比对原始邮件授权记录。