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

土族程序员2025-07-31 18:53

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

css 复制代码

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

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

css 复制代码

// 错误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:

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

原因为：

StyleManager 使用 Font.loadFont() 这个方法不会对URL编码的百分号字符执行解码，那么如果路径中存在空格，会导致加载失败。由于CSS中的路径URL是样式解析器通过 getResource 获得的，因此我们没有可用的干预手段，折中的方案是，JavaFx 程序启动时通过代码加载字体，我们需要将 %20 替换为空格。
src:url("/sample.ttf") 的URL不能出现 '/' 开头的根目录表示形式，字体文件定位相对于CSS文件的位置，不应使用绝对路径，请改为相对路径。如果路径解析失败将收到 reportException 异常。
字体加载成功（未提示异常），但是字体依然没有生效，是为字体名称匹配失败，这会由三个原因导致：

　　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. 样式表中的字体名称必须有引号包围，否则依然会匹配失败。

css 复制代码

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

JavaFX CSS Reference Guide

Introduction to FXML | JavaFX 24