菜单配置

MenuConfig 是一个特殊的类，根据 jmix.ui.menu-config 应用程序属性加载主菜单结构。

使用 Studio 菜单设计器 定义菜单结构。

当使用 Studio 新建项目时，会生成包含应用程序主菜单结构的 menu.xml 文件。

<menu-config xmlns="http://jmix.io/schema/flowui/menu">
    <menu id="main-menu"
          title="msg://com.company.onboarding/menu.application.title"
          description="Application menu items"
          opened="true"
          icon="DOT_CIRCLE"
          classNames="application-menu">
        <item id="Department.list"/>
        <separator/>
        <item view="City.list" id="cities"/>
    </menu>
</menu-config>

有两种加载菜单结构定义文件的 模式：composite（默认）和 single。使用 jmix.ui.composite-menu 应用程序属性切换这两种模式。

下面详细了解 menu.xml 文件的内容。

menu-config 是 XML 根元素。menu-config 内部的元素组成了一个树状结构，其中 menu 元素是分枝而 item 和 separator 元素是叶子结点。

menu 是 menu-config 的内部元素。具有下列属性：

  • id - 元素的唯一标识符。

  • title - menu 元素的标题。如果未设置，则会用 下面 介绍的规则确定标题。

  • description - 鼠标悬停时展示的提示文字。可以使用 消息包 中的本地化消息。

  • icon - menu 元素的图标。

  • classNames - 定义菜单项的 CSS 类名。

  • opened - 定义 menu 元素是否默认展开。默认值为 false。

示例：

<menu id="main-menu"
      title="msg://com.company.onboarding/menu.application.title"
      description="Application menu items"
      opened="true"
      icon="DOT_CIRCLE"
      classNames="application-menu">
    <item id="Department.list"/>
    <separator/>
    <item view="City.list" id="cities"/>
</menu>

item 属性

item 是 menu 的内部元素。对于每个 item，可以设置这些属性（attributes）、配置（properties）、（路由（route） 以及 查询参数（query parameters）。

有下列属性：

  • id - 元素的唯一标识符。如果没有定义 view、bean 属性，则可以使用 id 指向同名视图。当用户点击时，会在主主界面打开相应的视图。

    <item id="Department.list"/>

  • title — item 元素的标题。可以使用 消息包 中的本地化小心。如果未设置，则会用 下面 介绍的规则确定标题。

    <item view="User.list" title="msg://com.company.onboarding.view.user/UserListView.title"/>

  • description — 鼠标悬停时展示的提示文字。可以使用 消息包 中的本地化消息。

  • view — 视图标识符。可以用来在多个菜单打开同一界面。当用户点击时，会在主界面打开相应的视图。

    <item view="City.list" id="cities1"/>
<item view="City.list" id="cities2"/>

  • bean —  bean 名称。必须与 beanMethod 一起使用。当用户点击时，执行指定的 bean 方法。

    menu.xml
    <item bean="MenuBean"
      beanMethod="browseCities"
      title="Show Cities"/>
    MenuBean.java
    @Component("MenuBean")
public class MenuBean {

    @Autowired
    private ViewNavigationSupport viewNavigationSupport;

    public void browseCities() {
        viewNavigationSupport.navigate(CityListView.class);
    }
}

    使用 properties 内部元素可以从菜单项传递参数至 bean 方法。示例：

    menu.xml
    <item bean="MenuBean" beanMethod="openLink"
      id="openBeanWithParams" title="External Link">
    <properties>
        <property name="url" value="https://jmix.io"/>
    </properties>
</item>
    MenuBean.java
    @Component("MenuBean")
public class MenuBean {

    public void openLink(Map<String, Object> parameters) {
        String url = (String) parameters.get("url");
        if (url == null) {
            return;
        }
        UI.getCurrent().getPage().open(url);
    }
}

  • shortcutCombination — 菜单项的 键盘快捷键。示例：

    <item view="City.list"
      id="cities3"
      shortcutCombination="ALT-C"/>

    快捷键可以在 application.properties 文件配置，在 menu.xml 文件使用：

    menu.xml
    <item view="City.list"
      id="cities4"
      shortcutCombination="${sample.menu.city}"/>
    application.properties
    sample.menu.city=ALT-SHIFT-C

  • icon — item 元素的图标。

  • className — 定义菜单项的 CSS 类名。

item 配置

item 元素可以用内部的 properties 元素配置传入 bean 的参数。properties 是一个容器元素，内部的 property 子元素用来定义具体的配置，可以设置：

  • name — 配置属性名称

  • value — 配置属性值。

路由参数

item 元素可以在子元素 routeParameters 中声明路由参数。

定义视图路由的 URL 路径可以包含路由参数。例如，传入 详情视图 的实体实例 id 就可以作为路由参数。下面例子中的菜单项打开特定部门的详情视图：

menu.xml
<item view="Department.detail" title="HR Department">
    <routeParameters>
        <parameter name="id" value="9b77a432-1610-5147-ff93-e7ee27c26e09"/>
    </routeParameters>
</item>

URL 查询参数

item 元素还可以在子元素 urlQueryParameters 中定义一个或多个 URL 查询参数（query parameter）。

menu.xml
<item view="City.list" title="Query Parameters">
    <urlQueryParameters>
        <parameter name="page" value="3"/>
        <parameter name="sort" value="desc"/>
    </urlQueryParameters>
</item>

查询参数是 URL 尾部问号（?）后的名值对。多个查询参数可以用 & 符号分隔。上面示例会创建一个菜单项打开下面的 URL：

https://example.com/cities?page=3&sort=desc

菜单标题

如果 title 属性未定义，则 menu 或 item 标题通过这种方式定义：以 menu-config 作为前缀，再加上元素的 id，中间以 “.” 分隔。形成的字符串作为 消息包 的键值。示例：

messages.properties
menu-config.Departments.list = Departments
menu-config.cities = Cities

如果菜单项的 id 未设置，为了给这种菜单项定义标题，会在 menu-config 之后添加视图名称或 bean 名称及方法，以 # 分隔。