如何在Drupal 9中用自定义模块覆盖form.html.twig模板

按以下步骤逐一操作，确保模块自带模板替代默认模板：

• 1. 在自定义表单类中指定主题钩子
  在表单类的buildForm()方法里，为表单数组添加#theme属性，定义自定义主题钩子名称：

  public function buildForm(array $form, FormStateInterface $form_state) {
    // 表单元素定义逻辑...
  
    // 关键：绑定自定义主题钩子
    $form['#theme'] = 'my_custom_form';
  
    return $form;
  }
  

  注意：钩子名称使用下划线分隔（如my_custom_form），后续模板文件名需转成短横线分隔格式。

• 2. 在模块内创建模板文件
  在你的模块目录下新建templates文件夹，放入自定义模板文件，命名为my-custom-form.html.twig（下划线转短横线）。模板示例：

  {# 自定义表单模板 #}
  <div class="custom-form-wrapper">
    {{ form|without('form_build_id', 'form_token', 'form_id') }}
  </div>
  

• 3. 注册主题钩子（实现hook_theme）
  在模块的.module文件中，实现hook_theme()来注册主题钩子，明确模板路径：

  function mymodule_theme($existing, $type, $theme, $path) {
    return [
      'my_custom_form' => [
        'render element' => 'form', // 告知Drupal这是表单类主题钩子
        'template' => 'my-custom-form', // 模板文件名（不含.html.twig后缀）
        'path' => $path . '/templates', // 模板所在的相对路径
      ],
    ];
  }
  

  替换mymodule为你的实际模块名称。

• 4. 强制清除Drupal缓存
  这是极易忽略的关键步骤，执行以下操作之一：

  • 后台操作：配置 > 开发 > 性能 > 清除所有缓存
  • Drush命令：drush cr

• 5. 验证模板是否被识别
  开启Twig调试模式确认模板加载状态：

  1. 编辑sites/default/services.yml，设置twig.config.debug: true
  2. 清除缓存后，查看页面源代码，寻找类似注释：

     <!-- THEME DEBUG -->
     <!-- CALL: theme('my_custom_form') -->
     <!-- FILE NAME SUGGESTIONS:
          * my-custom-form.html.twig
          x form.html.twig
     -->
     

     若my-custom-form.html.twig被标记为x，说明已生效；若未出现该条目，检查hook_theme注册逻辑是否有误。

• 6. 检查文件权限
  确保templates文件夹权限为755，模板文件权限为644，避免服务器无法读取模板文件。

内容的提问来源于stack exchange，提问作者Gilbert M.