TYPO3 v10 后台仪表盘如何注册扩展名称并正确显示自定义图标

图标纯黑问题修复 #

• 原因：TYPO3 10后台会自动为模块图标应用主题适配的填充样式，你使用的SVG图标自带固定fill="#000"填充属性，导致样式覆盖后显示纯黑；也可能是图标路径与实际扩展路径不匹配。
• 修复操作：
  • 打开SVG图标文件，删除所有<svg>、<path>标签上写死的fill属性，仅保留路径代码即可，TYPO3会自动适配主题色填充
  • 确认你代码中配置的图标路径EXT:gpi_localizer/Resources/Public/Icons/Extension.svg与你当前开发的扩展key一致，如果不一致替换为对应扩展key
  • 建议将SVG图标尺寸调整为1616或2424，符合TYPO3后台图标规范

扩展名称不显示问题修复 #

• 原因：你配置的labels对应的XLF翻译文件缺少模块必须的翻译标签，或者XLF文件存在语法错误。
• 修复操作：
  • 打开路径对应的翻译文件EXT:gpi_localizer/Resources/Private/Language/locallang.xlf，添加以下两个翻译项：

<trans-unit id="mlang_tabs_tab">
  <source>my_extension</source>
</trans-unit>
<trans-unit id="mlang_labels_tablabel">
  <source>自定义扩展管理</source>
</trans-unit>

• 检查XLF文件头部格式是否符合规范，无语法错误
• 清空TYPO3后台全部缓存，重新登录即可显示正常名称

补充提示 #

你当前代码中的routeTarget指向第三方扩展l10nmgr的控制器，如果你是开发自定义扩展，需要替换为你自己编写的控制器类和对应方法。
TYPO3 10及以上版本更推荐在扩展的Configuration/Backend/Modules.php中注册模块，性能和可维护性更好，参考写法：

return [
    'web_MyExt' => [
        'parent' => 'web',
        'position' => ['after' => 'web_info'],
        'access' => 'user,group',
        'workspaces' => 'live',
        'path' => '/module/web/MyExt',
        'iconIdentifier' => 'extension-myext-icon',
        'labels' => 'LLL:EXT:gpi_localizer/Resources/Private/Language/locallang.xlf',
        'extensionName' => 'GpiLocalizer',
        'controllerActions' => [
            \YourVendor\GpiLocalizer\Controller\Manager::class => [
                'main'
            ],
        ],
    ],
];

如果使用上述写法需要在扩展的Configuration/Icons.php中注册图标：

return [
    'extension-myext-icon' => [
        'provider' => \TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider::class,
        'source' => 'EXT:gpi_localizer/Resources/Public/Icons/Extension.svg',
    ],
];

内容的提问来源于stack exchange，提问作者Mohamed Mazen