iCMS 后台菜单配置与开发指南

## 概述 本文档旨在为开发人员提供清晰的指导，以便快速理解和配置 iCMS 系统中的后台菜单。文档基于提供的 JSON 配置示例，详细说明了菜单的结构、字段含义以及如何扩展和自定义菜单。 --- ## 一、菜单配置结构 ### 1.1 基本结构 菜单配置采用 JSON 格式，每个菜单项是一个对象，包含以下常见字段： | 字段名 | 类型 | 描述 | | ---------- | ------- | ------------------------------------------------------------------- | | `id` | String | 菜单项的唯一标识符（可选）。如果未设置，系统会根据`href` 自动生成。 | | `caption` | String | 菜单项的显示名称。支持多语言，可通过`Lang::get()` 获取翻译。 | | `icon` | String | 菜单项的图标类名，默认使用 Font Awesome 或自定义图标库。 | | `href` | String | 菜单项的链接地址。如果是子菜单，可以省略。 | | `children` | Array | 子菜单项数组，用于构建多级菜单。 | | `sort` | Integer | 排序值，数值越小越靠前。 | | `ui` | String | 自定义 UI 属性，例如`cms:ui:ajax`。 | | `menuOnly` | Boolean | 是否仅在菜单中显示，不作为实际链接（可选）。 | ### 1.2 特殊字段 - **分隔符**：当 `caption` 的值为 `"-"` 时，表示一个分隔线。 - **动态子菜单**：通过 `childrentest` 字段指定动态生成子菜单的方法，例如 `ConfigAdmincp::getSiteMemu`。 --- ## 二、JSON 示例解析 ### 2.1 文章应用菜单 ```json { "id": "article", "sort": "2", "caption": "文章", "icon": "si si-grid", "children": [ { "caption": "文章配置", "href": "/article/config", "icon": "cog" }, { "caption": "-" }, { "caption": "更新栏目缓存", "href": "/articleCategory/cache", "icon": "sync", "ui": "cms:ui:ajax" } ] } ``` #### 解析： 1. **顶级菜单**： - `id`: 唯一标识符为 `article`。 - `caption`: 显示名称为“文章”。 - `icon`: 使用图标 `si si-grid`。 - `sort`: 排序值为 `2`。 2. **子菜单项**： - “文章配置”：链接到 `/article/config`，图标为 `cog`。 - 分隔线：`caption` 为 `"-"`。 - “更新栏目缓存”：链接到 `/articleCategory/cache`，图标为 `sync`，并启用了 AJAX 功能（`ui: cms:ui:ajax`）。 --- ### 2.2 系统配置菜单 ```json { "id": "settings", "children": [ { "id": "system", "caption": "系统设置", "href": "/config/system", "icon": "cog", "sort": "-999", "children-show": false, "children": [ { "caption": "调试", "href": "/config/system/debug", "icon": "bugs" } ] } ] } ``` #### 解析： 1. **顶级菜单**： - `id`: 唯一标识符为 `settings`。 2. **子菜单项**： - “系统设置”：链接到 `/config/system`，图标为 `cog`，排序值为 `-999`（优先级最高）。 - `children-show`: 设置为 `false`，表示默认不展开子菜单。 - 子菜单项“调试”：链接到 `/config/system/debug`，图标为 `bugs`。 --- ## 三、完整示例 以下是一个完整的菜单配置示例，包含动态子菜单和权限控制的扩展字段： ```json { "id": "example", "sort": "3", "caption": "示例应用", "icon": "fa fa-cube", "children": [ { "caption": "基本功能", "href": "/example/basic", "icon": "wrench", "sort": "1" }, { "caption": "-" }, { "caption": "高级功能", "href": "/example/advanced", "icon": "gear", "sort": "2", "children": [ { "caption": "子功能1", "href": "/example/advanced/sub1", "icon": "circle" }, { "caption": "子功能2", "href": "/example/advanced/sub2", "icon": "circle" } ] }, { "caption": "动态菜单", "href": "/example/dynamic", "icon": "refresh", "children": "ExampleAdmincp::getDynamicMenu" } ] } ``` #### 特点： 1. **动态子菜单**：通过 `children` 字段调用 `ExampleAdmincp::getDynamicMenu` 方法生成子菜单。 2. **分隔线**：用于分隔不同功能模块。 3. **排序**：通过 `sort` 字段控制菜单项的顺序。 --- ## 四、开发与扩展 ### 4.1 如何新增菜单项 1. 在 JSON 配置中添加新的菜单项，例如： ```json { "caption": "新功能", "href": "/new-feature", "icon": "star", "sort": "5" } ``` 2. 确保 `href` 对应的路由已注册。 3. 如果需要动态生成子菜单，设置 `children` 字段，并实现对应的 PHP 方法。 ### 4.2 自定义图标 - 默认图标库为 Font Awesome，可以通过修改 `icon` 字段使用其他图标库。 - 支持自定义图标类名，例如 `fa-icon`。 ### 4.3 动态菜单 - 使用 `children` 字段动态生成子菜单。 - 实现类似 `ConfigAdmincp::getSiteMemu` 的方法，返回子菜单数组。 --- ## 五、注意事项 1. **排序规则**：`sort` 值越小，菜单项越靠前。 2. **分隔线**：分隔线不能单独存在，需与其他菜单项配合使用。 3. **动态属性**：确保 `data-*` 属性符合 HTML 规范。 4. **性能优化**：对于大型菜单，建议使用懒加载或异步加载子菜单。 --- ## 六、总结 通过本文档，开发人员可以快速掌握 iCMS 后台菜单的配置和开发方法。合理利用 JSON 配置和扩展字段，能够高效实现复杂的菜单结构，满足不同应用场景的需求。