TYPO3 11中如何在不强制依赖Dashboard的情况下注册仪表盘widget

核心逻辑是让Widget相关服务仅在Dashboard扩展已安装的场景下才被注册加载，具体操作步骤如下：

• 第一步：调整扩展服务自动扫描配置
  修改Configuration/Services.yaml，将Widget类所在目录排除在全局自动扫描范围外，避免未装Dashboard扩展时系统自动扫描到Widget类，触发依赖接口不存在的报错：

  services:
    _defaults:
      autowire: true
      autoconfigure: true
      public: false
  
    Vendor\YourExtension\:
      resource: '../Classes/*'
      # 新增排除规则，将Widget目录排除在全局自动扫描之外
      exclude: '../Classes/Dashboard/Widget/*'
  

• 第二步：按条件注册Widget服务
  两种方案二选一即可：
  • 方案1：用YAML条件注册
    直接在Configuration/Services.yaml中补充带条件的Widget注册规则，仅当WidgetInterface存在时才生效：

    # 接上述基础服务配置
    Vendor\YourExtension\Dashboard\Widget\YourCustomWidget:
      tags:
        - name: dashboard.widget
          identifier: 'your_extension_custom_widget'
          widgetGroups: 'general'
      # 仅当Dashboard扩展的WidgetInterface存在时才注册该服务
      when@available:
        class: TYPO3\CMS\Dashboard\Widgets\WidgetInterface
    

  • 方案2：用PHP服务配置注册（更灵活）
    新建Configuration/Services.php文件，通过PHP代码判断接口是否存在后再注册服务：

    <?php
    declare(strict_types=1);
    
    use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
    use TYPO3\CMS\Dashboard\Widgets\WidgetInterface;
    use Vendor\YourExtension\Dashboard\Widget\YourCustomWidget;
    
    return static function (ContainerConfigurator $configurator): void {
        $services = $configurator->services();
        if (interface_exists(WidgetInterface::class)) {
            $services->set(YourCustomWidget::class)
                ->tag('dashboard.widget', [
                    'identifier' => 'your_extension_custom_widget',
                    'widgetGroups' => 'general'
                ]);
        }
    };
    

• 第三步：确认composer.json配置
  保持你原有的suggests配置即可，不要将typo3/cms-dashboard放入require节点：

  {
    "suggest": {
      "typo3/cms-dashboard": "安装后可使用本扩展提供的自定义Dashboard小部件"
    }
  }
  

完成以上配置后，未安装Dashboard扩展的环境下不会加载Widget相关的任何代码，不会抛出接口不存在的报错，安装后自动生效。

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