3.5.2.5. 可视化组件 API

API 文档

通用

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

  com.vaadin.ui.TextField vTextField = textField.unwrap(com.vaadin.ui.TextField.class);

• unwrapComposition() - 返回针对不同客户端的最外层的外部包裹容器（external container）。可以在 Client 模块简化底层 API 的调用。

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

Buffered-缓冲写入模式接口

• commit() - 从上次更新之后的所有改动更新到数据源。

• discard() - 从上次更新之后所有的改动都废弃掉。对象会从数据源更新数据。

• isModified() - 如果从上次更新后这个对象有过改动，这个方法会返回 true。

if (textArea.isModified()) {
    textArea.commit();
}

支持此接口的组件：

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

Collapsable-可折叠接口

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

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

  支持此接口的组件：

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 优先级高，也就是说，如果点击处理函数设置了的话，默认的弹出小窗便不会显示。

textArea.setContextHelpIconClickHandler(contextHelpIconClickEvent ->
        dialogs.createMessageDialog()
                .withCaption("Title")
                .withMessage("Message body")
                .withType(Dialogs.MessageType.CONFIRMATION)
                .show()
);

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

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。

  用例示范：

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

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

• CollapseEvent，所属组件： TreeDataGrid，

• ColumnCollapsingChangeEvent，所属组件： DataGrid，

• ColumnReorderEvent，所属组件： DataGrid，

• ColumnResizeEvent，所属组件： DataGrid，

• ExpandedStateChangeEvent，所属组件： Filter 和 GroupBoxLayout (参阅 Collapsable)，

• ExpandEvent，所属组件： TreeDataGrid，

• SelectedTabChangeEvent，所属组件： TabSheet，

• SelectionEvent，所属组件： DataGrid，

• SelectionEvent，所属组件： Table，

• SortEvent，所属组件： DataGrid，

• SplitPositionChangeEvent，所属组件： SplitPanel，

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

HasValue-有值处理接口

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

  @Inject
  private TextField<String> textField;
  @Inject
  private Notifications notifications;
  @Subscribe
  protected void onInit(InitEvent event) {
      textField.addValueChangeListener(stringValueChangeEvent ->
              notifications.create()
                      .withCaption("Before: " + stringValueChangeEvent.getPrevValue() +
                              ". After: " + stringValueChangeEvent.getValue())
                      .show());
  }

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

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

也可参阅 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 接口的监听器拦截鼠标在组件区域点击事件。

  vbox.addLayoutClickListener(layoutClickEvent ->
      notifications.create()
              .withCaption("Clicked")
              .show());

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

  @Subscribe("vbox")
  protected void onVboxLayoutClick(LayoutClickNotifier.LayoutClickEvent event) {
      notifications.create()
              .withCaption("Clicked")
              .show();
  }

支持此接口的组件：

ButtonsPanel - BoxLayout - CssLayout - GridLayout

HasMargin-容器边距接口

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

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

    vbox.setMargin(true);

  • 只设置上边距和下边距：

    vbox.setMargin(true, false, true, false);

  • 创建 MarginInfo 配置类实例来设置边距：

    vbox.setMargin(new MarginInfo(true, false, false, true));

• getMargin() - 以 MarginInfo 实例的方式返回组件的边距设置。

支持此接口的组件：

BoxLayout - Filter - Frame - GridLayout ScrollBoxLayout

HasOuterMargin-组件外边距接口

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

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

    groupBox.setOuterMargin(true);

  • 只设置组件上下外边距：

    groupBox.setOuterMargin(true, false, true, false);

  • 创建 MarginInfo 配置类实例来设置外边距：

    groupBox.setOuterMargin(new MarginInfo(true, false, false, true));

• getOuterMargin() - 以 MarginInfo 实例的方式返回组件的外边距设置。

支持此接口的组件：

GroupBoxLayout

HasSpacing-留白接口

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

  vbox.setSpacing(true);

支持此接口的组件：

BoxLayout - ButtonsPanel - Frame - GridLayout GroupBoxLayout - ScrollBoxLayout

ShortcutNotifier-快捷键接口

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

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

支持此接口的组件：

BoxLayout - ButtonsPanel - CssLayout - GridLayout - GroupBoxLayout - ScrollBoxLayout