3.5.2.5. 可视化组件 API

API 文档

通用

  • unwrap() - 返回针对不同客户端的组件实例(Vaadin 或者 Swing 组件)。可以在 Client 模块简化底层 API 的调用,参考 使用 Vaadin 组件 章节。

    1. com.vaadin.ui.TextField vTextField = textField.unwrap(com.vaadin.ui.TextField.class);
  • unwrapComposition() - 返回针对不同客户端的最外层的外部包裹容器(external container)。可以在 Client 模块简化底层 API 的调用。

这两个方法支持所有可视化组件。

Buffered-缓冲写入模式接口

  • commit() - 从上次更新之后的所有改动更新到数据源。
  • discard() - 从上次更新之后所有的改动都废弃掉。对象会从数据源更新数据。
  • isModified() - 如果从上次更新后这个对象有过改动,这个方法会返回 true
  1. if (textArea.isModified()) {
  2. textArea.commit();
  3. }

支持此接口的组件:

CheckBox - CurrencyField - DateField - DatePicker - FileUploadField - LookupField - LookupPickerField - MaskedField - PasswordField - PickerField - RichTextArea - SearchPickerField - SuggestionPickerField - TextArea - TextField - TimeField

Collapsable-可折叠接口

  • addExpandedStateChangeListener() - 添加实现了 ExpandedStateChangeListener 接口的监听器来拦截组件的展开状态变化事件。

    1. @Subscribe("groupBox")
    2. protected void onGroupBoxExpandedStateChange(Collapsable.ExpandedStateChangeEvent event) {
    3. notifications.create()
    4. .withCaption("Expanded: " + groupBox.isExpanded())
    5. .show();
    6. }

    支持此接口的组件:

Filter - GroupBoxLayout

ComponentContainer-组件容器接口

  • add(component) - 添加子组件到容器。
  • remove(component) - 从容器移除子组件。
  • removeAll() - 移除容器内所有组件。
  • getOwnComponent(id) - 返回直接拥有(directly owned)的组件。
  • getComponent(id) - 返回这个容器下面组件树的一个组件。
  • getComponentNN(id) - 返回这个容器下面组件树的一个组件。如果没找到,会抛出异常。
  • getOwnComponents() - 返回这个容器直接拥有的所有组件。
  • getComponents() - 返回这个容器下的组件树的所有组件。

支持此接口的组件:

Accordion - BoxLayout - CssLayout - FieldGroup - Form - Frame - GridLayout - GroupBoxLayout - HtmlBoxLayout - ScrollBoxLayout - SplitPanel - TabSheet

OrderedContainer-有序容器接口

  • indexOf() - 返回给定组件在有序容器中的索引位置。

支持此接口的组件:

BoxLayout - CssLayout - Frame - GroupBoxLayout - ScrollBoxLayout -

HasContextHelp-内容提示接口

  • setContextHelpText() - 设置内容提示文本。如果设置的话,会为字段添加一个特殊的图标,参阅: contextHelpText

  • setContextHelpTextHtmlEnabled() - 定义是否用 HTML 渲染内容提示文本。参阅: contextHelpTextHtmlEnabled

  • setContextHelpIconClickHandler() - 设置内容提示图标点击处理函数。点击处理函数比 context help text 优先级高,也就是说,如果点击处理函数设置了的话,默认的弹出小窗便不会显示。

  1. textArea.setContextHelpIconClickHandler(contextHelpIconClickEvent ->
  2. dialogs.createMessageDialog()
  3. .withCaption("Title")
  4. .withMessage("Message body")
  5. .withType(Dialogs.MessageType.CONFIRMATION)
  6. .show()
  7. );

几乎所有组件都支持此接口:

Accordion - BoxLayout - BrowserFrame - ButtonsPanel - Calendar - CheckBox - CheckBoxGroup - ColorPicker - CssLayout - CurrencyField - DataGrid - DateField - DatePicker - Embedded - FieldGroup - FileUploadField - Filter - Form - GridLayout - GroupBoxLayout - GroupTable - HtmlBoxLayout - Image - JavaScriptComponent - Label - LookupField - LookupPickerField - MaskedField - OptionsGroup - OptionsList - PasswordField - PickerField - PopupView - ProgressBar - RadioButtonGroup - RichTextArea - ScrollBoxLayout - SearchPickerField - SourceCodeEditor - SplitPanel - SuggestionField - SuggestionPickerField - Table - TabSheet - TextArea - TextField - TimeField - TokenList - Tree - TreeDataGrid - TreeTable - TwinColumn

HasSettings-用户设置接口

  • applySettings() - 恢复上次用户使用该组件的设置。

  • saveSettings() - 保存当前用户对该组件的设置。

支持此接口的组件:

DataGrid - Filter - GroupBoxLayout - SplitPanel - Table - TextArea

HasUserOriginated-事件来源接口

  • isUserOriginated() - 提供事件来源的信息。如果事件是在客户端通过用户交互触发,则返回 true。如果是在服务端以编程方式触发,则返回 false

    用例示范:

    1. @Subscribe("customersTable")
    2. protected void onCustomersTableSelection(Table.SelectionEvent<Customer> event) {
    3. if (event.isUserOriginated())
    4. notifications.create()
    5. .withCaption("You selected " + event.getSelected().size() + " customers")
    6. .show();
    7. }

isUserOriginated() 方法支持对以下事件进行跟踪:

  • CollapseEvent,所属组件: TreeDataGrid

  • ColumnCollapsingChangeEvent,所属组件: DataGrid

  • ColumnReorderEvent,所属组件: DataGrid

  • ColumnResizeEvent,所属组件: DataGrid

  • ExpandedStateChangeEvent,所属组件: FilterGroupBoxLayout (参阅 Collapsable),

  • ExpandEvent,所属组件: TreeDataGrid

  • SelectedTabChangeEvent,所属组件: TabSheet

  • SelectionEvent,所属组件: DataGrid

  • SelectionEvent,所属组件: Table

  • SortEvent,所属组件: DataGrid

  • SplitPositionChangeEvent,所属组件: SplitPanel

  • ValueChangeEvent,所属组件:所有实现了 HasValue 接口的组件 (参阅: ValueChangeListener)。

HasValue-有值处理接口

  • addValueChangeListener() - 添加实现了 ValueChangeListener 接口的监听器来拦截组件的值变化事件。

    1. @Inject
    2. private TextField<String> textField;
    3. @Inject
    4. private Notifications notifications;
    5. @Subscribe
    6. protected void onInit(InitEvent event) {
    7. textField.addValueChangeListener(stringValueChangeEvent ->
    8. notifications.create()
    9. .withCaption("Before: " + stringValueChangeEvent.getPrevValue() +
    10. ". After: " + stringValueChangeEvent.getValue())
    11. .show());
    12. }

    为了达到相同的目的,也可以订阅组件特定的事件,示例:

    1. @Subscribe("textField")
    2. protected void onTextFieldValueChange(HasValue.ValueChangeEvent<String> event) {
    3. notifications.create()
    4. .withCaption("Before: " + event.getPrevValue() +
    5. ". After: " + event.getValue())
    6. .show();
    7. }

也可参阅 UserOriginated.

支持此接口的组件:

CheckBox - CheckBoxGroup - ColorPicker - CurrencyField - DateField - DatePicker - FileUploadField - Label - LookupField - LookupPickerField - MaskedField - OptionsGroup - OptionsList - PasswordField - PickerField - ProgressBar - RadioButtonGroup - RichTextArea - SearchPickerField - SourceCodeEditor - SuggestionField - SuggestionPickerField - TextArea - TextField - TimeField - TokenList - TwinColumn

LayoutClickNotifier-布局点击通知接口

  • addLayoutClickListener() - 添加实现了 LayoutClickListener 接口的监听器拦截鼠标在组件区域点击事件。

    1. vbox.addLayoutClickListener(layoutClickEvent ->
    2. notifications.create()
    3. .withCaption("Clicked")
    4. .show());

    为了达到相同的目的,也可以订阅组件特定的事件,示例:

    1. @Subscribe("vbox")
    2. protected void onVboxLayoutClick(LayoutClickNotifier.LayoutClickEvent event) {
    3. notifications.create()
    4. .withCaption("Clicked")
    5. .show();
    6. }

支持此接口的组件:

ButtonsPanel - BoxLayout - CssLayout - GridLayout

HasMargin-容器边距接口

  • setMargin() - 设置容器外边框和容器内容之间的边距。

    • 设置组件所有方向的边距:

      1. vbox.setMargin(true);
    • 只设置上边距和下边距:

      1. vbox.setMargin(true, false, true, false);
    • 创建 MarginInfo 配置类实例来设置边距:

      1. vbox.setMargin(new MarginInfo(true, false, false, true));
  • getMargin() - 以 MarginInfo 实例的方式返回组件的边距设置。

支持此接口的组件:

BoxLayout - Filter - Frame - GridLayout ScrollBoxLayout

HasOuterMargin-组件外边距接口

  • setOuterMargin() - 设置组件外边框外的边距。

    • 设置所有方向的外边距:

      1. groupBox.setOuterMargin(true);
    • 只设置组件上下外边距:

      1. groupBox.setOuterMargin(true, false, true, false);
    • 创建 MarginInfo 配置类实例来设置外边距:

      1. groupBox.setOuterMargin(new MarginInfo(true, false, false, true));
  • getOuterMargin() - 以 MarginInfo 实例的方式返回组件的外边距设置。

支持此接口的组件:

GroupBoxLayout

HasSpacing-留白接口

  • setSpacing() - 在这个组件和他的子组件之间添加一些空白。

    1. vbox.setSpacing(true);

支持此接口的组件:

BoxLayout - ButtonsPanel - Frame - GridLayout GroupBoxLayout - ScrollBoxLayout

ShortcutNotifier-快捷键接口

  • addShortcutAction() - 添加一个操作,当用户按下配置的快捷键组合的时候触发。

    1. cssLayout.addShortcutAction(new ShortcutAction("SHIFT-A", shortcutTriggeredEvent ->
    2. notifications.create()
    3. .withCaption("SHIFT-A action")
    4. .show()));

支持此接口的组件:

BoxLayout - ButtonsPanel - CssLayout - GridLayout - GroupBoxLayout - ScrollBoxLayout