3.5.2.1.40. 侧边菜单

API 文档

SideMenu 组件提供了定制主窗口布局、管理菜单项、添加图标和标记(badges)以及应用自定义样式的方法。

它也可以像其它可视化组件一样用在任何界面中。要将 SideMenu 组件添加到界面，应该将 xmlns：main ="http://schemas.haulmont.com/cuba/mainwindow.xsd" 命名空间添加到界面描述中。

gui sidemenu

该组件的 XML 名称： sideMenu

在界面 XML 描述中定义该组件的示例:

  1. <main:sideMenu id="sideMenu"
  2.                width="100%"
  3.                selectOnClick="true"/>

CUBA Studio 为主窗口提供了界面模板，其中包含 sideMenu 组件和侧边面板中的预定义样式：

  1. <layout>
  2.     <hbox id="horizontalWrap"
  3.           expand="workArea"
  4.           height="100%"
  5.           stylename="c-sidemenu-layout"
  6.           width="100%">
  7.         <vbox id="sideMenuPanel"
  8.               expand="sideMenu"
  9.               height="100%"
  10.               margin="false,false,true,false"
  11.               spacing="true"
  12.               stylename="c-sidemenu-panel"
  13.               width="250px">
  14.             <hbox id="appTitleBox"
  15.                   spacing="true"
  16.                   stylename="c-sidemenu-title"
  17.                   width="100%">
  18.                 <label id="appTitleLabel"
  19.                        align="MIDDLE_CENTER"
  20.                        value="mainMsg://application.logoLabel"/>
  21.             </hbox>
  22.             <embedded id="logoImage"
  23.                       align="MIDDLE_CENTER"
  24.                       stylename="c-app-icon"
  25.                       type="IMAGE"/>
  26.             <hbox id="userInfoBox"
  27.                   align="MIDDLE_CENTER"
  28.                   expand="userIndicator"
  29.                   margin="true"
  30.                   spacing="true"
  31.                   width="100%">
  32.                 <main:userIndicator id="userIndicator"
  33.                                     align="MIDDLE_CENTER"/>
  34.                 <main:newWindowButton id="newWindowButton"
  35.                                       description="mainMsg://newWindowBtnDescription"
  36.                                       icon="app/images/new-window.png"/>
  37.                 <main:logoutButton id="logoutButton"
  38.                                    description="mainMsg://logoutBtnDescription"
  39.                                    icon="app/images/exit.png"/>
  40.             </hbox>
  41.             <main:sideMenu id="sideMenu"
  42.                            width="100%"/>
  43.             <main:ftsField id="ftsField"
  44.                            width="100%"/>
  45.         </vbox>
  46.         <main:workArea id="workArea"
  47.                        height="100%">
  48.             <main:initialLayout margin="true"
  49.                                 spacing="true">
  50.                 <label id="welcomeLabel"
  51.                        align="MIDDLE_CENTER"
  52.                        stylename="c-welcome-text"
  53.                        value="mainMsg://application.welcomeText"/>
  54.             </main:initialLayout>
  55.         </main:workArea>
  56.     </hbox>
  57. </layout>

sideMenu 属性：

  • selectOnClick 属性设置为 true 时，会在鼠标单击时突出显示选中的菜单项。默认值为 false。

gui sidemenu 2

SideMenu 接口的方法：

  • createMenuItem - 创建一个新菜单项，但不将此项添加到菜单。对于整个菜单，Id 必须是唯一的。
  • addMenuItem - 添加菜单项到菜单。

  • removeMenuItem - 从菜单项列表中移除菜单项。

  • getMenuItem - 根据 id 从菜单树中获取菜单项。

  • hasMenuItems - 如果菜单包含菜单项，则返回 true。

SideMenu 组件用于显示菜单项。MenuItem API 允许在界面控制器中创建菜单项。以下方法可用于根据应用程序业务逻辑动态更新菜单项。以编程方式添加菜单项的示例：

  1. SideMenu.MenuItem item = sideMenu.createMenuItem("special");
  2. item.setCaption("Daily offer");
  3. item.setBadgeText("New");
  4. item.setIconFromSet(CubaIcon.GIFT);
  5. sideMenu.addMenuItem(item,0);

gui sidemenu 3

MenuItem 接口的方法：

  • setCaption - 设置菜单项名称。
  • setCaptionAsHtml - 启用或禁用 HTML 模式的菜单名称。

  • setBadgeText - 设置菜单项的标记文本。标记是显示在菜单项右侧的小部件，例如：

    1. int count = 5;
    2. SideMenu.MenuItem item = sideMenu.createMenuItem("count");
    3. item.setCaption("Messages");
    4. item.setBadgeText(count + " new");
    5. item.setIconFromSet(CubaIcon.ENVELOPE);
    6. sideMenu.addMenuItem(item,0);

    gui sidemenu 4

    标记文本可以在 Timer 组件的配合下动态更新：

    1. public void updateCounters(Timer source) {
    2.     sideMenu.getMenuItemNN("sales")
    3.             .setBadgeText(String.valueOf(LocalTime.MIDNIGHT.minusSeconds(timerCounter-source.getDelay())));
    4.     timerCounter++;
    5. }

    gui sidemenu 5

  • setIcon - 设置菜单项图标。
  • setCommand - 设置菜单项命令，或点击菜单项时要执行的操作。
  • addChildItem/removeChildItem - 添加或移除子菜单的菜单项。
  • setExpanded - 默认展开或折叠包含子菜单的菜单项。

  • setStyleName - 给组件设置一个或多个自定义样式名，并且会覆盖所有已定义的用户样式。多个样式通过空格分隔的样式名列表指定。样式名必须是有效的 CSS class 名称。

    标准的 sideMenu 模板包含一些预定义样式： c-sidemenu-layout 、 c-sidemenu-panel 和 c-sidemenu-title。默认的 c-sidemenu 样式在 Halo 和 Hover 这两个主题及它们的扩展主题中支持。

  • setTestId - 调用用于 UI 测试的 cuba-id 值。

PopupButton 的展示可以使用带 $cuba-sidemenu-* 和 $cuba-responsive-sidemenu-* 前缀的 SCSS 变量进行自定义。可以在创建一个 主题扩展 或者一个 自定义主题 之后在可视化编辑器里修改这些变量的值。

sideMenu 的属性

align - caption - css - description - enable - height - icon - id - selectOnClick - stylename - tabIndex - visible - width

ftsfield 属性

align - caption - description - enable - height - icon - id - stylename - visible - width

sideMenu 的 API

addMenuItem - createMenuItem - removeMenuItem

menuItem 的 API

addChildItem - removeChildItem - setBadgeText - setCaption - setCaptionAsHtml - setCommand - setExpanded - setIcon - setStyleName - setTestId