3.5.5.1. 声明式操作

可以在 XML 界面描述中为任何实现了 Component.ActionsHolder 接口的组件指定一组操作,包括整个窗口或 frame。 操作的定义使用 actions 元素完成,它包含嵌套的 action 元素。

action 元素有以下属性:

  • id − 标识符,在 ActionsHolder 组件中应该是唯一的。

  • type - 定义指定的操作类型。如果设置了该属性,框架会搜索带有 @ActionType 注解以及指定类型的类,并用该类实例化此操作。如果未指定类型,框架会创建一个BaseAction类的实例。参阅 标准操作 了解如何使用框架提供的操作类型,以及 自定义操作类型 了解如何创建自己的操作类型。

  • caption – 操作名称。

  • description – 操作描述。

  • enable – 可用性标识(true / false)。

  • icon – 操作图标。

  • primary - 属性,表明是否应使用特殊视觉样式(true / false)突出显示表示此操作的按钮。

    突出显示在 hover 主题中默认可用; 要在 halo 主题中启用此功能,请将 $cuba-highlight-primary-action 样式变量设置为 true

    默认情况下,create 标准列表操作和查找界面中的 lookupSelectAction 是突出显示的。

    actions primary

  • shortcut - 快捷键。

    可以在 XML 描述中对快捷键值进行硬编码。可选的修饰键:ALTCTRLSHIFT ,由“ - ”字符分隔。例如:

    1. <action id="create" shortcut="ALT-N"/>

    要避免使用硬编码值,可以使用下面列表中的预定义快捷键别名,例如:

    1. <action id="edit" shortcut="${TABLE_EDIT_SHORTCUT}"/>
    • TABLE_EDIT_SHORTCUT

    • COMMIT_SHORTCUT

    • CLOSE_SHORTCUT

    • FILTER_APPLY_SHORTCUT

    • FILTER_SELECT_SHORTCUT

    • NEXT_TAB_SHORTCUT

    • PREVIOUS_TAB_SHORTCUT

    • PICKER_LOOKUP_SHORTCUT

    • PICKER_OPEN_SHORTCUT

    • PICKER_CLEAR_SHORTCUT

  1. 另一种选择是使用 `Config` 接口和方法的完全限定名称,这个方法返回快捷键定义:
  2. ```
  3. <action id="remove" shortcut="${com.haulmont.cuba.client.ClientConfig#getTableRemoveShortcut}"/>
  4. ```
  • visible – 可见性标识 (true / false).

下面是操作声明和处理的示例。

  • 为整个界面声明操作:

    1. <window>
    2. <actions>
    3. <action id="sayHello" caption="msg://sayHello" shortcut="ALT-T"/>
    4. </actions>
    5. <layout>
    6. <button action="sayHello"/>
    7. </layout>
    8. </window>
    1. // controller
    2. @Inject
    3. private Notifications notifications;
    4. @Subscribe("sayHello")
    5. protected void onSayHelloActionPerformed(Action.ActionPerformedEvent event) {
    6. notifications.create()
    7. .withCaption("Hello")
    8. .withType(Notifications.NotificationType.HUMANIZED)
    9. .show();
    10. }

    在上面的示例中,声明了一个操作,它的标识符是 sayHello,标题来自界面的消息包。此操作被绑定到一个按钮,按钮的标题将被设置为操作的名称。界面控制器订阅操作的 ActionPerformedEvent,这样当用户单击按钮或按下 ALT-T 快捷键时,将调用 onSayHelloActionPerformed() 方法。

  • PopupButton声明操作:

    1. <popupButton id="sayBtn" caption="Say">
    2. <actions>
    3. <action id="hello" caption="Say Hello"/>
    4. <action id="goodbye" caption="Say Goodbye"/>
    5. </actions>
    6. </popupButton>
    1. // controller
    2. @Inject
    3. private Notifications notifications;
    4. private void showNotification(String message) {
    5. notifications.create()
    6. .withCaption(message)
    7. .withType(NotificationType.HUMANIZED)
    8. .show();
    9. }
    10. @Subscribe("sayBtn.hello")
    11. private void onSayBtnHelloActionPerformed(Action.ActionPerformedEvent event) {
    12. notifications.create()
    13. .withCaption("Hello")
    14. .show();
    15. }
    16. @Subscribe("sayBtn.goodbye")
    17. private void onSayBtnGoodbyeActionPerformed(Action.ActionPerformedEvent event) {
    18. notifications.create()
    19. .withCaption("Hello")
    20. .show();
    21. }
  • Table声明操作:

    1. <groupTable id="customersTable" width="100%" dataContainer="customersDc">
    2. <actions>
    3. <action id="create" type="create"/>
    4. <action id="edit" type="edit"/>
    5. <action id="remove" type="remove"/>
    6. <action id="copy" caption="Copy" icon="COPY" trackSelection="true"/>
    7. </actions>
    8. <columns>
    9. <!-- -->
    10. </columns>
    11. <rowsCount/>
    12. <buttonsPanel alwaysVisible="true">
    13. <!-- -->
    14. <button action="customersTable.copy"/>
    15. </buttonsPanel>
    16. </groupTable>
    1. // controller
    2. @Subscribe("customersTable.copy")
    3. protected void onCustomersTableCopyActionPerformed(Action.ActionPerformedEvent event) {
    4. // ...
    5. }

    在这个例子中,除了表格的 createeditremove 标准动作之外,还声明了 copy 操作。trackSelection="true" 属性表示如果表格中没有行被选中,则操作和相应按钮将被禁用。如果要对当前选定的表格行执行操作, 这个属性就很有用。

  • 声明PickerField操作:

    1. <pickerField id="userPickerField" dataContainer="customerDc" property="user">
    2. <actions>
    3. <action id="lookup" type="picker_lookup"/>
    4. <action id="show" description="Show user" icon="USER"/>
    5. </actions>
    6. </pickerField>
    1. // controller
    2. @Subscribe("userPickerField.show")
    3. protected void onUserPickerFieldShowActionPerformed(Action.ActionPerformedEvent event) {
    4. //
    5. }

    在上面的例子中,为 PickerField 组件声明了标准的 picker_lookup 操作和一个额外的 show 操作。由于显示操作的 PickerField 按钮使用图标而不是标题,因此未设置标题属性。description 属性允许将光标悬停在操作按钮上时显示提示信息。

在界面控制器中可以通过直接注入或从实现 Component.ActionsHolder 接口的组件中获取中任何已声明操作的引用。这对于以编程方式设置操作属性非常有用。例如:

  1. @Named("customersTable.copy")
  2. private Action customersTableCopy;
  3. @Inject
  4. private PickerField<User> userPickerField;
  5. @Subscribe
  6. protected void onBeforeShow(BeforeShowEvent event) {
  7. customersTableCopy.setEnabled(false);
  8. userPickerField.getActionNN("show").setEnabled(false);
  9. }