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 文章应用菜单

{
    "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"
        }
    ]
}

解析：

顶级菜单：
- id: 唯一标识符为 article。
- caption: 显示名称为“文章”。
- icon: 使用图标 si si-grid。
- sort: 排序值为 2。
子菜单项：
- “文章配置”：链接到 /article/config，图标为 cog。
- 分隔线：caption 为 "-"。
- “更新栏目缓存”：链接到 /articleCategory/cache，图标为 sync，并启用了 AJAX 功能（ui: cms:ui:ajax）。

2.2 系统配置菜单

{
    "id": "settings",
    "children": [
        {
            "id": "system",
            "caption": "系统设置",
            "href": "/config/system",
            "icon": "cog",
            "sort": "-999",
            "children-show": false,
            "children": [
                {
                    "caption": "调试",
                    "href": "/config/system/debug",
                    "icon": "bugs"
                }
            ]
        }
    ]
}

解析：

顶级菜单：
- id: 唯一标识符为 settings。
子菜单项：
- “系统设置”：链接到 /config/system，图标为 cog，排序值为 -999（优先级最高）。
- children-show: 设置为 false，表示默认不展开子菜单。
- 子菜单项“调试”：链接到 /config/system/debug，图标为 bugs。

三、完整示例

以下是一个完整的菜单配置示例，包含动态子菜单和权限控制的扩展字段：

{
    "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"
        }
    ]
}

特点：

动态子菜单：通过 children 字段调用 ExampleAdmincp::getDynamicMenu 方法生成子菜单。
分隔线：用于分隔不同功能模块。
排序：通过 sort 字段控制菜单项的顺序。

四、开发与扩展

4.1 如何新增菜单项

在 JSON 配置中添加新的菜单项，例如：

{
    "caption": "新功能",
    "href": "/new-feature",
    "icon": "star",
    "sort": "5"
}

确保 href 对应的路由已注册。
如果需要动态生成子菜单，设置 children 字段，并实现对应的 PHP 方法。

4.2 自定义图标

默认图标库为 Font Awesome，可以通过修改 icon 字段使用其他图标库。
支持自定义图标类名，例如 fa-icon。

4.3 动态菜单

使用 children 字段动态生成子菜单。
实现类似 ConfigAdmincp::getSiteMemu 的方法，返回子菜单数组。

五、注意事项

排序规则：sort 值越小，菜单项越靠前。
分隔线：分隔线不能单独存在，需与其他菜单项配合使用。
动态属性：确保 data-* 属性符合 HTML 规范。
性能优化：对于大型菜单，建议使用懒加载或异步加载子菜单。

六、总结

通过本文档，开发人员可以快速掌握 iCMS 后台菜单的配置和开发方法。合理利用 JSON 配置和扩展字段，能够高效实现复杂的菜单结构，满足不同应用场景的需求。