GXT 外观设计

本指南与 GXT 3.0+ 最相关。

在 GXT 2.0 中，小部件负责直接创建其 DOM 结构。这可以通过手动创建元素或使用 HTML 片段来完成。HTML 可以直接生成，也可以使用 XTemplate 生成。然后，CSS 类名由小部件应用于元素。使用这种方法，小部件的视图与小部件本身紧密结合，并且 CSS 类名通常硬编码到小部件中。

虽然这种方法有效，但存在一些限制。首先，更改组件的 DOM 结构非常困难，因为小部件与其当前的 DOM 结构紧密结合。其次，更改小部件的样式或外观也很困难，因为 CSS 样式是小部件的一部分，并且直接添加到小部件的元素中。

GXT 3.0 引入了一种渲染视图和设置小部件样式的新方法。这种方法非常灵活，并且比以前的方法有很多优点。它支持使用不同的样式交换不同的 DOM 结构（标记）。

该设计围绕一个名为外观的概念展开，该概念基于 Google 引入的新设计。外观只是一个类，它控制小部件的视图实现的 HTML 结构和样式。外观是一种设计模式，而不是具体的实现。 有关 GWT 外观模式的更多信息。

展示外观如何工作的最佳方法是逐步介绍一个示例。有很多移动部件，但一旦您熟悉这些概念，它就非常简单明了。

首先，我们创建一个简单的小部件，该小部件手动创建其 DOM，并且 CSS 类名在小部件中分配。

• 组件示例

    public class PushButton extends Component implements HasClickHandlers {
      private Element imageWrap;
      private Element textWrap;
  
      public PushButton(String text) {
        setElement(DOM.createDiv());
  
        imageWrap = DOM.createDiv();
        imageWrap.setClassName("testImage");
        getElement().appendChild(imageWrap);
  
        textWrap = DOM.createDiv();
        textWrap.setClassName("testText");
        getElement().appendChild(textWrap);
  
        setText(text);
        setStyleName("testButton");
        sinkEvents(Event.ONCLICK);
      }
  
      public void setText(String text) {
        textWrap.setInnerText(text);
      }
  
      public void setIcon(Image icon) {
        imageWrap.setInnerHTML("");
        imageWrap.appendChild(icon.getElement());
      }
  
      @Override
      public HandlerRegistration addClickHandler(ClickHandler handler) {
        return addDomHandler(handler, ClickEvent.getType());
      }
    }
  
    public class Test implements EntryPoint {
      @Override
      public void onModuleLoad() {
        PushButton button = new PushButton("Click Me");
        button.setIcon(new Image(ExampleImages.INSTANCE.add16()));
        button.setWidth(100);
        button.addClickHandler(new ClickHandler() {
            @Override
            public void onClick(ClickEvent event) {
                Info.display("Message", "The button was clicked");
            }
        });
        RootPanel.get().add(button);
      }
    }
  

• CSS 示例

    .testButton {
      border: 1px solid navy;
      font-size: 12px;
      padding: 4px;
    }
  
    .testButton .testImage {
      float: left;
    }
  
    .testButton .testText {
      text-align: center;
    }
  

这是小部件的屏幕截图：

PushButton 是一个简单的小部件，它显示图标和文本，并在触发时触发 click 事件。在构造函数中，我们手动创建 DOM 元素并分配 CSS 类名。

虽然这种方法有效，但存在一些问题。首先，由于小部件直接创建 DOM，因此更改外观非常困难。此外，小部件直接与元素交互，例如 setText 方法。此外，小部件的 CSS 位于外部 CSS 文件中。如果 CSS 可以是 GWT CssResource 的一部分，以利用 CssResource 提供的优化和功能，那就更好了。

现在，让我们以这个示例为例并应用外观设计。

定义外观接口

第一步是创建一个接口，该接口定义小部件和外观实例之间的交互。

public interface ExampleAppearance {
  void render(SafeHtmlBuilder sb);
  void onUpdateText(XElement parent, String text);
  void onUpdateIcon(XElement parent, Image icon);
}

当父小部件调用 render 方法时，外观会返回小部件的 HTML 标记。这是通过 SafeHtmlBuilder 实例完成的，该实例有助于从文本片段构建 XSS 安全的 HTML。当外观需要更新按钮的文本和图标时，将调用 onUpdateText 和 onUpdateIcon 方法。

实现外观接口

接下来，我们创建外观接口的默认实现。

public static class DefaultAppearance implements Appearance {
  public interface Template extends XTemplates {
    @XTemplate(source = "DefaultAppearance.html")
    SafeHtml template(Style style);
  }

  public interface Style extends CssResource {
    String testButton();
    String testButtonText();
    String testButtonImage();
  }

  private final Style style;
  private final Template template;

  public interface Resources extends ClientBundle {
    @Source("DefaultAppearance.css")
    Style style();
  }

  public DefaultAppearance() {
    this((Resources) GWT.create(Resources.class));
  }

  public DefaultAppearance(Resources resources) {
    this.style = resources.style();
    this.style.ensureInjected();

    this.template = GWT.create(Template.class);
  }

  @Override
  public void onUpdateIcon(XElement parent, Image icon) {
    XElement element = parent.selectNode("." + style.testButtonImage());
    element.removeChildren();
    element.appendChild(icon.getElement());
  }

  @Override
  public void onUpdateText(XElement parent, String text) {
    parent.selectNode("." + style.testButtonText()).setInnerText(text);
  }

  @Override
  public void render(SafeHtmlBuilder sb) {
    sb.append(template.template(style));
  }
}

默认外观有很多部分。让我们逐步了解它们

定义外观样式

我们定义了 Style 接口，它是 CssResource。我们将定义组件将使用的 CSS。通过使用 CssResource，我们将 CSS 直接与我们的组件关联，而不是引用从外部样式表提取的样式。CSS 将被最小化和混淆。此外，CSS 将成为应用程序下载的一部分，而不是通过额外的 HTTP 请求检索。如果应用程序不使用此小部件，则 CSS 将不会成为下载的一部分。与以前版本的 GXT 中使用的单片 CSS 文件相比，这是一个巨大的改进。

public interface Style extends CssResource {
  String testButton();
  String testButtonText();
  String testButtonImage();
}

定义外观资源

接下来，我们创建一个 ClientBundle 子类，它将提供我们小部件需要的任何资源。

public interface Resources extends ClientBundle {
  @Source("DefaultAppearance.css")
  Style style();
}

DefaultAppearance 的 CSS 与我们的第一个示例使用的 CSS 相同。

使用 XTemplate 渲染标记

外观使用 XTemplate 生成 DOM 结构。XTemplate 传递一个 Style 实例以应用于标记。

• XTemplate 示例

    public interface Template extends XTemplates {
      @XTemplate(source = "DefaultAppearance.html")
      SafeHtml template(Style style);
    }
  

• XTemplate 外部源示例

    <!-- file: ./DefaultAppearance.html -->
    <div class="{style.testButton}">
      <div class="{style.testImage}"></div>
      <div class="{style.testText}"></div>
    </div>    
  

请注意类名是如何从传递给模板的 Style 实例中提取的。这很重要，因为实际的 CSS 类名将被混淆。此外，{style.styleMethodName} 源自 CSSResources 样式。我们喜欢使用辅助类 StyleInjectorHelper.ensureInjected(this.style, true); 立即注入该 CSS。如果首先不注入 CSSResource，有时会导致样式计算错误。

实现外观构造函数

然后我们创建两个构造函数，一个接受外观实例，另一个创建默认外观实例。

使用 GWT.create 非常重要，因为它允许使用延迟绑定规则指定不同的 Resource 实例。

public DefaultAppearance() {
   this((Resources) GWT.create(Resources.class));
}

public DefaultAppearance(Resources resources) {
   this.style = resources.style();
   this.style.ensureInjected();
   this.template = GWT.create(Template.class);
}

接下来，我们使用 GWT.create() 创建我们的 Template 实例。

外观实现细节

我们实现了外观接口的方法。

@Override
public void onUpdateIcon(XElement parent, Image icon) {
  XElement element = parent.selectNode("." + style.testButtonImage());
  element.removeChildren();
  element.appendChild(icon.getElement());
}

@Override
public void onUpdateText(XElement parent, String text) {
  parent.selectNode("." + style.testButtonText()).setInnerText(text);
}

@Override
public void render(SafeHtmlBuilder sb) {
  sb.append(template.template(style));
}

render 方法使用 XTemplate 生成 HTML 标记。text 和 image 方法是通过针对传递给方法的父元素来实现的。

外观不会传递父小部件，也不应维护状态，因此它们可以重用，也可以在没有父小部件的情况下使用，例如在 GWT Cells 中。例如，您可能希望将推送按钮插入到网格单元中。

现在我们已经定义了外观并有了具体的实现，我们可以实现小部件。

private final Appearance appearance;

public AppearancePushButton(String text) {
  this(text, (Appearance) GWT.create(DefaultAppearance.class));
}

public AppearancePushButton(String text, Appearance appearance) {
  this.appearance = appearance;

  SafeHtmlBuilder sb = new SafeHtmlBuilder();
  this.appearance.render(sb);

  setElement(XDOM.create(sb.toSafeHtml()));
  setText(text);
  sinkEvents(Event.ONCLICK);
}

@Override
public HandlerRegistration addClickHandler(ClickHandler handler) {
  return addDomHandler(handler, ClickEvent.getType());
}

public void setText(String text) {
  appearance.onUpdateText(getElement(), text);
}

public void setImage(Image icon) {
  appearance.onUpdateIcon(getElement(), icon);
}

您会注意到，小部件不直接绑定到外观的 DOM 或样式。相反，小部件将其视图工作委托给外观。

现在，使用延迟绑定或直接绑定，PushButton 可以与不同的外观一起使用。有几个原因需要有多个外观

不同的浏览器功能。您可能有一个使用 CSS3 渐变和 CSS3 圆角的外观，以及一个使用图像和不同 DOM 结构的不同外观，以看起来与 CSS3 版本相同。

您可以为不同的设备（如桌面和移动设备）设置不同的外观。这很棒，因为您可以拥有一个在桌面和浏览器中都工作的小部件，而不是拥有两个不同的组件。

主题也受支持。主题模块可以覆盖小部件使用的默认样式或标记。

总结

外观设计是一种非常灵活的方式来生成小部件的视图。自定义可以在三个级别进行

• 不同的外观。
• 外观内不同的资源。
• 外观内不同的 XTemplate。
• 所有三个维度都可以使用延迟绑定规则和编程方式进行控制。

一个示例规则可能如下所示

<replace-with class="PushButton.CustomAppearance">
<when-type-is class="PushButton.Appearance">
<any>
<when-property-is name="user.agent" value="ie6">
<when-property-is name="user.agent" value="ie8">
</when-property-is></when-property-is></any>
</when-type-is></replace-with>

我们正在将外观模式应用于库中的所有小部件。这将带来更好的性能和自定义可能性。