Qooxdoo 7.6适配新fonts配置时，如何保留带@的图标路径？

问题背景 #

在Qooxdoo 7.6项目中，按照官方指引将废弃的provides.webfonts替换为provides.fonts后，功能正常，但所有图标路径必须从@FontAwesome6Regular/lock-open/16修改为FontAwesome6Regular/lock-open/16。项目中存在数百处此类引用，不想批量修改代码，尝试将字体ID改为@FontAwesome6Regular并同步更新@usefont声明未生效，寻求无需修改图标路径的解决方案。

现有配置 #

原Manifest.json（废弃的webfonts配置） #

{
  "info": {
    ...
  },
  "provides": {
   ...
    "webfonts": [
      {
        "name": "FontAwesome6Regular",
        "defaultSize": 16,
        "comparisonString": "\\u30\\u31",
        "mapping": "iconfont/fontawesome6/fa-regular.map",
        "resources": [
          "iconfont/fontawesome6/fa-regular-400.woff2"
        ]
      }
    ]
  },
   ...
  "$schema": "https://qooxdoo.org/schema/Manifest-1-0-0.json"
}

修改后的配置（使用fonts） #

源代码注释

@asset(iconfont/*)
@usefont(FontAwesome6Regular)

修改后的Manifest.json fonts配置

"fonts": {
  "FontAwesome6Regular": {
    "family": [
      "FontAwesome6Regular"
    ],
    "defaultSize": 16,
    "comparisonString": "\\u30\\u31",
    "mapping": "iconfont/fontawesome6/fa-regular.map",
    "fontFaces": [
      {
        "fontFamily": "FontAwesome6Regular",
        "paths": [
          "iconfont/fontawesome6/fa-regular-400.woff2"
        ]
      }
    ]
  }
}

解决方案 #

方案1：在Manifest.json中配置字体别名 #

Qooxdoo 7.x的provides.fonts支持为字体配置aliases字段，直接将带@前缀的名称设为字体别名，无需修改任何代码：

修改Manifest.json中的fonts配置，添加aliases属性：

"fonts": {
  "FontAwesome6Regular": {
    "family": ["FontAwesome6Regular"],
    "defaultSize": 16,
    "comparisonString": "\\u30\\u31",
    "mapping": "iconfont/fontawesome6/fa-regular.map",
    "fontFaces": [
      {
        "fontFamily": "FontAwesome6Regular",
        "paths": ["iconfont/fontawesome6/fa-regular-400.woff2"]
      }
    ],
    "aliases": ["@FontAwesome6Regular"]
  }
}

如果有其他字体（如FontAwesome6Solid、FontAwesome6Brands等），同理在对应字体配置中添加带@的别名即可。

方案2：在应用初始化时添加图标别名映射 #

如果Manifest的aliases配置不生效，可在应用入口类的main方法中，通过图标管理器手动注册别名：

main() {
  super.main();
  
  // 注册带@前缀的字体图标别名
  const iconManager = qx.theme.icon.Icon.getInstance();
  iconManager.addAlias("@FontAwesome6Regular", "FontAwesome6Regular");
  // 其他字体依次添加
  // iconManager.addAlias("@FontAwesome6Solid", "FontAwesome6Solid");
  // iconManager.addAlias("@FontAwesome6Brands", "FontAwesome6Brands");
  
  // 后续应用初始化代码...
}

验证方法 #

修改配置后重新编译项目，检查原有使用@FontAwesome6Regular/lock-open/16的按钮及其他组件是否正常显示图标，无需修改任何图标路径代码。

内容的提问来源于stack exchange，提问作者Jaejin Jang