Appendix A: 项目配置文件 - A.5. menu.xml - 《CUBA 框架开发者手册 Version 7.0》

A.5. menu.xml

这个类型的文件在 Web 客户端使用，定义应用程序的主菜单结构。

XML schema： http://schemas.haulmont.com/cuba/7.0/menu.xsd

这个文件的路径由 cuba.menuConfig 应用程序属性指定。当在 Studio 里面创建新项目的时候，会在 web 模块包的根目录创建 web-menu.xml 文件，比如 modules/web/src/com/company/sample/web-menu.xml。

menu-config – XML 根节点元素。menu-config 的元素组成了一个树状结构，这里 menu 元素是树枝，item 和 separator 元素是树叶。

menu 元素的属性：

id – 元素的标识符，菜单元素的本地化标题通过 id 来决定（参考如下）。
description - 光标悬浮提示窗的内容。可以使用主语言包里面的本地化语言。
icon - 菜单元素的图标。参考 icon 了解细节。
insertBefore 、 insertAfter – 设置此菜单项应当放在特定的元素或者特定的名称的菜单项之前或之后。这个属性用来在应用程序组件菜单文件定义的菜单中找一个合适的位置插入此菜单项。insertBefore 和 insertAfter 不能同时使用。
stylename - 为菜单项定义一个样式名称。参考主题了解细节。

item 元素的属性：

id – 元素的唯一标识符，菜单元素的本地化标题通过 id 来决定（参考如下）。如果没有定义任何 screen，bean，class 属性，此 id 用来指向具有相同 id 值的界面。当用户点击菜单项时，会在程序主窗口打开对应的界面。

<item id="sample_Foo.browse"/>

screen - 界面标识符。可以用这个标识符在菜单中多次包含同一界面。当用户点击菜单项时，会在程序主窗口打开对应的界面。

<item id="foo1" screen="sample_Foo.browse"/>
<item id="foo2" screen="sample_Foo.browse"/>

bean - bean 名称。必须跟 beanMethod 一起使用。当用户点击菜单项时，会调用 bean 的此方法。

<item bean="sample_FooProcessor" beanMethod="processFoo"/>

class - 实现了 Runnable 的类全名。当用户点击菜单项时，会创建指定类的一个对象，并调用其 run() 方法。

<item class="com.company.sample.web.FooProcessor"/>

description - 光标悬浮提示窗显示的文字。可以从主语言包中使用本地化语言。

<item id="sample_Foo.browse" description="mainMsg://fooBrowseDescription"/>

shortcut – 此菜单项的快捷键。可以用 ALT, CTRL, SHIFT 功能键，用 - 分隔，比如：

shortcut="ALT-C"
shortcut="ALT-CTRL-C"
shortcut="ALT-CTRL-SHIFT-C"

快捷键也可以通过应用程序属性来配置，然后在 menu.xml 文件中通过下列方式来使用：

shortcut="${sales.menu.customer}"

openType – 界面打开模式。对应于 OpenMode 枚举：NEW_TAB，THIS_TAB，DIALOG。默认值是 NEW_TAB。
icon - 菜单元素的图标。参考 icon 了解细节。
insertBefore, insertAfter – 设定此项应当在一个特定元素或者标识符指定的特定菜单项之前或者之后。
resizable – 只跟 DIALOG 界面打开模式有关。控制界面是否能改变大小。可选值：true，false。默认情况下主菜单不会影响弹出窗口的改变大小的功能。
stylename - 为菜单项定义一个样式名称。参考主题了解细节。

item 的子元素：

param – 传递到界面旧控制器的 init() 方法的参数。在 menu.xml 里配置的参数会覆盖在 screens.xml 里配置的同名参数。

param 的属性：

name – 参数名称
value – 参数值。字符串类型，按照下面的规则可以转成其它类型的对象：

如果字符串的值是一个实体的标识符，按照 EntityLoadInfo 类规定的格式，系统会加载指定的实体实例。

如果字符串是 ${some_name} 格式的，参数的值会被设置为 some_name 应用程序属性的值。

true 和 false 的字符串会被转化为 Boolean 类型的相应值。

其它情况，用字符串本身的值作为参数值。

permissions – 设置一组权限，用户只有满足这些权限才能使用此菜单项。这个机制应当在菜单项需要绑定到特定的权限或者绑定到多个权限时使用。大多数情况下，安全子系统的标准功能应该足以满足根据界面标识符控制菜单可用性的要求。

这个元素应当包含一组 permission 子元素，每个元素描述一条需要的权限。菜单项只有在所有权限都满足的情况下才可用。

permission 属性：

type – 权限类型。可用这些 PermissionType: SCREEN, ENTITY_OP, ENTITY_ATTR, SPECIFIC, UI。
target – 用来检查权限的对象（object）。根据权限类型会不同：

SCREEN – 界面标识符，比如 sales$Customer.lookup。

ENTITY_OP – 使用 {entity_name}:{op} 格式的字符串，这里 {op} 可以是：read, create, update, delete。比如 sales$Customer:create。

ENTITY_ATTR – 使用 {entity_name}:{attribute} 格式的字符串，比如 sales$Customer:name。

SPECIFIC – 特定的权限标识符，比如 sales.runInvoicing。

UI – 界面可视化组件的路径。

菜单文件的示例：

<menu-config xmlns="http://schemas.haulmont.com/cuba/menu.xsd">
  <menu id="sales" insertBefore="administration">
      <item id="sales_Customer.lookup"/>
      <separator/>
      <item id="sales_Order.lookup"/>
  </menu>
</menu-config>

菜单项的本地化语言名称可以通过这种方式来定义：menu-config 前缀加上一个点放到元素标识符前面；这个拼出来的字符串作为主语言包的一个键值。示例：

menu-config.sales=Sales
menu-config.sales$Customer.lookup=Customers

如果没设置 id，菜单元素的名称会通过类名（如果设置了 class 属性）或者 bean 名称和 bean 方法名称（如果设置了 bean 属性）生成，因此，推荐设置 id 属性。