本文介绍如何在 Sulu CMS 中为每个页面配置预设图标，并在 Headless 导航 API 响应中自动注入 navigationIcon 字段，避免用户随意上传图标，同时绕过 excerpt 和 media selection 的权限与约束限制。
本文介绍如何在 sulu cms 中为每个页面配置预设图标，并在 headless 导航 api 响应中自动注入 `navigationicon` 字段，避免用户随意上传图标，同时绕过 excerpt 和 media selection 的权限与约束限制。
在 Sulu CMS 构建的 Headless 站点中，常需为导航菜单项（如首页、关于我们、服务等）展示统一风格的 SVG 或图标字体标识。但 Sulu 默认不支持在导航上下文（navigation context）中直接暴露自定义字段——尤其是当该字段需严格限定为预设图标集（而非任意媒体上传）时，标准的 excerpt 或 single_media_selection 字段均无法满足「可控、可复用、可序列化到导航响应」三重要求。
核心挑战在于：
- excerpt 区域虽支持扩展字段，但其数据不会自动包含在 sulu_headless.api.navigation API 响应中；
- single_media_selection 无法限制为指定系统媒体集合（如 icons），存在内容治理风险；
- 页面结构（Structure）本身不支持运行时动态注入字段至 Headless 导航序列化结果。
✅ 推荐方案：利用 Symfony 事件监听器劫持导航 API 响应
通过监听 kernel.response 事件，在 sulu_headless.api.navigation 路由返回前，主动解析原始 JSON 响应，按 UUID 查找对应页面文档，提取已存储于 Document Extension 中的图标配置，并注入新字段（如 navigationIcon）。该方式零侵入核心逻辑，完全兼容 Sulu 文档生命周期与 HeadlessBundle 架构。
步骤一：定义页面扩展字段（Extension）
首先，为页面模板（如 default.xml）添加自定义 extension 字段，使用 select 类型绑定预设图标选项（推荐使用 choice + options 避免自由输入）：
<!-- config/templates/pages/default.xml -->
<property name="navigation" type="extension">
<meta>
<title lang="en">Navigation Settings</title>
</meta>
<params>
<param name="view" value="navigation_settings"/>
</params>
<children>
<property name="icon" type="select">
<meta>
<title lang="en">Navigation Icon</title>
</meta>
<params>
<param name="options" type="collection">
<param name="home" value="home"/>
<param name="about" value="about"/>
<param name="services" value="services"/>
<param name="contact" value="contact"/>
</param>
</params>
</property>
</children>
</property>✅ 优势：选项受控、无上传风险、前端可直接映射为 CSS class 或 SVG sprite ID。
步骤二：注册事件监听器
创建监听器类（如 App\EventListener\NavigationListener），在 kernel.response 事件中拦截导航 API 响应，并注入图标数据：
<?php declare(strict_types=1);
namespace App\EventListener;
use Sulu\Component\DocumentManager\DocumentManagerInterface;
use Sulu\Component\DocumentManager\Exception\DocumentManagerException;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
class NavigationListener
{
public function __construct(private DocumentManagerInterface $documentManager)
{
}
public function onKernelResponse(ResponseEvent $event): void
{
$request = $event->getRequest();
// 仅处理 Headless 导航 API
if ($request->attributes->get('_route') !== 'sulu_headless.api.navigation') {
return;
}
$response = $event->getResponse();
$content = $response->getContent();
// 安全解析 JSON（建议加 try-catch）
$data = json_decode($content, true);
if (json_last_error() !== JSON_ERROR_NONE || !isset($data['_embedded']['items'])) {
return;
}
// 遍历导航项，注入 navigationIcon
foreach ($data['_embedded']['items'] as &$item) {
if (!isset($item['uuid'])) {
continue;
}
try {
$doc = $this->documentManager->find($item['uuid']);
$extensions = $doc->getExtensionsData()->toArray();
if (isset($extensions['navigation']['icon'])) {
$item['navigationIcon'] = $extensions['navigation']['icon'];
}
} catch (DocumentManagerException $e) {
// 日志记录异常，但不中断响应
error_log(sprintf('Failed to load extension for page %s: %s', $item['uuid'], $e->getMessage()));
}
}
$response->setContent(json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));
}
}步骤三：注册服务并启用监听器
在 config/services.yaml 中注册监听器为事件订阅者：
# config/services.yaml
App\EventListener\NavigationListener:
tags:
- { name: 'kernel.event_listener', event: 'kernel.response', method: 'onKernelResponse' }⚠️ 注意事项：
- 该监听器仅影响 sulu_headless.api.navigation 路由，不影响其他 API（如内容详情页）；
- 若需支持多层级导航（非仅 top-level），需递归处理 children 数组；
- 生产环境建议添加缓存层（如 Doctrine 缓存 DocumentInterface 实例），避免高频文档查询；
- 图标值（如 "home"）应在前端约定渲染逻辑（例如 ）。
总结
本方案以最小侵入性实现了「预设图标 + 导航上下文注入」的核心需求：
? 安全可控：图标来源为配置化选项，杜绝任意上传；
? 结构清晰：Extension 字段与页面模板强绑定，语义明确；
? API 就绪：无需修改前端调用逻辑，navigationIcon 直接可用；
? 可扩展：后续可轻松扩展为图标 ID → SVG 内联、CDN URL 映射等高级策略。
未来若 Sulu HeadlessBundle 支持 extension_fields 白名单配置或导航序列化钩子，此监听器可平滑迁移为声明式配置——当前阶段，它是最稳健、最符合 Sulu 架构哲学的实践路径。
