文档帮助

术语、图标和标签

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

访问级别

框架类或其成员可以指定为 privateprotected。否则,该类/成员为 publicPublicprotectedprivate 是访问描述符,用于传达应如何以及何时使用类或类成员。

成员类型

成员语法

下面是一个类成员示例,我们可以对其进行剖析,以展示类成员的语法(在本例中,是从 Ext.button.Button 类查看的 lookupComponent 方法)。

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 方法文档将在配置项行中找到,以方便参考。

历史记录栏

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

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

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

搜索和过滤器

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

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

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

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

API 文档类元数据

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

展开和折叠示例和类成员

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

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

桌面视图与移动视图

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

查看类源代码

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

GXT 4.x


顶部

日志记录

当仅仅拥有出色的调试器和良好的测试覆盖率还不够时,使用 GXTLogging 进行日志记录可以成为应用程序调试工具箱中非常宝贵的工具。随着应用程序变得更加复杂,日志记录可能会非常方便,因此您可以查看由于看似不相关的逻辑和事件而可能正在发生的其他交互。日志记录对于其他流程也很有用,例如在仍在编写代码时获得关于可能错误的反馈、衡量应用程序各个部分的性能以及跟踪应用程序的使用方式。

当大型原子对撞机喷出大量数据时,它们使用假设来深入挖掘和过滤数据。日志记录也是如此:除非在编写源代码时提出假设,否则日志记录看起来会像噪音。在编写应用程序时心中牢记这个目标将使您能够生成稍后在您想要过滤应用程序生成的输出时会有帮助的日志记录详细信息。

GWT 中的日志记录

GWT 中内置了三种主要的日志记录机制,每种机制都有略有不同的目的和用例

  • GWT.log 仅用于开发模式。当调用时,它会将消息添加到开发模式控制台。有两种可以调用的方法,log(String) 和 log(String, Exception)。前者将简单文本作为信息语句写出,后者作为错误写出,并且在选择消息时绘制异常的完整堆栈跟踪。现在 Super Dev Mode 开始被采用,这种情况正在减少,因为这些消息不会显示出来。

  • 轻量级日志记录系统旨在成为一种低级别、特定于 Web 模式的机制,用于跟踪诸如应用程序启动、简单性能指标之类的详细信息,并且可以在无需重新编译应用程序的情况下启用或禁用。这意味着这些日志语句永远不会编译出来,因此应谨慎使用。

  • Java 日志记录工具在 GWT 中部分模拟,允许访问您通常在非 GWT Java 代码中拥有的大多数相同调用。这可以在开发或 Web 模式下使用,并且您的模块中有许多配置选项,因此您可以决定日志记录应去向何处。本文将重点介绍此工具。

java.util.logging

java.util.logging 工具在客户端和服务器上的行为相同 — 实例可以从对 Logger.getLogger(String) 的调用中检索,应给出当前类名的名称,并且通常保存在私有静态 final 字段中,以避免每次需要时获取或创建新的记录器。

如果您的项目包含 GXT,则日志记录已存在但完全禁用。日志记录在 com.sencha.gxt.core.Core 模块中启用 — 此行将必要的类添加到项目中,但强制它们全部完全编译出来

<inherits name="com.google.gwt.logging.LoggingDisabled" />

要启用日志记录,请添加此定义并将 value 标志设置为 true。可能的值为 TRUE 或 FALSE — 使用上面的 LoggingDisabled inherits 语句(或您应用程序中的 GXT),以下是如何启用日志记录

<set-property name="gwt.logging.enabled" value="TRUE"/>

有七个可用的日志记录级别:severe、warning、info、config、fine、finer、finest。该列表中的级别越高,消息就越重要 — 大多数日志记录配置显示前两个级别,其余级别通常会被省略,除非在特定情况下。

<set-property name="gwt.logging.logLevel" value="INFO"/>

接下来,有日志记录处理程序,GWT 使用这些机制来显示或持久化记录的消息。通常在服务器上,您会将日志消息写入一个或多个文件,但在客户端我们没有这种能力,因此我们需要更谨慎地选择如何获取日志消息。这些分为几个类别,可以单独启用或禁用

  • 特定于开发模式 - 这些仅在开发模式下工作,因为它们使用 GWT.log 或 Java 控制台来发出消息

      <set-property name="gwt.logging.systemHandler" value="ENABLED" />
      <set-property name="gwt.logging.developmentModeHandler" value="ENABLED" />
    
  • 浏览器控制台 - Firebug、Chrome 的 Inspector、IE 的 Developer Toolbar 等。这些在 Web 或开发模式下在浏览器中显示消息,但除非用户直接打开其中一个控制台,否则不可见。

      <set-property name="gwt.logging.consoleHandler" value="ENABLED" />
      <set-property name="gwt.logging.firebugHandler" value="ENABLED" />
    
  • 浏览器弹出窗口 - 这个想法可能有助于使用户能够查看日志中的内容,尽管默认实现始终在大多数 GWT 和 GXT 小部件下方呈现,因此通常不是很有用;稍后对此进行更多介绍。

  • 最后,服务器 - 我们可以将消息发送到服务器,并要求它像往常一样记录它们以供稍后查看。此选项使您可以将日志保存到文件,但请记住,所有用户都将一起记录到同一个文件。这是默认情况下禁用的唯一选项,因为它需要正确配置的服务器来接收这些日志,使用 com.google.gwt.logging.shared.RemoteLoggingService RPC 接口。

      <set-property name="gwt.logging.simpleRemoteHandler" value="DISABLED" />
    

示例应用程序

这是一个示例,其中使用了大多数日志记录默认设置。所有浏览器和开发模式控制台均已使用,远程日志记录保持禁用状态,并且弹出窗口已禁用,因为它不能很好地与 GXT 配合使用。日志级别设置为 FINEST 以报告所有可能的消息,此外,还告知 GXT 本身发出所有内部详细信息。

<!-- In the Project.gwt.xml file, after the GXT inherits statement -->
<!-- Ask for all possible messages -->
<set-property name="gwt.logging.logLevel" value="FINEST" />
<!-- Write messages to browser consoles and to the jvm and dev mode -->
<!-- Note that these are the defaults, so we don’t actually need to list them -->
<set-property name="gwt.logging.consoleHandler" value="ENABLED" />
<set-property name="gwt.logging.firebugHandler" value="ENABLED" />
<set-property name="gwt.logging.developmentModeHandler" value="ENABLED" />
<set-property name="gwt.logging.systemHandler" value="ENABLED" />
<!-- Disable the popupHandler when using GXT layouts, they draw above -->
<set-property name="gwt.logging.popupHandler" value="DISABLED" />
<!-- Leave RPC logging disabled, as we aren’t setting that up in this example -->
<set-property name="gwt.logging.simpleRemoteHandler" value="DISABLED" />
<!-- Ask GXT to log all internal details -->
<set-property name="gxt.logging.enabled" value="true" />

以下是一个简单的记录器示例。首先实例化记录器,稍后调用 logger.log(...) 以根据应用程序模块中选择的选项生成日志记录输出。

    // Example using logging
    public class TestLogging implements EntryPoint {
      // instantiates a logger
      private static final Logger logger = Logger.getLogger(TestLogging.class.getName());

      @Override
      public void onModuleLoad() {
        logger.log(Level.INFO, "Phase A: So far so good.");
        logger.log(Level.WARNING, "Did this forget something?");

        TextField field = new TextField();
        String value;
        try {
          value = field.getValueOrThrow();
        } catch (ParseException e) {
          logger.log(Level.SEVERE, "Field Error", e);
        }

        if (logger.isLoggable(Level.INFO)) {
          // Anything in this statement will not get compiled when logging is off.
          logger.warning("Do something extra while logging.");
        }

        if (GXTLogConfiguration.loggingIsEnabled()) {
          // Anything in this statement will not get compiled when logging is off.
          logger.info("Do something GXT logging is on.");
        }
      }
    }

更多配置

通过完全禁用或启用日志记录功能,您是在告诉编译器要么保留所有日志语句,要么完全删除它们。日志级别不太具体;即使您将日志级别设置为 WARN,正如在非 GWT Java 中一样,某些代码可能会通过调用 Logger.getLogger("").setLevel(Level.FINEST) 将其改回 FINEST。这进一步使您能够为应用程序的不同部分设置不同的日志级别。以相同的方式,您可以为特定的记录器指定处理程序,为内部代码设置一个日志级别,为第三方代码设置另一个日志级别,等等。但是,一旦日志记录被禁用,该代码应完全编译出来。

构建您自己的日志处理程序

构建您自己的处理程序只是实现 java.util.logging.Handler 并使用数据执行某些操作的问题。这是 GXT 中的一个示例,它生成一个 Grid,可以将其添加到应用程序的一部分以显示所有日志消息。请注意,在将处理程序添加到记录器(在本例中,可能是根记录器)之前,它不会开始记录已记录的消息。

public class GridHandler extends Handler implements IsWidget {
  public interface LogRecordProperties extends PropertyAccess<LogRecord> {
    @Path("millis")
    ModelKeyProvider<LogRecord> key();

    ValueProvider<LogRecord, String> message();
    ValueProvider<LogRecord, String> loggerName();
    ValueProvider<LogRecord, Long> millis();
    ValueProvider<LogRecord, Level> level();
  }

  private static final LogRecordProperties properties = GWT.create(LogRecordProperties.class);
  protected final ListStore<LogRecord> store = new ListStore<LogRecord>(properties.key());
  private Grid<LogRecord> grid;

  public GridHandler() {
    grid = getLogRecordGrid(getLogRecordColumnModel(getColumnConfigs()));
  }

  @Override
  public void publish(LogRecord logRecord) {
    store.add(logRecord);
  }

  // these methods do nothing, since we don't need to think about files
  @Override
    public void flush() {
  }

  @Override
    public void close() {
  }

  @Override
    public Widget asWidget() {
    return grid;
  }

  private Grid<LogRecord> getLogRecordGrid(ColumnModel<LogRecord> columnModel) {
    Grid<LogRecord> grid = new Grid<LogRecord>(store, columnModel);
    grid.getView().setForceFit(true);
    return grid;
  }

  private ColumnModel<LogRecord> getLogRecordColumnModel(List<ColumnConfig<LogRecord, ?&gt;> columns) {
    return new ColumnModel<LogRecord>(columns);
  }

  protected List<ColumnConfig<LogRecord, ?&gt;> getColumnConfigs() {
    List<ColumnConfig<LogRecord, ?&gt;> columns = new ArrayList<ColumnConfig<LogRecord, ?&gt;>();
    columns.add(new ColumnConfig<LogRecord, String>(properties.loggerName(), 10, "Logger"));
    columns.add(new ColumnConfig<LogRecord, Level>(properties.level(), 10, "Level"));
    columns.add(new ColumnConfig<LogRecord, String>(properties.message(), 10, "Message"));
    columns.add(new ColumnConfig<LogRecord, Date>(new LongToDateValueProvider<LogRecord>(properties.millis()), 10, "Timestamp"));
    return columns;
  }

  public void clear() {
    store.clear();
  }

  public static class LongToDateValueProvider<M> implements ValueProvider<M, Date> {
    private final ValueProvider<M, Long> base;

    public LongToDateValueProvider(ValueProvider<M, Long> base) {
      this.base = base;
    }

    @Override
    public String getPath() {
      return base.getPath();
    }

    @Override
    public Date getValue(M object) {
      return new Date(base.getValue(object));
    }

    @Override
    public void setValue(M object, Date value) {
      base.setValue(object, value.getTime());
    }
  }
}

结论

日志记录添加了额外的流程输出信息,这可以提供非常宝贵的流程信息,无论是在开发期间、开发之后还是在调试期间。它可以完全编译出来,也可以添加回去以协助生产环境中的调试,并且可以为您的特定应用程序进行自定义,以准确地呈现您需要的详细信息。

延伸阅读

GWT 日志记录

GXT 4.x