声明式操作 - CUBA 框架开发者手册

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 是突出显示的。
shortcut - 快捷键。
可以在 XML 描述中对快捷键值进行硬编码。可选的修饰键：ALT、CTRL、SHIFT ，由“ - ”字符分隔。例如：
<action id="create" shortcut="ALT-N"/>
要避免使用硬编码值，可以使用下面列表中的预定义快捷键别名，例如：
<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
另一种选择是使用 Config 接口和方法的完全限定名称，这个方法返回快捷键定义：
<action id="remove" shortcut="${com.haulmont.cuba.client.ClientConfig#getTableRemoveShortcut}"/>
visible – 可见性标识 (true / false).

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

为整个界面声明操作：

<window>
    <actions>
        <action id="sayHello" caption="msg://sayHello" shortcut="ALT-T"/>
    </actions>

    <layout>
        <button action="sayHello"/>
    </layout>
</window>

// controller
@Inject
private Notifications notifications;

@Subscribe("sayHello")
protected void onSayHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
                .withCaption("Hello")
                .withType(Notifications.NotificationType.HUMANIZED)
                .show();
}

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

注意，为整个界面声明的操作不会刷新状态。也就是说，如果一个操作有特定的 enabledRule，直到手动调用 refreshState() 时才会应用。

为PopupButton声明操作:

<popupButton id="sayBtn" caption="Say">
    <actions>
        <action id="hello" caption="Say Hello"/>
        <action id="goodbye" caption="Say Goodbye"/>
    </actions>
</popupButton>

// controller
@Inject
private Notifications notifications;

private void showNotification(String message) {
    notifications.create()
            .withCaption(message)
            .withType(NotificationType.HUMANIZED)
            .show();
}

@Subscribe("sayBtn.hello")
private void onSayBtnHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

@Subscribe("sayBtn.goodbye")
private void onSayBtnGoodbyeActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

为Table声明操作:

<groupTable id="customersTable" width="100%" dataContainer="customersDc">
    <actions>
        <action id="create" type="create"/>
        <action id="edit" type="edit"/>
        <action id="remove" type="remove"/>
        <action id="copy" caption="Copy" icon="COPY" trackSelection="true"/>
    </actions>
    <columns>
        <!-- -->
    </columns>
    <rowsCount/>
    <buttonsPanel alwaysVisible="true">
        <!-- -->
        <button action="customersTable.copy"/>
    </buttonsPanel>
</groupTable>

// controller

@Subscribe("customersTable.copy")
protected void onCustomersTableCopyActionPerformed(Action.ActionPerformedEvent event) {
    // ...
}

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

声明PickerField操作:

<pickerField id="userPickerField" dataContainer="customerDc" property="user">
    <actions>
        <action id="lookup" type="picker_lookup"/>
        <action id="show" description="Show user" icon="USER"/>
    </actions>
</pickerField>

// controller

@Subscribe("userPickerField.show")
protected void onUserPickerFieldShowActionPerformed(Action.ActionPerformedEvent event) {
    //
}

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

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

@Named("customersTable.copy")
private Action customersTableCopy;

@Inject
private PickerField<User> userPickerField;

@Subscribe
protected void onBeforeShow(BeforeShowEvent event) {
    customersTableCopy.setEnabled(false);
    userPickerField.getActionNN("show").setEnabled(false);
}