许多类在使用配置对象创建(实例化)类时都有快捷名称。快捷名称被称为 alias
(别名)(如果类扩展了 Ext.Component,则为 xtype
(类型别名))。别名/xtype 列在适用类的类名旁边,以供快速参考。
框架类或其成员可以指定为 private
(私有)或 protected
(受保护)。否则,类/成员为 public
(公共)。Public
(公共)、protected
(受保护)和 private
(私有)是访问描述符,用于传达应如何以及何时使用类或类成员。
Public(公共)类和类成员可供任何其他类或应用程序代码使用,并且可以在主要产品版本中被依赖为稳定和持久的。公共类和成员可以通过子类安全地扩展。
Protected(受保护)类成员是稳定的 public
(公共)成员,旨在由拥有类或其子类使用。受保护的成员可以通过子类安全地扩展。
Private(私有)类和类成员在框架内部使用,不供应用程序开发人员使用。私有类和成员可能会随时更改或从框架中省略,恕不另行通知,并且不应在应用程序逻辑中依赖它们。
static
(静态)标签。*请参阅下面的静态。下面是一个示例类成员,我们可以对其进行剖析,以展示类成员的语法(在本例中,是从 Ext.button.Button 类查看的 lookupComponent 方法)。
让我们看一下成员行的每个部分
lookupComponent
)( item )
)Ext.Component
)。对于不返回除 undefined
之外的任何内容的方法,可以省略此项,或者可以显示为由正斜杠 /
分隔的多个可能值,表示返回的内容可能取决于方法调用的结果(即,如果 get 方法调用成功,则方法可能返回 Component,如果失败,则返回 false
,这将显示为 Ext.Component/Boolean
)。PROTECTED
(受保护)- 请参阅下面的标志部分)Ext.container.Container
)。如果成员源自当前类,则源类将显示为蓝色链接,如果它从祖先类或混入类继承,则显示为灰色。view source
(查看源代码))item : Object
)。undefined
之外的值,则“返回值”部分将注释返回的类或对象类型以及描述(示例中为 Ext.Component
)Available since 3.4.0
(自 3.4.0 版本起可用)- 未在示例中显示),紧接在成员描述之后Defaults to: false
(默认为:false))API 文档使用许多标志来进一步传达类成员的功能和意图。标签可以用文本标签、缩写或图标表示。
classInstance.method1().method2().etc();
false
,则标记为可阻止的事件将不会触发- 表示框架类
- 单例框架类。*有关更多信息,请参阅单例标志
- 组件类型框架类(Ext JS 框架中扩展 Ext.Component 的任何类)
- 表示类、成员或指南在当前查看的版本中是新的
- 表示类型为 config
(配置)的类成员
- 表示类型为 property
(属性)的类成员
- 表示类型为 method
(方法)的类成员
- 表示类型为 event
(事件)的类成员
- 表示类型为 theme variable
(主题变量)的类成员
- 表示类型为 theme mixin
(主题 mixin)的类成员
- 表示类、成员或指南在当前查看的版本中是新的
在 API 文档页面上的类名正下方是一行按钮,对应于当前类拥有的成员类型。每个按钮显示按类型划分的成员计数(此计数在应用过滤器后会更新)。单击按钮会将您导航到该成员部分。将鼠标悬停在成员类型按钮上将显示该类型的所有成员的弹出菜单,以便快速导航。
与类配置选项相关的 Getter 和 Setter 方法将显示在方法部分以及 API 文档和成员类型菜单的配置部分中,就在它们所作用的配置下方。Getter 和 Setter 方法文档将在配置行中找到,以便于参考。
您的页面历史记录保存在本地存储中,并显示在顶部标题栏下方(使用可用的实际空间)。默认情况下,仅显示的搜索结果是与您当前查看的产品/版本匹配的页面。您可以通过单击历史记录栏右侧的 按钮并选择“全部”单选按钮来扩展显示的内容。这将显示所有产品/版本的所有最近页面访问历史记录。
在历史记录配置菜单中,您还将看到最近访问页面的列表。结果按“当前产品/版本”和“全部”单选按钮进行过滤。单击 按钮将清除历史记录栏以及保存在本地存储中的历史记录。
如果在历史记录配置菜单中选择“全部”,则“在历史记录栏中显示产品详细信息”复选框选项将启用。选中后,每个历史页面的产品/版本将与历史记录栏中的页面名称一起显示。将光标悬停在历史记录栏中的页面名称上也会将产品/版本显示为工具提示。
可以使用页面顶部的搜索字段搜索 API 文档和指南。
在 API 文档页面上,还有一个过滤器输入字段,该字段使用过滤器字符串过滤成员行。除了按字符串过滤外,您还可以按访问级别、继承和只读过滤类成员。这是通过使用页面顶部的复选框完成的。
API 类导航树底部的复选框过滤类列表以包含或排除私有类。
单击空的搜索字段将显示您最近 10 次搜索,以便快速导航。
每个 API 文档页面(Javascript 原始类型页面除外)都有一个与该类相关的元数据菜单视图。此元数据视图将具有以下一项或多项
Ext.button.Button
类有一个备用类名 Ext.Button
)。维护备用类名通常是为了向后兼容性。可运行的示例 (Fiddles) 默认在页面上展开。您可以使用代码块左上角的箭头单独折叠和展开示例代码块。您还可以使用页面右上角的切换按钮切换所有示例的折叠状态。切换所有状态将在页面加载之间记住。
类成员默认在页面上折叠。您可以使用成员行左侧的箭头图标展开和折叠成员,或使用右上角的展开/折叠所有切换按钮全局展开/折叠。
在较窄的屏幕或浏览器上查看文档将导致针对较小外形尺寸优化的视图。桌面视图和“移动”视图之间的主要区别在于
可以通过单击 API 文档页面顶部的类名来查看类源代码。可以通过单击成员行右侧的“view source”(查看源代码)链接来查看类成员的源代码。
Sencha Cmd 包括 Sencha Package Manager(Sencha 包管理器)。包旨在解决两个基本问题:消费和分发。本指南重点介绍了这些主题。另请参阅 创建 Sencha Cmd 包,了解有关创建和共享包的信息。
"packages"
文件夹由 Sencha Cmd 生成的所有工作区在根目录都有一个 "packages"
文件夹。可以配置此文件夹的位置,但无论其位置如何,"packages"
文件夹的作用都是充当工作区中应用程序(或其他包)使用的所有包的存储位置。
packages/ # Container folder for shared Cmd packages
local/ # Folder for packages generated in this workspace
remote/ # Folder for packages downloaded into the workspace
当应用程序需要包并下载以满足需求时,包将被添加到 "packages/remote"
文件夹中。当生成包时(使用 sencha generate package
),它将生成到 "packages/local"
中。
无论包的来源如何(无论是本地创建还是从远程仓库下载 - 见下文),消费包的方式都是相同的:您在 "app.json"
中的 requires
数组中添加一个条目。为了演示目的,我们添加了一个简单的包,您可以尝试使用
{
"name": "MyApp",
"requires": [
"cool-stuff"
]
}
给定上述要求,sencha app build
和 sencha app refresh
现在都将执行将包集成到应用程序中所需的步骤。通常,在更改包需求后,您需要运行 sencha app refresh
,以便支持“开发模式”所需的元数据是最新的。
无论您运行哪个命令,Sencha Cmd 都会下载包并将其解压缩到您的 "packages/remote"
文件夹中。之后,您将在您的工作区中找到一个 "packages/remote/cool-stuff"
文件夹。
包的一种用途仅仅是保存工作区中多个应用程序可用的代码或主题。这些包永远不需要分发(超出源代码控制)即可为您的开发提供价值。
要将包添加到您的工作区,您只需生成包
sencha generate package common
这会在 "packages/local/common"
文件夹中生成一个新包。此包还在其 "package.json"
中标记为 local: true
。此标志阻止 Sencha Cmd 永远不会使用来自远程仓库的版本覆盖该包(见下文)。如果通过编辑 "workspace.json"
将包文件夹合并(就像以前的版本一样),这将变得很重要。
然后将 “common” 添加为应用程序 "app.json"
的要求,如上所述
{
"name": "MyApp",
"requires": [
"common"
]
}
有关更多详细信息,特别是关于如何将包分发给其他人,请参阅 创建 Sencha Cmd 包。
虽然本地包在大型应用程序中可能非常有价值,但包最有用的方面之一是能够分发包供其他人使用。
包使用包仓库共享和分发。Sencha Cmd 自动创建一个“本地仓库”来缓存包以及发布包。本指南未讨论本地仓库在包创作中的作用。有关该主题的详细信息,请参阅 创建 Sencha Cmd 包。
许多操作隐式地使用本地仓库。当 Sencha Cmd 在 "app.json"
中遇到 requires
语句时,它遵循以下基本步骤
一旦包被下载,后续对此包的需求将不需要下载;该包将在本地仓库中找到。
本地仓库在“旁边”各种版本的文件夹中创建,以方便缓存。例如,Windows 上用户 Foo 的 Sencha Cmd 的默认安装目录可能类似于这样
C:\Users\Foo\bin\Sencha\Cmd\n.n.n.n
鉴于该安装目录,本地仓库将位于
C:\Users\Foo\bin\Sencha\Cmd\repo
可以通过编辑 Sencha Cmd 安装文件夹中的 "sencha.cfg"
来更改此设置。
本地仓库的内容在 创建 Sencha Cmd 包 中进一步讨论。
为了将包下载到本地仓库,Sencha Cmd 必须知道远程仓库。默认情况下,Sencha Cmd 自动将 Sencha Package Repository(Sencha 包仓库)添加为名为 “sencha” 的远程仓库。
要查看远程仓库列表,请运行 sencha repository list
命令
> sencha repository list
...
[INF] Remote repository connections (1):
[INF]
[INF] sencha - http://cdn.sencha.com/cmd/packages/
您可以使用 sencha repository add
和 sencha repository remove
命令从此列表中添加和删除仓库。如果您选择托管本地仓库,那么您的本地仓库实际上是其他人的有效远程仓库。有关此的详细信息,请参阅 创建 Sencha Cmd 包。
可用的包集在“目录”中列出。您可以使用以下命令显示全局目录的内容
sencha package list
当您列出包时,您会注意到该列表包括名称和版本。
由于 Sencha Cmd 的仓库管理是分布式的,您可以根据需要添加或删除远程仓库,因此没有通用的包命名空间。如果您保留与 Sencha Package Repository 的默认 “sencha” 连接,那么您可以将该仓库的内容视为命名标准。
由 Sencha 发布(未包含在 Sencha Framework 内部)的包将使用以下形式的名称
所有以前缀开头的包名称均由 Sencha 保留,相对于 Sencha Package Repository。建议即使您断开与 Sencha Package Repository 的连接,也应避免与这些名称冲突。
为了连接包及其使用者(即,应用程序或其他包),考虑所涉及的版本非常重要。为了帮助管理这一点,所有包都有版本号,requires
语句使用这些版本号来处理版本限制。
所有包都由其名称和版本的组合来描述。但是,对于包的每个版本,还有另一个版本号描述其向后兼容性级别。此版本是包创建者声明的,他们认为其包的特定版本与某些特定的先前版本级别向后兼容。
在 "package.json"
描述符中,有两个重要的属性:version
和 compatVersion
。例如
{
...
"version": "n.n.n",
"compatVersion": "2.4.2",
...
}
此数字必须是以下格式
\d+(\.\d+)*
当使用上面的 requires
属性时,我们仅指定了包名称,以使示例尽可能简单。这精确地意味着“最新版本”。在某些情况下,这是可以接受的,但是如果该包的下一个版本是完全重新设计并且不提供任何级别的向后兼容性,则这可能是一个有风险的要求。
为了保护您的应用程序免受这种情况的影响,我们可以更改 require
语句以使其非常严格并锁定我们想要的版本号
{
"name": "MyApp",
"requires": [
"[email protected]"
]
}
这种方法有其位置,但是它甚至阻止了包的维护版本被拾取。在项目的最后阶段,这可能正是所期望的,但是在开发过程中,也许我们希望稍微宽松一些并接受任何兼容版本。
以下更改将执行此操作
{
"name": "MyApp",
"requires": [
"[email protected]?"
]
}
以上请求具有版本 1.0 向后兼容性的最新可用版本的 "ext-easy-button"
。
限制版本匹配的其他方法是
给定所有期望的和可用的版本,Sencha Cmd 将确定最佳匹配包集,并确保这些包在您的工作区中。
如果存在互斥的要求,则此过程可能会失败。在这种情况下,您将看到一条错误消息,说明哪些要求无法满足。