如何在 Grav 插件中正确获取已处理的模块化页面内容

本文详解在 grav 自定义插件中（如 `onpagesinitialized` 阶段）安全获取模块化页面（modular page）的**已渲染内容**（processed content），解决因 twig 模板路径缺失导致的 `"template 'modular/xxx.html.twig' is not defined"` 错误，并提供可靠、可复用的实现方案。

在 Grav 中，模块化页面（如 /austria/_price-list）的内容需经 Twig 渲染引擎解析后才能输出最终 HTML（例如处理 {% include %}、短代码、Markdown 转义等）。直接调用 $page->content() 仅返回原始 Markdown 或未渲染的 Twig 模板字符串，不会执行模板逻辑或包含其他页面内容——这正是你遇到问题的根本原因：你的模块页中通过 {% include page.template~'.html.twig' %} 动态加载子模板，但插件中未触发完整渲染流程，导致 page.content() 返回的是含 Twig 标签的原始字符串，而非实际 HTML。

要真正获取“已处理内容”，必须模拟 Grav 的页面渲染上下文。以下是推荐做法：

✅ 正确步骤：手动触发 Twig 渲染

public static function createIndexData($file): bool
{
    $pages = self::getPages();
    if (!$pages) return false;

    $grav = Grav::instance();
    $page = $pages->find('/austria/_price-list');
    if (!$page || !$page->published()) {
        return false;
    }

    // 1. 确保主题模板路径可用（关键！）
    $locator = $grav['locator'];
    $themePath = $locator->findResource('theme://templates');
    if ($themePath && !in_array($themePath, $grav['twig']->getLoader()->getPaths())) {
        $grav['twig']->addPath($themePath);
        $grav->fireEvent('onTwigTemplatePaths'); // 触发事件确保扩展生效
    }

    // 2. 获取页面渲染后的 HTML 内容（核心）
    try {
        // 强制设置当前页面上下文，避免模板中 page.find() 失败
        $grav['page'] = $page;

        // 手动渲染：等效于前端访问该页面时的完整处理流程
        $renderedContent = $page->template()->render(['page' => $page]);

        // ✅ 此时 $renderedContent 即为完全处理后的 HTML 字符串
        dump($renderedContent);
        exit();
    } catch (\Twig\Error\LoaderError $e) {
        error_log('Twig template load error: ' . $e->getMessage());
        dump('Template not found or invalid: ' . $e->getMessage());
        exit();
    } catch (\Exception $e) {
        error_log('Rendering failed: ' . $e->getMessage());
        dump('Rendering error: ' . $e->getMessage());
        exit();
    }

    return true;
}

⚠️ 关键注意事项

• 不要硬编码主题路径：原答案中 __DIR__.'/../../../themes/yourtheme/templates' 是脆弱写法，易因插件安装位置变化而失效。应始终使用 $locator->findResource('theme://templates')。
• $page->content() ≠ 渲染后内容：它只返回原始正文（Raw Content），不执行 Twig、不解析 include、不运行短代码。务必改用 $page->template()->render()。
• 上下文依赖：模块页中常依赖 page, uri, config 等全局变量，因此需显式设置 $grav['page'] = $page，否则 page.find() 在插件中会失败。
• 事件触发时机：onPagesInitialized 阶段页面对象已初始化，但 Twig 路径可能尚未完全注册，因此需主动 addPath() 并触发 onTwigTemplatePaths。
• 异常防护：务必包裹 try/catch，模块页模板缺失或语法错误将直接抛出 Twig\Error\LoaderError 或 SyntaxError。

? 补充建议：若只需部分内容（如纯 HTML 片段）

可结合 Twig 环境单独渲染特定模板：

$twig = $grav['twig']->twig();
$template = $twig->load('modular/price-list-global.html.twig');
$html = $template->render(['page' => $page]);

但前提是该模板已存在于 Twig 加载路径中（仍需上述路径配置）。

通过以上方式，你就能在插件中稳定、准确地获取任意模块化页面的真实渲染结果，彻底规避模板未定义、上下文丢失等问题。