为自定义模块创建自定义 Twig 模板

02/10/2025, by Ivan

Drupal 8 的总体理念是避免在自定义模块的 PHP 代码中直接生成 HTML。你应该将这些交给 Twig 模板来处理。要在你的模块中创建新的 Twig 模板，请执行以下步骤。

步骤 1：在 .module 文件中定义 hook_theme
如果 [module].module 文件还不存在，请创建它，并添加定义每个 Twig 模板的代码。数组中每个元素的键是你之后调用模板时需要使用的名称。注意不要在文件名中使用连字符。

function test_twig_theme($existing, $type, $theme, $path) {
  return [
    'my_template' => [
      'variables' => ['test_var' => NULL],
    ],
  ];
}

参见 hook_theme() 文档。

步骤 2：调用模板
在返回渲染数组的地方（例如由路由 yml 文件调用的控制器方法，或其他地方），调用 Twig 模板。下面是一个测试模块的示例，它通过模块中的路由 yml 文件调用。

/**
 * @file
 * Contains \Drupal\test_twig\Controller\TestTwigController.
 */
 
namespace Drupal\test_twig\Controller;
 
use Drupal\Core\Controller\ControllerBase;
 
class TestTwigController extends ControllerBase {
  public function content() {
 
    return [
      '#theme' => 'my_template',
      '#test_var' => $this->t('Test Value'),
    ];
 
  }
}

你也可以使用渲染方法来构建输出，如果你需要将其作为代码中其他工作流的一部分：

$renderable = [
  '#theme' => 'my_template',
  '#test_var' => 'test variable',
];
$rendered = \Drupal::service('renderer')->renderPlain($renderable);

请注意，这是一个基础实现，没有使用任何缓存。Render API 概览提供了更多关于如何为其添加缓存的信息。关于缓存需要注意的是：变量名会被缓存，如果你更改了它们（例如将「test_var」改为「my_var」），你需要刷新缓存。

步骤 3：创建 Twig 模板
在模块中，在 templates 文件夹内创建 Twig 模板。文件名应与在 hook_theme() 中定义的名称一致（将下划线替换为连字符）。在此示例中，文件名应为 my-template.html.twig。
以下是测试使用的文件：

<p>Test twig template!</p>
 
<p>test_var: {{ test_var }}</p>

这样做的好处是，如果主题中不存在相应的文件，就会使用模块中定义的模板文件。只需将文件放入你的主题 templates 文件夹，清除缓存（drush cache-rebuild），系统就会读取该文件。

你还可以将文件放入站点主题的任意子文件夹中，以保持良好的组织结构。

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验

为自定义模块创建自定义 Twig 模板

Menu