yumoqing/bricks

Fork 0

yumoqing 55908f7b8f bugfix

2025-10-05 06:39:58 +08:00

8.0 KiB

Raw Blame History

`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 字段，即菜单项数据。

行为逻辑

解析目标类型：
- 若 target === 'PopupWindow'：创建 PopupWindow 实例
- 若 target === 'Popup'：创建 Popup 实例
- 否则：查找对应 ID 的组件 (bricks.getWidgetById)
使用 widgetBuild 动态生成 URL Widget 并插入目标组件
触发全局 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: 点击事件

流程

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

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

`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
  }
});

注意事项

性能优化：动态子菜单仅在首次展开时请求数据，后续展开直接显示缓存内容。
事件隔离：所有点击事件均调用 stopPropagation() 防止意外冒泡。
URL Widget 构建：依赖 bricks.widgetBuild() 异步构建，需确保环境已初始化。
目标组件存在性：应确保 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 后台使用。

8.0 KiB Raw Blame History Unescape Escape

bricks.Menu 技术文档

概述