bricks/aidocs/menu.md

bricks.Menu 技术文档

本文档为 bricks.Menu 类的详细说明，基于其继承自 bricks.VBox 的结构和功能设计。

---

概述

bricks.Menu 是一个用于构建可交互菜单界面组件的类，继承自 bricks.VBox。它支持嵌套子菜单、动态加载远程子菜单内容，并能响应菜单项点击事件以打开新窗口或更新目标组件内容。

该组件适用于构建侧边栏菜单、导航菜单或任何树形结构的交互式 UI。

---

继承关系

• 父类: bricks.VBox
• 类型: 自定义 UI 组件类（Class-based）

---

构造函数

constructor(options)

参数

参数名	类型	说明
options	Object	配置选项对象，继承自 VBox 并扩展以下属性

options 支持字段：

字段	类型	必需	默认值	说明
items	Array	✅	-	菜单项数组，每个元素是一个菜单项配置对象（见下文）
bgcolor	String	❌	"white"	背景颜色
target	String	❌	-	点击菜单项后内容加载的目标组件 ID 或特殊值 'PopupWindow' / 'Popup'
popup_options	Object	❌	{}	当目标为 PopupWindow 或 Popup 时使用的弹窗配置

⚠️ 注意：target 和 popup_options 可在单个菜单项中覆盖。

示例

new bricks.Menu({
  items: [
    { label: "首页", url: "/home" },
    { label: "用户管理", submenu: "/api/users" }
  ],
  target: "main_content",
  bgcolor: "#f5f5f5"
});

---

核心方法

create_submenu_container()

创建一个用于容纳子菜单的容器（VBox），默认隐藏并带有缩进样式。

返回值

• {bricks.VBox} —— 已配置好样式的子菜单容器

样式设置

• marginLeft: "15px"
• display: "none"

---

async menu_clicked(event)

处理菜单项被点击后的逻辑，根据配置打开页面、弹窗或注入到指定组件。

参数

• event: DOM 事件对象，包含 params 字段，即菜单项数据。

行为逻辑

1. 解析目标类型：
   • 若 target === 'PopupWindow'：创建 PopupWindow 实例
   • 若 target === 'Popup'：创建 Popup 实例
   • 否则：查找对应 ID 的组件 (bricks.getWidgetById)
2. 使用 widgetBuild 动态生成 URL Widget 并插入目标组件
3. 触发全局 command 事件，携带原始菜单项参数

触发事件

• command：携带菜单项信息，可用于外部监听执行命令

日志输出

• 失败时打印错误日志：
  • 目标组件未找到
  • widget 构建失败

---

create_children(w, items)

递归创建菜单项及其子菜单。

参数

参数	类型	说明
w	bricks.Container	容器组件，用于添加生成的菜单项
items	Array	菜单项列表

子菜单类型判断

条件	类型	说明
item.items 存在	静态子菜单	直接递归创建
item.submenu 存在	动态子菜单	点击时通过 URL 加载
其他	叶节点菜单项	绑定点击事件触发 item_click

内部行为

• 创建 HBox 表示菜单项
• 添加图标与文本
• 绑定点击/展开事件
• 支持国际化（i18n）、换行、左对齐等文本特性

---

async get_submenu_items(url)

从远程 URL 获取子菜单数据（JSON 格式）。

参数

• url (String): 请求地址

返回值

• Promise<Array>: 菜单项数组（data.options.items）

示例响应格式

{
  "options": {
    "items": [
      { "label": "子项1", "url": "/sub1" },
      { "label": "子项2", "url": "/sub2" }
    ]
  }
}

---

async load_submenu(container, event)

懒加载动态子菜单内容。

参数

• container: 子菜单容器（VBox）
• event: 点击事件

流程

1. 阻止事件冒泡
2. 若未加载过，则调用 get_submenu_items() 获取数据
3. 调用 create_children() 填充内容
4. 切换显示/隐藏状态

✅ 实现“点击展开 → 首次加载 → 缓存”机制

---

items_toggle_hide(w, event)

切换静态子菜单的可见性。

参数

• w: 子菜单容器
• event: 事件对象

行为

• 执行 toggle_hide() 显示或隐藏
• 阻止事件冒泡

---

create_menuitem(item)

创建单个菜单项 UI 组件（HBox）。

参数

• item: 菜单项配置对象

属性	类型	说明
label	String	显示文本（支持 i18n）
icon	String	图标 URL
url	String	导航链接
name	String	名称（备用标题）
其他字段	Any	将直接挂载到返回的 widget 上

返回值

• {bricks.HBox} 包含图标和文本的水平布局组件

子组件

组件	类型	说明
iw	Icon 或 BlankIcon	图标区域，若无图标则占位
tw	Text	文本标签，启用自动换行、左对齐、填充样式

样式类

• 应用 CSS 类名：menuitem_css 或默认 'menuitem'

---

regen_menuitem_event(item, event)

菜单项点击事件处理器，用于非容器型菜单项。

行为

• 记录日志
• 触发 item_click 事件并传递 item
• 阻止事件冒泡

---

事件系统

监听的事件

• item_click: 当菜单项被点击时触发，由 regen_menuitem_event 发出

分发的事件

事件名	数据	说明
item_click	item 对象	内部使用，通知上级处理点击
command	item 对象	外部可监听，表示一个命令被执行

---

配置与扩展

默认弹窗选项获取

• bricks.get_popupwindow_default_options()
• bricks.get_popup_default_options()

可通过 popup_options 合并自定义配置（使用 bricks.extend）

国际化支持

• Text 组件启用 i18n: true，支持多语言翻译

样式定制

• 可通过 menuitem_css 自定义菜单项样式类
• 使用 set_css() 和 set_style() 进行细粒度控制

---

注册与工厂模式

bricks.Factory.register('Menu', bricks.Menu);

允许通过字符串标识符创建实例：

bricks.createWidget("Menu", options);

---

使用场景示例

场景 1：静态树形菜单

const menu = new bricks.Menu({
  items: [
    {
      label: "仪表盘",
      icon: "/icons/dashboard.png",
      url: "/dashboard"
    },
    {
      label: "设置",
      items: [
        { label: "账户", url: "/settings/account" },
        { label: "安全", url: "/settings/security" }
      ]
    }
  ],
  target: "main_panel"
});

场景 2：动态加载子菜单

const menu = new bricks.Menu({
  items: [
    {
      label: "产品分类",
      submenu: "/api/categories",
      icon: "/icons/folder.png"
    }
  ],
  target: "PopupWindow",
  popup_options: {
    width: 800,
    height: 600
  }
});

---

注意事项

1. 性能优化：动态子菜单仅在首次展开时请求数据，后续展开直接显示缓存内容。
2. 事件隔离：所有点击事件均调用 stopPropagation() 防止意外冒泡。
3. URL Widget 构建：依赖 bricks.widgetBuild() 异步构建，需确保环境已初始化。
4. 目标组件存在性：应确保 target 所指组件已注册且可用。

---

依赖模块

模块	用途
bricks.VBox, bricks.HBox	布局容器
bricks.Icon, bricks.BlankIcon	图标显示
bricks.Text	文本渲染与 i18n
bricks.PopupWindow, bricks.Popup	弹窗组件
bricks.HttpJson	JSON 数据请求
bricks.Factory, bricks.widgetBuild	组件工厂与异步构建
bricks.extend	对象合并工具函数

---

版本信息

• 作者: Bricks Framework Team
• 版本: v1.0（基础功能稳定）
• 最后更新: 2025年4月5日

---

✅ 本组件适用于构建灵活、可扩展的菜单系统，推荐结合路由系统或 CMS 后台使用。