3.5.2.1.3. 按钮

在线示例

API 文档

当用户点击一个按钮,就会执行一个操作。

Button

该组件对应的 XML 名称: button

按钮上可以有标题、图标、或者两者皆有。下面这个图列举了一些不同类型的按钮。

gui buttonTypes

下面是从本地化消息包获取文本显示到按钮和提示上的例子:

  1. <button id="textButton" caption="msg://someAction" description="Press me"/>

按钮上的标题是用 caption 属性来设置,弹出提示用 description 来设置。

如果 disableOnClick 属性设置成 true 这个按钮在点击之后就会变成不可点击的状态,主要用来防止多次(意外的)点击这个按钮。之后可以通过调用 setEnabled(true) 把按钮恢复成可点击状态。

icon 属性定义了图标的位置或者图标集中的名称。详细信息请参看图标

创建带有图标的按钮的例子:

  1. <button id="iconButton" caption="" icon="SAVE"/>

按钮的主要功能是在点击的时候执行一个动作(action)。点击之后调用的控制器方法可以通过 invoke 属性来定义。这个属性的值需要是控制器的方法名,这个方法需要满足下面的条件:

  • 方法应该是 public

  • 方法返回值是 void

  • 方法不能有任何参数, 或者只能有一个 Component 组件类型的参数。 如果方法带有 Component 参数, 那么这个组件就是调用此方法的按钮实例。

以下是按钮调用 someMethod 的例子:

  1. <button invoke="someMethod" caption="msg://someButton"/>

在界面控制器里需要定义名称为 someMethod 的方法:

  1. public void someMethod() {
  2. //some actions
  3. }

如果设置了 action 属性,那么就会忽略 invoke 属性。action 属性包含了按钮中相应操作的名称。

带有 action 属性的按钮的例子:

  1. <actions>
  2. <action id="someAction" caption="msg://someAction"/>
  3. </actions>
  4. <layout>
  5. <button action="someAction"/>
  6. </layout>

实现了 Component.ActionsHolder 接口的组件中的任何操作都可以指定给按钮。表格分组表格树形表格中的操作都可以指定给按钮。有两种添加操作的方法,一种是在 XML 描述中以声明的方式添加,另一种是在界面控制器里以编程的方式添加,这两种方式没有区别。不管使用哪种方式,在使用操作的时候,组件的名称和操作的标识符必须定义在 action 属性中,并且它们之间用 . 分隔。比如,下面的例子中,将 coloursTablecreate 操作指定给一个按钮:

  1. <button action="coloursTable.create"/>

按钮的操作也可以通过编程创建,方法是在界面控制器中创建继承自BaseAction的类。

如果给 Button 定义了 Action 实例,那么按钮会从操作获取以下属性:captiondescriptioniconenableshortcutvisible。其中 captiondescriptionicon 属性只有在 Button 本身没有设置时才会使用操作的对应属性,其它的 Action 的属性比 Button 的相同属性有更高的优先级。

如果 操作 的属性在其被指定给 Button 之后发生了改变, 那么 Button 的相应属性也会跟着改变,也就是说按钮监听 操作 的变化。这种情况下,如果操作的 captiondescriptionicon 改变的话,即便按钮本身也定义了这些属性,这些属性还是会跟随操作的属性变化而变化。

shortcut 属性用来为按钮指定一个快捷键组合,使用字符串来定义。可选的功能键为:ALTCTRLSHIFT,使用 “-“ 与其他键分隔。示例:

  1. <button id="button" caption="msg://shortcutButton" shortcut="ALT-C"/>

按钮样式

primary 属性用来将按钮设置为高亮显示,默认情况下,如果这个按钮调用的操作的primary属性为 true,这个按钮会被设置为高亮显示。

  1. <button primary="true"
  2. invoke="foo"/>

这个高亮样式在 Hover 主题中是默认开启的;如果希望在 Halo-based 主题中使用 primary 样式,可以通过设置 $cuba-highlight-primary-action 样式变量true 来开启。

actions primary

接下来,在使用了 Halo-based 主题的 Web Client 里,可以通过 stylename 属性来给按钮组件设置一些预定义的样式,可以通过 XML 或者编程的方法设置:

  1. <button id="button"
  2. caption="Friendly button"
  3. stylename="friendly"/>

如果使用编程的方式来设置样式, 可以直接用 HaloTheme 主题类里面的以 BUTTON_ 开头的一些主题常量:

  1. button.setStyleName(HaloTheme.BUTTON_FRIENDLY);
  • borderless - 无边框的按钮。
  • borderless-colored - 无边框但是具有彩色按钮标题。
  • danger - 当按钮的操作比较危险时可以使用的一种警示按钮,比如会导致数据丢失或者其它不可撤消的操作。
  • friendly - 当按钮的操作比较安全的时候可以用的一种友好的按钮,比如不会导致数据丢失或者其它不可撤消的操作。
  • icon-align-right - 将按钮的图标对齐在按钮名称的右侧。
  • icon-align-top - 将按钮的图标放到按钮标题的上方。
  • icon-only - 只显示按钮的图标,并且把按钮调整成正方形。
  • primary - 主要的操作按钮,比如用户在填写表单时按下回车键的操作按钮。尽量少用,一般来说一个界面只有一个主要(primary)按钮。
  • quiet - “安静的” 按钮,跟 borderless 很像,只有在光标悬浮到这个按钮上面才会有样式变化。

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


按钮的属性

action - align - caption - captionAsHtml - css - description - descriptionAsHtml - disableOnClick - enable - box.expandRatio - icon - id - invoke - shortcut - stylename - tabIndex - visible - width

按钮预定义的样式

borderless - borderless-colored - danger - friendly - huge - icon-align-right - icon-align-top - icon-only - large - primary - quiet - small - tiny