JavaFX CSS @font-face 错误全面分析 loadStylesheetUnPrivileged / reportException

JavaFx 支持样式表，并且支持@font-face加载指定字体。官方提供的示例代码如下：

@font-face { font-family: 'sample'; font-style: normal; font-weight: normal; src: local('sample'), url('http://font.samples/resources/sample.ttf';) format('truetype'); }

但是这段代码极具误导性，而且很容易出现如下错误：

// 错误1 com.sun.javafx.css.StyleManager loadStylesheetUnPrivileged INFO:Could not load @font-face font [file:/D:/JOYZL%20SCADA/scada/trunk/brace/target/classes/com/joyzl/brace/window/HUATENS.ttf] // 错误2 javafx.css.CssParser reportException 警告: Please report java.lang.NullPointerException at:

其次的错误是字体加载成功了，但是却没有生效。

原因为：

1.StyleManager使用Font.loadFont()这个方法不会对URL编码的百分号字符执行解码，那么如果路径中存在空格，会导致加载失败。由于CSS中的路径URL是样式解析器通过getResource获得的，因此我们没有可用的干预手段，折中的方案是，JavaFx 程序启动时通过代码加载字体，我们需要将%20替换为 空格。

2.src:url("/sample.ttf")的URL不能出现‘/’开头的根目录表示形式，字体文件定位相对于CSS文件的位置，不应使用绝对路径，请改为相对路径。如果路径解析失败将收到reportException异常。

3. 字体加载成功（未提示异常），但是字体依然没有生效，是为字体名称匹配失败，这会由三个原因导致：
A.@font-face中指定的font-family是无效的，JavaFx 不会使用这个指令，@font-face中除了src:url之外的指令都被忽略，包括 url 后面的format，只能使用字体默认名称。
B. 字体默认名称，在不同的操作系统可能不一样，以“阿里巴巴普惠体”字体测试，在简体中文 Windows 11 中字体名称为'阿里巴巴普惠体 3.0 45 Light'而在 Debian 12 中字体名称为'Alibaba PuHuiTi 3.0 45 Light'，并且-fx-fongt-family指令不支持多个字体名称，是不是要疯了。
C. 样式表中的字体名称必须有引号包围，否则依然会匹配失败。

-fx-font-family: Monserrat; /*无效*/ -fx-font-family: 'Monserrat';

JavaFX CSS Reference Guide

Introduction to FXML | JavaFX 24

以上是 我们在编译 JOYZL SCADA Station 和 R11 的 Windows 和 Linux 两个版本时，所遇到的 JavaFx 字体问题的分析和解决，希望 JavaFx 持续改进。 JOYZL SCADA Station 是完全国产化的 数据采集与监测控制软件，主要应用于工业数据采集监控。