文档帮助

术语、图标和标签

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

访问级别

框架类或其成员可以指定为privateprotected。否则,类/成员为publicPublicprotectedprivate是访问描述符,用于传达类或类成员的使用方式和时间。

成员类型

成员语法

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

lookupComponent ( item ) : Ext.Component
protected

当在items配置的初始化期间或添加新项目时,将原始配置对象添加到此容器时调用added), or {@link #insert inserted.

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

当需要对子项创建应用特殊处理时,可以在子类中覆盖此方法。

参数

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 文档页面顶部的类名称来查看类源代码。可以通过单击成员行右侧的“查看源代码”链接来查看类成员的源代码。

Ext JS 7.8.0


顶部

针对多个环境和屏幕进行开发

开发一个在所有设备上都功能完备、易于使用且美观的应用程序是应用程序开发的圣杯。借助 Ext JS 6,您现在拥有实现这一目标所需的工具,而且难度极低。

创建满足所有这些要求的应用程序可以通过几种不同的方式实现。

通用应用程序和工具包

自 Ext JS 6 以来最大的变化之一是将 Ext JS 和 Touch 合并到一个包含两个不同工具包的框架中:经典和现代。这些工具包包含 Ext JS 和 Touch 的视图层。共享核心资源和逻辑并同时使用这两个工具包的应用程序称为通用应用程序。

要选择应用程序的工具包,用户只需调整其 Sencha Cmd 生成的应用程序的 app.json,如下所示

"toolkit": "classic", // or "modern"

这两个框架的核心(数据、控制器、模型等)已协调为一个单一的通用平台。这允许共享数据和逻辑,可以帮助开发人员进一步优化其应用程序。

注意:我们将在下面详细讨论每个工具包。

如果您不熟悉 app.json,它是一个包含应用程序核心配置的列表。

Sencha Cmd 生成的 app.json 文件包含许多您可能需要调整的属性。这些属性在代码中进行了文档说明,以解释它们各自控制的内容。

如果您正在升级项目,您的 app.json 可能不包含所有可能的选项。升级完成后,任何缺失属性的默认值可以在 ".sencha/app/app.defaults.json" 中找到。您不应该编辑该文件,但可以从该文件中复制部分内容到您的 app.json 文件。

有关 app.json 的更多信息,请查看 微加载器指南

经典

经典工具包提供传统的 Ext JS 5 应用程序支持。这包括对桌面浏览器、平板电脑和支持触控的笔记本电脑的支持。

现代

现代工具包提供适用于所有现代浏览器的通用 HTML5 应用程序支持(IE11+),从桌面到手机。

构建配置文件

构建配置文件允许开发人员根据应用程序 app.json 文件中 builds 对象创建应用程序的不同版本。历史上,用户有机会根据主题和语言环境区分构建。

我们上面已经谈到了 app.json,但有关更多信息,请查看 微加载器指南

从 Ext JS 6 和 Sencha Cmd 6 开始,开发人员现在可以在其构建配置中包含一个 toolkit 键。这允许用户将工具包设置为经典或现代(更多信息请见下文)。然后,Cmd 会循环遍历每个构建键,并为每个构建应用相应的工具包以及任何与工具包无关的逻辑。

与工具包无关的代码包括任何可以在工具包之间共享的代码。这包括以前在 sencha-core 包中找到的任何内容(例如,数据、控制器等)。
重要的是要注意,此共享逻辑必须可用于两种工具包。

通用应用程序的 builds 配置应该类似于以下 JSON 结构

"builds": {

   "mymodern": {

       "toolkit" : "modern",

       "theme"   : "theme-cupertino",

       "requires": [

           "charts",

           "ux"

       ]   

   },

   "myclassic": {

      "toolkit" : "classic",

      "theme"   : "theme-neptune",

         "slicer"  : null,

      "requires": [

           "charts"

       ]     

   }

}

构建时的预期结果

让我们谈谈基于上面的 builds 对象,您期望的结果。此 builds 配置允许您从 Sencha Cmd 发出以下构建命令

// Build modern application only
sencha app build mymodern

// Build classic application only
sencha app build myclassic 

// Build all targets within the builds object
sencha app build 

重要的是要注意,构建目标名称可以是您选择的任何名称。您可以将 mymodern 替换为 foo,然后发出

sencha app build foo

生成的 mymodern 应用程序将使用现代工具包,可以访问 ux 和 charts 包,并显示 Cupertino 主题。

生成的 myclassic 应用程序将使用经典工具包,可以访问 charts 包,并显示 Neptune 主题。

您可以在 builds 对象中创建任意数量的变体。默认情况下,所有输出都会显示在您的根级 builds 文件夹中。

通用应用程序

通用应用程序利用 Sencha Cmd 生成跨越两种工具包的多个应用程序构建。这些构建会生成可以在桌面或移动设备上运行的应用程序。重要的是要注意,单个应用程序**不能**在单个类路径中包含现代和经典框架。在大多数情况下,应用程序将在传统的应用程序目录中包含全局逻辑;根级“app”文件夹。
理想情况下,应用程序的通用方面将包含数据、模型、视图模型等。您也可以共享控制器,但开发人员可能需要有创意才能生成跨越工具包的逻辑。

例如,假设您的经典应用程序有一个网格,您的现代应用程序有一个列表,它们都使用共享的存储和模型。然后,假设您希望这两个应用程序都对用户与这些组件的交互做出反应。我们必须寻找网格和列表之间的共同事件。一个理想的解决方案可能是利用 select 事件,因为这两个组件都可以触发它。但是,如果您的逻辑包含“itemtap”,您的经典应用程序将不知道这意味着什么,并且很可能在 Cmd 构建过程的经典部分中导致问题。

在考虑了共享逻辑和资源之后,开发人员可以在相应的工具包 src 文件夹中创建特定于工具包的代码。这可以通过查看 Ext JS 6 中新的通用应用程序文件夹结构来最好地理解。

注意:如果您正在创建单个工具包应用程序,则文件夹结构应与以前的实现非常相似。

Ext JS 6 文件夹结构

重要的是要注意,在创建通用应用程序时,Ext JS 6 和 Sencha Cmd 6 的新目录结构中存在一些重大差异。这些更改是为了确保应用程序能够针对三个特定领域。

  • 全局应用程序代码

  • 经典特定代码

  • 现代特定代码

以下是一个通用应用程序文件夹结构的表示

// app

     // app

          // model

          // store    

          // view

     // classic

          // src

          // sass

          // resources

     // modern

          // src

          // sass

          // resources

     // resources

     // sass

创建通用应用程序

使用通用应用程序入门非常简单。Sencha Cmd 现在会生成一个“入门应用程序”,其中包含适当的文件结构、app.json 和共享代码示例。要创建您的通用应用程序,请像往常一样生成应用程序

 sencha -sdk /path/to/ExtSDK generate app MyApp ./MyAppLocation

Sencha Cmd 现在将创建一个功能齐全的通用应用程序。此应用程序将生成一个经典应用程序和一个现代应用程序,它们都共享可以在“app”文件夹中找到的数据。工具包特定的定义可以在它们各自的工具包命名文件夹(modern 和 classic)中找到。

为了查看每个应用程序以进行开发,您可以像针对构建一样针对 Sencha 应用程序监视。

 sencha app watch modern 

 sencha app watch classic

注意:省略监视目标将默认到builds 对象中第一个命名的构建。

构建应用程序后,您可以在各自的浏览器中查看构建。
例如,在 iPhone 上加载构建文件夹应该会显示您的应用程序的现代版本。在桌面浏览器中加载它应该会显示您的应用程序的经典版本。

运行时配置

还有几种方法可以使用应用程序的运行时环境来创建应用程序。这些方法包括应用程序配置文件、响应式配置和平台配置。

让我们探索它们各自提供的可能性以及它们如何协同工作,为您的用户提供跨多种媒介的无缝体验。

应用程序配置文件

使用Ext.app.Profile 允许开发人员通过 mainView(或 Viewport)根据定义的条件交换应用程序的视图。这意味着您可以通过为特定条件激活配置文件来为您的应用程序创建完全不同的视图。例如,您可能希望根据您的应用程序是在移动设备上加载还是在桌面浏览器上加载来呈现特定视图。

在这种情况下,您将创建两个配置文件,然后将它们列在应用程序类中找到的配置文件数组中。以下是一个简单示例

Ext.define('App.Application', {
    extend: 'Ext.app.Application',

    profiles: [
        'Desktop',
        'Mobile'
    ]
});

活动配置文件由配置文件上isActive 方法的返回值确定。以下是如何配置应用程序以根据检测到的操作系统加载桌面视图的示例。

Ext.define('App.profile.Desktop', {
    extend: 'Ext.app.Profile',

    mainView: 'App.view.desktop.Main',

    isActive: function () {
        return Ext.os.is.Desktop;
    },

    launch: function () {
        console.log('Launch Desktop');
    }
});

配置文件不必使用mainView 配置。相反,您可以使用配置文件的启动方法进行任何进一步的自定义处理。只有活动配置文件的launch 方法会被调用。

平台配置

platformConfig 属性可以在类声明中使用,也可以用于根据当前平台或设备分类配置对象实例。我们可能会在这样的视图中使用它

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',

    title: 'Mfg Summary',

    platformConfig: {
        desktop: {
            title: 'Manufacturing Summary'
        }
    }
});

以上与以下直接方法的结果相同

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',

    title: testForDesktop ? 'Manufacturing Summary'
                          : 'Mfg Summary'
});

想法不是比较platformConfig 与三元运算符的优点,而是看到platformConfig 被视为类声明的一部分。因此,这种方法无论基类是什么都将起作用。偏爱platformConfig 而不是内联逻辑的一个原因是将视图保持为仅数据,可以安全地以 JSON 格式发送。

也可以使用platformConfig 来配置实例

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',

    items: [{
        xtype: 'panel',

        platformConfig: {
            desktop: {
                title: 'Manufacturing Summary'
            },
            '!desktop': {
                title: 'Mfg Summary'
            }
        }
    }]
});

以上最好的直接翻译是

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',

    items: [
        Ext.merge({
            xtype: 'panel'
        },
        testForDesktop ? {
            title: 'Manufacturing Summary'
        } : {
            title: 'Mfg Summary'
        })
    ]
});

但是,在这种使用 platformConfig 的情况下,合并由initConfig 方法处理。换句话说,提供platformConfig 属性作为实例配置仅受在构造函数中调用initConfig 的类支持。对于Ext.WidgetExt.Component、大多数数据包类(如 AbstractStore)以及使用 Observable 的任何类都是如此。

类似于在类声明中使用platformConfig 如何修改类主体,在实例配置上使用platformConfig 如何修改对象的初始配置。

响应式配置

Ext JS 5.0 引入了 responsiveConfig 和响应式 Mixin 和插件,使之成为可能。responsiveConfig 的规则和属性不仅在创建实例时进行评估,而且在设备方向或视窗大小发生变化时也会进行评估。虽然这与 platformConfig 相比会增加一些开销,但它可能比通过监听窗口大小调整或方向变化来自己处理这些问题更有效。

如果我们稍微调整一下我们的标准,我们可以使标题响应设备大小,而不是设备分类(“桌面”)。

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',
    mixins: ['Ext.mixin.Responsive'],

    responsiveConfig: {
        'width >= 600': {
            title: 'Manufacturing Summary'
        },
        'width < 600': {
            title: 'Mfg Summary'
        }
    }
});

由于上面的类具有 responsiveConfig,因此我们从使用 mixin 中受益,避免为每个实例创建插件。但是,当在组件实例上使用时,我们必须使用响应式插件。

Ext.define('App.view.summary.Manufacturing', {
    extend: 'Ext.panel.Panel',

    items: [{
        xtype: 'panel',
        plugins: 'responsive',

        responsiveConfig: {
            'width >= 600': {
                title: 'Manufacturing Summary'
            },
            'width < 600': {
                title: 'Mfg Summary'
            }
        }
    }]
});

重要的是要记住,上面示例中的宽度是视窗宽度,而不是组件宽度。

结论

有了所有这些工具,只需要为特定情况选择合适的工具即可。对于加载时的简单调整,有 platformConfig。对于更动态的条件,有 responsiveConfig。要大规模更改内容,有 Ext.app.Profile

如果您需要一个在平板电脑上看起来与在桌面或手机上完全不同的应用程序,您可以考虑 Sencha Cmd 构建配置文件。构建配置文件可以从桌面构建中删除平板电脑开销,反之亦然。

由于不可能存在“一刀切”的解决方案,Ext JS 提供了不同的工具,将效率和灵活性结合在一起。它们共同协作,以确保您的应用程序能够自然地适应尽可能广泛的设备。

Ext JS 7.8.0