文档帮助

目录

术语、图标和标签 访问级别 成员类型 成员语法 成员标志 类图标 成员图标 导航和功能 类成员快速导航菜单 Getter 和 Setter 方法 历史记录栏 搜索和过滤器 API 文档类元数据 展开和折叠示例及类成员 桌面 -vs- 移动视图 查看类源代码

术语、图标和标签

许多类在使用配置对象创建（实例化）类时都有快捷名称。快捷名称被称为 alias（别名）（如果类扩展了 Ext.Component，则为 xtype）。别名/xtype 列在适用类的类名旁边，以便快速参考。

访问级别

框架类或其成员可以指定为 private（私有）或 protected（受保护）。否则，类/成员为 public（公共）。Public、protected 和 private 是访问描述符，用于传达类或类成员应如何以及何时使用。

成员类型

成员语法

下面是一个类成员示例，我们可以剖析它以展示类成员的语法（在本例中是从 Ext.button.Button 类查看的 lookupComponent 方法）。

Ext.container.Container
查看源代码
lookupComponent ( item ) : Ext.Component
受保护

当原始配置对象添加到此容器时调用，无论是在初始化 items 配置期间，还是在新的项被 添加）或 {@link #insert 插入} 时。

此方法将传递的对象转换为实例化的子组件。

当需要对子组件创建应用特殊处理时，可以在子类中重写此方法。

参数

item :  Object

正在添加的配置对象。

返回值
Ext.Component

要添加的组件。

让我们看一下成员行的每个部分

成员标志

API 文档使用许多标志来进一步传达类成员的功能和意图。标签可以用文本标签、缩写或图标表示。

类图标

- 表示框架类

- 单例框架类。*有关更多信息，请参阅单例标志

- 组件类型框架类（Ext JS 框架中扩展 Ext.Component 的任何类）

- 表示类、成员或指南在当前查看的版本中是新的

成员图标

- 表示类型为 config（配置）的类成员

- 表示类型为 property（属性）的类成员

- 表示类型为 method（方法）的类成员

- 表示类型为 event（事件）的类成员

- 表示类型为 theme variable（主题变量）的类成员

- 表示类型为 theme mixin（主题混入）的类成员

- 表示类、成员或指南在当前查看的版本中是新的

类成员快速导航菜单

在 API 文档页面上的类名正下方是一行按钮，对应于当前类拥有的成员类型。每个按钮显示按类型划分的成员计数（此计数会随着应用过滤器而更新）。单击按钮会将您导航到该成员部分。将鼠标悬停在成员类型按钮上将显示该类型的所有成员的弹出菜单，以便快速导航。

Getter 和 Setter 方法

与类配置选项相关的 Getter 和 Setter 方法将显示在方法部分以及 API 文档和成员类型菜单的配置部分中，紧挨着它们所作用的配置下方。Getter 和 Setter 方法文档将在配置行中找到，以便于参考。

历史记录栏

您的页面历史记录保存在本地存储中，并在顶部标题栏正下方显示（使用可用空间）。默认情况下，显示的唯一搜索结果是与您当前查看的产品/版本匹配的页面。您可以通过单击历史记录栏右侧的 按钮并选择“全部”单选选项来展开显示的内容。这将显示历史记录栏中所有产品/版本的所有最近页面。

在历史记录配置菜单中，您还将看到最近页面访问的列表。结果按“当前产品/版本”和“全部”单选选项进行过滤。单击 按钮将清除历史记录栏以及本地存储中保存的历史记录。

如果在历史记录配置菜单中选择了“全部”，“在历史记录栏中显示产品详细信息”的复选框选项将启用。选中后，每个历史页面的产品/版本将与历史记录栏中的页面名称一起显示。将光标悬停在历史记录栏中的页面名称上也会以工具提示的形式显示产品/版本。

搜索和过滤器

可以使用页面顶部的搜索字段搜索 API 文档和指南。

在 API 文档页面上，还有一个过滤器输入字段，用于使用过滤器字符串过滤成员行。除了按字符串过滤外，您还可以按访问级别、继承和只读来过滤类成员。这是通过页面顶部的复选框完成的。

API 类导航树底部的复选框过滤类列表以包含或排除私有类。

单击空的搜索字段将显示您最近 10 次搜索，以便快速导航。

API 文档类元数据

每个 API 文档页面（JavaScript 原始类型页面除外）都有一个与该类相关的元数据菜单视图。此元数据视图将具有以下一项或多项

展开和折叠示例及类成员

可运行的示例 (Fiddles) 默认在页面上展开。您可以使用代码块左上角的箭头单独折叠和展开示例代码块。您还可以使用页面右上角的切换按钮切换所有示例的折叠状态。切换所有状态将在页面加载之间记住。

类成员默认在页面上折叠。您可以使用成员行左侧的箭头图标或右上角的展开/折叠全部切换按钮全局展开和折叠成员。

桌面 -vs- 移动视图

在较窄的屏幕或浏览器上查看文档将导致针对较小外形尺寸优化的视图。桌面和“移动”视图之间的主要区别在于

查看类源代码

可以通过单击 API 文档页面顶部的类名来查看类源代码。可以通过单击成员行右侧的“view source”（查看源代码）链接来查看类成员的源代码。

GXT 4.x


顶部

目录

参考 变更亮点 简介 设置 组件 布局 数据 绑定 存储 数据组件

Sencha GXT 2.x 到 4.x 迁移指南

本指南最适合从 Sencha GXT 2.x 迁移到 Sencha GXT 4.x 的用户。

参考

变更亮点

升级到 3.x+ 时将遇到的总体变化

  • 2.x 中的 setLayout 在 3.x 中变为特定的容器
  • 基于属性的模型数据移动到可序列化的普通旧 Java 对象。
    • Auto beans 可用于从 JSON 创建这些对象。
    • 2.x 中的 bean 模型由属性支持，但在 3.x 中不是，除非普通旧 java 对象实现了属性格式。
  • 外部 CSS 更改为性能更高的 CssResources。
  • 事件监听器更改为事件处理程序
  • gxtWidget.el() 变为 gxtWidget.getElement();

简介

Sencha GXT 4.x 是组件和工具的下一代产品，它与 GWT 编译器和运行时结合使用，使得构建大型可维护的基于浏览器的 Web 应用程序成为可能。作为此新版本的一部分，我们对 GXT 2.x 进行了一些更改，主要目标如下

  1. 更好地兼容当前和未来的 GWT 功能
  2. 更多地使用 GWT 最佳实践
  3. 开箱即用，简单易用，并且可以针对特定用例进行扩展
  4. 能够与 GXT 2 版本并排运行。

与 GXT 2 中一样，可以将单个模块继承到您的项目中以开始使用该库：com.sencha.gxt.ui.GXT。还创建了其他几个模块，以便可以自定义在特定情况下如何绘制小部件。通过不继承主 GXT 模块，您可以限制编译中包含的代码，并且可以更好地控制要构建的浏览器排列 - 可以为 IE6、7、8、9 以及不同版本的 Firefox 和 Chrome 与 Safari 构建排列 - 总共 13 个。默认情况下，当继承主 GXT 模块时，这些会折叠到默认的 GWT 排列 - IE6-7、IE8、IE9、Firefox 和 Safari/Chrome。

GXT 2 中提供的许多类和功能也存在于 3 中，尽管它们的名称可能已更改。有些不再可能或不合理地保留在 GXT 本身中，或者已被我们现在利用的 GWT 功能取代。一些不再存在的主要功能现在在旧版 jar 中可用，但预计不会继续获得改进，仅作为过渡到更现代的 GWT 技术的权宜之计。

为了方便大型项目的迁移，GXT 2 和 3 可以同时位于同一类路径中 - 基本包已从 com.extjs.gxt 更改为 com.sencha.gxt。这与旨在从 2.x 适应到 3.x 容器和布局的容器相结合，将允许项目在必要时逐步迁移。

设置

使用 GXT 所需的资源现在都在内部管理 - 不再需要保持资源目录的最新状态。相反，GWT ClientBundle 功能用于管理图像和样式表，确保它们作为编译项目的一部分存在。但是，仍然需要从主 html 页面链接到样式表 - 每个编译的项目都将有一个 reset.css 文件，用于规范化浏览器之间的差异。这应该从您的 html 页面链接。无需链接到 gxt-all.css 文件或任何其他 css 来加载特定主题，其他主题应在项目内完成，而不是使用外部文件。

由于 GXT 3 需要 GWT 2.4 或更高版本，并且 GWT 2.4 要求 html 页面具有严格的 doctype，因此 GXT 3 也需要严格的 doctype。这使我们能够确保浏览器将更一致地呈现内容。

或者

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

或者

<!DOCTYPE html>

可以在主机 html 页面中用作严格的 doctype。

将库添加到 GWT 项目 xml 模块配置

<inherits name='com.sencha.gxt.ui.GXT'/>

组件

组件的基本概念完全没有改变 - 它们扩展了 GWT 小部件，并提供了额外的行为和生命周期详细信息。组件不再延迟绘制其内容 - 这允许 GXT 小部件在 UiBinder 中更有效地工作，并且通常更容易使用。为了减轻由此可能导致的性能损失的担忧，请考虑 GWT 类 LazyPanel - 这允许一组小部件在需要之前保持不显示状态。GWT 也开始使用 PotentialElement 类 - 我们将关注此功能的开发，并在最终确定后使用它。

此更改的另一个结果是，现在只有极少数组件 setter 只能在渲染之前使用，并且没有只能在渲染后使用的 setter。

组件生命周期不再包括 ComponentPlugin 初始化过程：无论如何，大多数插件都不能添加到多个组件，并且将插件添加到组件和使用组件初始化插件之间的区别可以忽略不计。

GXT 3 事件现在基于 GwtEvent 类，从而提供与现有 GWT 库和项目更好的兼容性，以及在向对象添加处理程序（以前是监听器）时更好的类型安全性。不再有 Observable 接口，也没有 BaseObservable 类 - 可以改用 EventBus 实例，以及 Has*Handler 接口来声明可以从中触发事件的位置。

/** Declare a strongly typed handler for this specific event */
public interface CustomEventHandler extends EventHandler {
  /** The method may be named and typed for this event */
  public void onMyEvent(CustomEvent event);
}

/** Declare a new event object with whatever state it will convey */
public class CustomEvent extends GwtEvent<CustomEventHandler> {
  private GwtEvent.Type<CustomEventHandler> TYPE = new 
        GwtEvent.Type<CustomEventHandler>();
  public static GwtEvent.Type<CustomEventHandler> getType() {
    return TYPE;
  }

  @Override
  public GwtEvent.Type<CustomEventHandler> getAssocatedType() {
    return getType();
  }

  @Override
  protected void dispatch(CustomEventHandler handler) {
    /* Call the specific handler method to inform listeners that the event is happening */
    handler.onMyEvent(this);
  }
}

// Add a handler to an EventBus or HandlerManager for the specific event type
eventBus.addHandler(CustomEvent.getType(), new CustomEventHandler() {
  @Override
  public void onMyEvent(CustomEvent event) {
    // React to the event
  }
});

// The event can then be fired, and the handler will recieve it
eventBus.fireEvent(new CustomEvent());

XTemplates 现在在编译时生成，并创建 SafeHtml 实例，而不是返回 String 或应用于 Element。这使得它们可以在任何可以使用 SafeHtml 的地方使用，尤其是在 Grid 或其他数据组件的 Cells 中。它们还能够对任何具有属性访问器方法的对象进行操作，而无需首先将对象转换为 JavaScriptObject 实例。如果需要运行时模板，则旧的运行时 Template 和 XTemplate 类在旧版 jar 中可用。查看我们的 XTemplates 重新设计博客文章以获取更多详细信息。

XTemplates 更广泛地用于组件内部结构中进行渲染，通常是通过组件的外观。此修改通常会产生更高效的渲染，以及通过直接修改外观及其模板来更容易读取和修改任何组件的结构，而不是使用子类来删除或重新排列 dom 元素，这是一种成本更高的操作。

许多组件都由 Cell 实现支持，允许它们在接受 cell 的任何数据组件中渲染，包括 Grid、Tree、TreeGrid 和 ListView。这些 cell 反过来委托给外观实现，或者通过在其构造函数中给定一个实例，或者通过依赖于通常在主题模块中定义的重新绑定规则。然后，这些外观负责使用 XTemplates 和 ClientBundles 绘制内容，并将元素上发生的事件与应在此 Cell 或 Component 中启动的行为相关联。

Ext GWT 2 依赖于 El 类作为包装 dom 元素的一种方式，以有效地对其执行操作，使用享元模式来避免频繁的对象构造，同时仍然添加功能。在 GXT 3 中，引入了 XElement 类，它扩展自 JavaScriptObject 类 Element

布局

在 GXT 2.x 中，所有 Container 子类都可以分配 Layout 实例，无论是在内部还是在外部。大多数子类也支持使用与其关联的布局数据添加小部件或组件的功能。很少能做到要求特定小部件具有正确类型的数据或任何数据。

为了帮助使编写和理解更容易，并促进 UiBinder 声明的布局，不再有 Layout 类，但容器声明它们将如何绘制其子项，并在可能的情况下提供强类型添加方法。某些布局不再是必需的，例如 FitLayout - 现在可以使用它的任何情况通常都已经知道如何将单个子项调整为其自身大小，例如 ContentPanel、Window 或 Dialog；或者 FormLayout - 随着 FieldLabel 的创建，能够接受任何小部件作为其内容，FormLayout 不提供任何有意义的价值。其他布局的名称已更改 - RowLayout 已变为 HorizontalLayoutContainer 或 VerticalLayoutContainer，具体取决于要使用的方向，而 ColumnLayout 已变为 CssFloatLayoutContainer。

Sencha GXT 2.x

Sencha GXT 4.x

描述

FlowLayout

FlowLayoutContainer

允许 HTML/CSS 规则定义如何绘制子项

FitLayout

N/A

将一个项目适配到其父级的大小 - 对于不应用布局的父级，GXT 3 中不需要

RowLayout

VerticalLayoutContainer

根据布局数据在垂直堆叠中基于父级分配的大小调整子项的大小和位置

HorizontalLayoutContainer

根据布局数据在水平行中基于父级分配的大小调整子项的大小和位置

ColumnLayout

CssFloatLayoutContainer

根据布局数据设置每个子项的宽度，但允许由 HTML/CSS 浮动规则确定位置和高度

BorderLayout

BorderLayoutContainer

在父级的五个不同区域中定位和调整子项的大小。首先处理位于边缘周围的子项，中心获得剩余空间。可以为此布局启用额外的装饰和用户启动的大小调整

CenterLayout

CenterLayoutContainer

在父级内定位所有子项，以便它们基于父级和子级大小居中

CardLayout

CardLayoutContainer

调整所有子项的大小和位置，使其与父级大小相同，但一次只允许一个可见

HBoxLayout

HBoxLayoutContainer

将子项定位为单个水平行，并支持自动溢出（当有太多小部件无法在可用宽度中显示时）

VBoxLayout

VBoxLayoutContainer

将子项定位为单个水平列

FormLayout

N/A

使用 FieldLabel 实例产生相同的效果

AccordionLayout

AccordionLayoutContainer

ContentPanel 子项一次显示一个，标题堆叠在一起，允许用户选择要显示的面板。默认为调整可见子项的大小以适应可用空间。

HtmlLayoutContainer

基于给定 html 主体中的 css 查询定位子项。不对子项执行大小调整。

NorthSouthLayoutContainer

最多三个子项的专用容器，定位它们，使顶部和底部占用它们需要的空间，而中心占用分配给父级的剩余大小。

2.x 和 4.x 中的布局

数据

在 GXT 2.x 中，提供了几个模型对象接口和基类，例如 ModelData、TreeModel、BaseModelData。这些类型允许一种伪反射，通过使每个模型负责跟踪从 String 键到它引用的属性的映射。这可能会使使用现有 POJO bean 和以类型安全的方式编写代码变得困难。当 AutoBeans 和 RequestFactory 发布时，很难有效地使用它们。

GXT 4.x 支持任何类似 bean 的对象，通过其 XTemplates 和 PropertyAccess（一种生成 ValueProvider 实例的机制）使用公共访问器（getter 和 setter）。ValueProvider 是一种以通用方式处理从模型外部更改和读取值的问题的方法

ValueProvider<Person, String> firstName, lastName;
Person p;

String f = firstName.getValue(p);
String l = lastName.getValue(p);

通过保持对这些属性的外部访问，模型不需要从任何基类扩展或使用任何接口。所有数据小部件和存储都使用 ValueProvider 来读取和写入值，XTemplates 也使用它们。

有时需要从模型中读取值，并将其用作存储中的键或 UI 中的标签——为此目的声明了只读接口，即 LabelProvider 和 ModelKeyProvider。PropertyAccess 也能够生成这些接口。可以为给定的路径 [d] 创建多个提供程序，但可以使用 @Path 注解指定不同的名称。@Path 注解也可以用于引用嵌套属性——在 GXT 2 中，可以写成 model.get("owner.firstName")，而在注解中则应写成 @Path("owner.firstName")。

作为支持任意模型对象的更改的一部分，我们还贯穿整个库，加强了泛型的使用，使其尽可能具体和一致。在某些地方，这导致了有些复杂的泛型，但好处是，如果所有泛型实例都设置正确，则不应该出现类转换异常，并且关于模型如何创建和传递也绝不会有混淆[e]。

泛型参数名

典型含义

M

模型对象

C

配置对象，通常在加载数据时传递给服务器

V

值，通常是 M 的属性

D

数据，通常通过网络传输，不直接被模型消费类使用[f]

T, X

其他所有情况，请务必参考 Javadoc

GXT 3 中泛型参数指南

绑定

随着强类型 GWT Editor 框架的引入，对 GXT 特定框架的需求有所降低。Bindings 和 FieldBindings 类在旧版 jar 中仍然可用，但 Field 和其他表单类现在实现了各种 Editor 接口，而不是期望 FormBinding 对象来包装它并提供要绑定的字符串。字段仍然支持处理和报告本地错误，但现在作为 GWT Editor 框架的一部分，它们可以显示在字段本身之外报告的错误，并且还可以将错误传递给编辑器驱动程序。

在 GXT 2 中使用的 Converter 类型，用于在 FieldBinding 中转换值，然后再将其设置到字段上，并在从字段中读取到模型后进行转换，它仍然存在，并且已被制成带有泛型的接口，以确保它与预期类型匹配。它可以与 Editor 框架一起使用，通过使用 ConverterEditorAdapter。这需要几个泛型参数，以确保驱动程序获得所有正确的详细信息——属性的实际类型、字段旨在编辑的类型以及要使用的实际字段类型。

存储

Store、ListStore 和 TreeStore 类已经过清理和更新。它们现在支持任何对象，前提是有办法为每个模型获取键。ModelKeyProvider 实例是强制性的，这与 2.x 不同，但此更改使存储在运行时少了一个可能的代码路径。这一点，加上对这些类进行仔细的重写和审查，应该使它们的性能显著提高，尤其是在内容在已被过滤和/或排序的情况下被更改时。

ListStore 中的一些方法已被重命名，以更符合 java.util.List——clear()、addAll(Collection)、get(int) 以及更多方法已被更改，以使存储在操作当前过滤器和排序选项时更加灵活。

鉴于支持任何 POJO bean 和 ValueProvider 的任何实现，Records 已经略有更改。可以通过调用 store.setAutoCommit(true) 完全忽略它们，以便立即对 bean 进行更改；或者，如果 autoCommit 为 false，则更改将排队在 Record 对象中，直到它们被提交或拒绝。这与 2.x 不同，在 2.x 中，更改会立即对底层模型进行，但原始值会被持久化。这有几个原因

  1. 在对象上调用 setter 可能会有副作用，因为可以使用任何实现，而不是始终通过 Map 支持模型。此外，由于 ValueProvider 只是一个接口，setValue 方法可能对其模型之外进行其他更改。
  2. 允许对象具有没有 getter 的 setter，因此在某些情况下将无法知道要恢复的原始值——这种情况不会经常出现，但在尝试还原时会导致异常。
  3. ListStore 可以使用 ListStoreEditor 类绑定到 Editor 中的 List 属性，并且 Editor 约定要求在调用 flush 之前不进行更改。这使得 ListStore 可以在 Editor 中更干净地使用。

TreeStore 的修改方式与 Store 和 ListStore 类似，可以接受任何对象，并通过方法而不是作为模型本身的属性来公开树结构。除了更好的性能特性和可用的泛型之外，这意味着对象不希望描述自己的结构，尽管允许它们通过实现 TreeNode递归地实现。然后，这些节点应通过 addSubTree 和 replaceSubTree 方法添加到 TreeStore 中。此结构不会自动修改——要获取完整的当前结构，请使用 getSubTree 方法并迭代结果。

数据小部件

GXT 3 中的数据小部件的操作方式与 2.x 中的基本相同——它们被提供一个 Store，从中获取数据（在某些情况下持久化更改），并且具有用于显示数据的灵活选项。主要更改围绕使用 ValueProvider 读取内容、使用 Cell 显示内容以及使用外观模式来修改数据小部件通常如何收集其数据。

每个数据小部件都可以提供一个 Cell 实例来委托渲染，在某些情况下，例如 Grid 和 TreeGrid，可以使用多个 Cell。通常，每个 Cell 通过 ValueProvider 映射到当前正在渲染的模型的单个属性，或模型本身。在模型本身正在被编辑的情况下，可以使用 IdentityValueProvider，它始终返回模型本身，以便传递给 Cell 进行渲染。

在 Ext GWT 2 中，Grid 单元格由 GridCellRenderer 实例渲染，返回 String 或 Widget 实例。如果使用 Widget，则将为每一行创建一个实例，这对于许多行来说可能会变得非常昂贵。Cells 通过使用单个实例来绘制所有行来解决这个问题，并处理所有逻辑，并具有足够的上下文来确切地知道每个特定用户交互发生的位置和方式。这带来了高效、响应迅速的显示，即使对于大量数据也是如此——请查看我们完全加载的 Cell Grid 示例以了解这一点。

大多数返回 HTML 的 CellGridRenderer 都可以轻松转换为 Cells，尤其是在 XTemplates 的帮助下。在 2.x 中返回库存 Ext GWT 组件的 Renderers 现在可以被匹配的 Cells 替换，因为大多数 GXT 3 组件都有一个 Cell，实际上用于执行其渲染并处理其事件。并且编写新的自定义 Cells 非常简单，并且将比为每一行绘制小部件产生性能更好的应用程序。

GXT 4.x