3.5.15.3.4. 创建 GWT 组件

在本节中，我们介绍如何创建一个简单的 GWT 组件（由 5 颗星组成的评级字段）及其在应用程序界面中的用法。

rating field component

在 CUBA Studio 中创建一个新项目，并将其命名为 ratingsample。

创建 web-toolkit 模块。一个简便的方法就是使用 CUBA Studio：在主菜单，点击 CUBA > Advanced > Manage modules > Create 'web-toolkit' Module。

为了创建 GWT 组件，需要创建下列文件：

  • RatingFieldWidget.java - web-toolkit 模块中的 GWT 部件。

  • RatingFieldServerComponent.java - Vaadin 组件类。

  • RatingFieldState.java - 组件状态类。

  • RatingFieldConnector.java - 连接器，用于连接客户端代码和服务器组件。

  • RatingFieldServerRpc.java - 为客户端定义服务器 API 的类。

现在创建需要的文件并对其进行必要的更改。

  • 在 web-toolkit 模块中创建 RatingFieldWidget 类。使用下面代码作为其内容：
  1. package com.company.ratingsample.web.toolkit.ui.client.ratingfield;
  3. import com.google.gwt.dom.client.DivElement;
  4. import com.google.gwt.dom.client.SpanElement;
  5. import com.google.gwt.dom.client.Style.Display;
  6. import com.google.gwt.user.client.DOM;
  7. import com.google.gwt.user.client.Event;
  8. import com.google.gwt.user.client.ui.FocusWidget;
  10. import java.util.ArrayList;
  11. import java.util.List;
  13. public class RatingFieldWidget extends FocusWidget {
  15.     private static final String CLASSNAME = "ratingfield";
  17.     // API for handle clicks
  18.     public interface StarClickListener {
  19.         void starClicked(int value);
  20.     }
  22.     protected List<SpanElement> stars = new ArrayList<>(5);
  23.     protected StarClickListener listener;
  24.     protected int value = 0;
  26.     public RatingFieldWidget() {
  27.         DivElement container = DOM.createDiv().cast();
  28.         container.getStyle().setDisplay(Display.INLINE_BLOCK);
  29.         for (int i = 0; i < 5; i++) {
  30.             SpanElement star = DOM.createSpan().cast();
  32.             // add star element to the container
  33.             DOM.insertChild(container, star, i);
  34.             // subscribe on ONCLICK event
  35.             DOM.sinkEvents(star, Event.ONCLICK);
  37.             stars.add(star);
  38.         }
  39.         setElement(container);
  41.         setStylePrimaryName(CLASSNAME);
  42.     }
  44.     // main method for handling events in GWT widgets
  45.     @Override
  46.     public void onBrowserEvent(Event event) {
  47.         super.onBrowserEvent(event);
  49.         switch (event.getTypeInt()) {
  50.             // react on ONCLICK event
  51.             case Event.ONCLICK:
  52.                 SpanElement element = event.getEventTarget().cast();
  53.                 // if click was on the star
  54.                 int index = stars.indexOf(element);
  55.                 if (index >= 0) {
  56.                     int value = index + 1;
  57.                     // set internal value
  58.                     setValue(value);
  60.                     // notify listeners
  61.                     if (listener != null) {
  62.                         listener.starClicked(value);
  63.                     }
  64.                 }
  65.                 break;
  66.         }
  67.     }
  69.     @Override
  70.     public void setStylePrimaryName(String style) {
  71.         super.setStylePrimaryName(style);
  73.         for (SpanElement star : stars) {
  74.             star.setClassName(style + "-star");
  75.         }
  77.         updateStarsStyle(this.value);
  78.     }
  80.     // let application code change the state
  81.     public void setValue(int value) {
  82.         this.value = value;
  83.         updateStarsStyle(value);
  84.     }
  86.     // refresh visual representation
  87.     private void updateStarsStyle(int value) {
  88.         for (SpanElement star : stars) {
  89.             star.removeClassName(getStylePrimaryName() + "-star-selected");
  90.         }
  92.         for (int i = 0; i < value; i++) {
  93.             stars.get(i).addClassName(getStylePrimaryName() + "-star-selected");
  94.         }
  95.     }
  96. }

部件（Widget）是一个客户端类，负责在 Web 浏览器中显示组件并处理浏览器事件。它定义了与服务端配合起来工作的接口。在这个的例子中，这些接口是 setValue() 方法和 StarClickListener 接口。

  • RatingFieldServerComponent 是一个 Vaadin 组件类。它定义了服务端代码 API、访问器方法、事件监听器和数据源连接。开发人员在应用程序代码中使用的是这个类的方法。
  1. package com.company.ratingsample.web.toolkit.ui;
  3. import com.company.ratingsample.web.toolkit.ui.client.ratingfield.RatingFieldServerRpc;
  4. import com.company.ratingsample.web.toolkit.ui.client.ratingfield.RatingFieldState;
  5. import com.vaadin.ui.AbstractField;
  7. // the field will have a value with integer type
  8. public class RatingFieldServerComponent extends AbstractField<Integer> {
  10.     public RatingFieldServerComponent() {
  11.         // register an interface implementation that will be invoked on a request from the client
  12.         registerRpc((RatingFieldServerRpc) value -> setValue(value, true));
  13.     }
  15.     @Override
  16.     protected void doSetValue(Integer value) {
  17.         if (value == null) {
  18.             value = 0;
  19.         }
  20.         getState().value = value;
  21.     }
  23.     @Override
  24.     public Integer getValue() {
  25.         return getState().value;
  26.     }
  28.     // define own state class
  29.     @Override
  30.     protected RatingFieldState getState() {
  31.         return (RatingFieldState) super.getState();
  32.     }
  34.     @Override
  35.     protected RatingFieldState getState(boolean markAsDirty) {
  36.         return (RatingFieldState) super.getState(markAsDirty);
  37.     }
  38. }
  • RatingFieldState 状态类定义客户端和服务器之间发送的数据。它包含在服务端自动序列化并在客户端上反序列化的公共字段。
  1. package com.company.ratingsample.web.toolkit.ui.client.ratingfield;
  3. import com.vaadin.shared.AbstractFieldState;
  5. public class RatingFieldState extends AbstractFieldState {
  6.     {   // change the main style name of the component
  7.         primaryStyleName = "ratingfield";
  8.     }
  9.     // define a field for the value
  10.     public int value = 0;
  11. }
  • RatingFieldServerRpc 接口定义了客户端可调用的服务器 API。它的方法可以由 Vaadin 内置的 RPC 机制调用。我们将在此组件中实现此接口。
  1. package com.company.ratingsample.web.toolkit.ui.client.ratingfield;
  3. import com.vaadin.shared.communication.ServerRpc;
  5. public interface RatingFieldServerRpc extends ServerRpc {
  6.     //method will be invoked in the client code
  7.     void starClicked(int value);
  8. }
  • 在 web-toolkit 模块中创建 RatingFieldConnector 类，连接器将客户端代码与服务端连接起来。
  1. package com.company.ratingsample.web.toolkit.ui.client.ratingfield;
  3. import com.company.ratingsample.web.toolkit.ui.RatingFieldServerComponent;
  4. import com.vaadin.client.communication.StateChangeEvent;
  5. import com.vaadin.client.ui.AbstractFieldConnector;
  6. import com.vaadin.shared.ui.Connect;
  8. // link the connector with the server implementation of RatingField
  9. // extend AbstractField connector
  10. @Connect(RatingFieldServerComponent.class)
  11. public class RatingFieldConnector extends AbstractFieldConnector {
  13.     // we will use a RatingFieldWidget widget
  14.     @Override
  15.     public RatingFieldWidget getWidget() {
  16.         RatingFieldWidget widget = (RatingFieldWidget) super.getWidget();
  18.         if (widget.listener == null) {
  19.             widget.listener = value ->
  20.                     getRpcProxy(RatingFieldServerRpc.class).starClicked(value);
  21.         }
  22.         return widget;
  23.     }
  25.     // our state class is RatingFieldState
  26.     @Override
  27.     public RatingFieldState getState() {
  28.         return (RatingFieldState) super.getState();
  29.     }
  31.     // react on server state change
  32.     @Override
  33.     public void onStateChanged(StateChangeEvent stateChangeEvent) {
  34.         super.onStateChanged(stateChangeEvent);
  36.         // refresh the widget if the value on server has changed
  37.         if (stateChangeEvent.hasPropertyChanged("value")) {
  38.             getWidget().setValue(getState().value);
  39.         }
  40.     }
  41. }

RatingFieldWidget 类中不定义组件的外观样式，只为关键元素指定样式名称。要定义组件的外观，需要创建样式表文件。简便方法就是使用 CUBA Studio：在主菜单，点击 CUBA > Advanced > Manage themes > Create theme extension。在弹窗中选择 hover 主题。另一个方法是使用 CUBA CLI 的 extend-theme 命令。hover 主题使用了 FontAwesome 的象形符号字体替代了 icons。

建议以 SCSS 混入(Mixin)的形式将组件样式放到 components/componentname 目录中的单独文件 componentname.scss 中。在 web 模块的 themes/hover/com.company.ratingsample 目录中创建 components/ratingfield 目录结构。然后在 ratingfield 目录中创建 ratingfield.scss 文件：

gwt theme ext structure

  1. @mixin ratingfield($primary-stylename: ratingfield) {
  2.   .#{$primary-stylename}-star {
  3.     font-family: FontAwesome;
  4.     font-size: $v-font-size--h2;
  5.     padding-right: round($v-unit-size/4);
  6.     cursor: pointer;
  8.     &:after {
  9.           content: '\f006'; // 'fa-star-o'
  10.     }
  11.   }
  13.   .#{$primary-stylename}-star-selected {
  14.     &:after {
  15.           content: '\f005'; // 'fa-star'
  16.     }
  17.   }
  19.   .#{$primary-stylename} .#{$primary-stylename}-star:last-child {
  20.     padding-right: 0;
  21.   }
  23.   .#{$primary-stylename}.v-disabled .#{$primary-stylename}-star {
  24.     cursor: default;
  25.   }
  26. }

将此文件包含在 hover-ext.scss 主题文件中：

  1. @import "components/ratingfield/ratingfield";
  3. @mixin com_company_ratingsample-hover-ext {
  4.   @include ratingfield;
  5. }

为了演示组件的工作原理，我们在 web 模块中创建一个新的界面。

将界面命名为 rating-screen。

在 IDE 中打开 rating-screen.xml 文件。Rating 组件需要一个容器，我们在界面 XML 中声明它：

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
  3.         caption="msg://caption"
  4.         messagesPack="com.company.ratingsample.web.screens.rating">
  5.     <layout expand="container">
  6.         <vbox id="container">
  7.             <!-- we'll add vaadin component here-->
  8.         </vbox>
  9.     </layout>
  10. </window>

打开 RatingScreen.java 界面控制器并添加将组件放置到界面上的代码。

  1. package com.company.ratingsample.web.screens.rating;
  3. import com.company.ratingsample.web.toolkit.ui.RatingFieldServerComponent;
  4. import com.haulmont.cuba.gui.components.VBoxLayout;
  5. import com.haulmont.cuba.gui.screen.Screen;
  6. import com.haulmont.cuba.gui.screen.Subscribe;
  7. import com.haulmont.cuba.gui.screen.UiController;
  8. import com.haulmont.cuba.gui.screen.UiDescriptor;
  9. import com.vaadin.ui.Layout;
  11. import javax.inject.Inject;
  13. @UiController("ratingsample_RatingScreen")
  14. @UiDescriptor("rating-screen.xml")
  15. public class RatingScreen extends Screen {
  16.     @Inject
  17.     private VBoxLayout container;
  19.     @Subscribe
  20.     protected void onInit(InitEvent event) {
  21.         RatingFieldServerComponent field = new RatingFieldServerComponent();
  22.         field.setCaption("Rate this!");
  23.         container.unwrap(Layout.class).addComponent(field);
  24.     }
  25. }

启动应用程序服务并查看结果。

rating screen result