本文介绍如何在 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。
步骤二：注册事件监听器
创建监听器类（如 AppEventListenerNavigationListener），在 kernel.response 事件中拦截导航 API 响应，并注入图标数据：
<?php declare(strict_types=1); namespace AppEventListener; use SuluComponentDocumentManagerDocumentManagerInterface; use SuluComponentDocumentManagerExceptionDocumentManagerException; use SymfonyComponentHttpKernelEventResponseEvent; 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 AppEventListenerNavigationListener: 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 架构哲学的实践路径。