文档帮助

术语、图标和标签

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

访问级别

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

成员类型

成员语法

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

lookupComponent ( item ) : Ext.Component
受保护的

当原始配置对象添加到此容器时调用,无论是在 items 配置的初始化期间,还是在添加新项目 added) 或 {@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 - Classic Toolkit


顶部
指南适用于: classic

为 Ext JS Classic Toolkit 设置主题

本指南是 Ext JS 主题 指南的延续,重点介绍 Ext JS Classic Toolkit 的主题 API,因此请在继续之前阅读该指南。有关现代工具包的信息,请参阅 为 Ext JS Modern Toolkit 设置主题 指南。

要求

本指南假定您已满足 Ext JS 主题 指南中描述的所有要求。回顾一下

设置

本指南假定您有一个工作区,自定义 my-themedemo-app 按照 Ext JS 主题 指南中的描述生成。

您应该可以使用以下命令 watch 演示应用程序(或运行 sencha app build --development 命令来编译您的样式)

$ sencha app watch --fashion

运行 sencha app watch 后,您可以使用 URL 拉起您的应用程序

https://127.0.0.1:1841/demo-app/

--fashion 开关将指示浏览器在您更改应用程序的主题时刷新应用程序内的样式 - 通常在不到一秒的时间内! 提醒:此实时更新功能仅在现代浏览器上受支持(其他浏览器将需要手动重新加载才能看到更改)。

主题组件

正如之前的 指南 中一般讨论的那样,组件的主题 API 由变量和 mixins 组成。组件的默认外观由其变量决定,而自定义外观可以通过调用“UI mixin”来定义和命名。

配置主题变量

每个可主题化的 Ext JS 组件都有一个变量列表,可用于配置其外观。让我们更改 my-theme 中 Panel 标题的 font-family。创建一个名为 my-theme/sass/var/panel/Panel.scss 的文件,并添加以下代码

$panel-header-font-family: Times New Roman;

现在查看您的应用程序,您应该看到面板标题使用“Times New Roman”字体。您可以在组件的 API 文档的“主题变量”部分找到每个组件的完整变量列表。例如,请参阅 Ext.panel.Panel 并滚动到标题为“主题变量”的部分

使用主题 Mixins

Ext JS Classic Toolkit 中的所有组件都有一个 ui 配置属性,默认为 "default"。可以在单个组件实例上配置此配置属性,以使它们的外观与同一类型的其他实例不同。Neptune 主题中使用此配置来创建不同类型的 面板按钮。例如,具有默认 ui 的面板具有深蓝色标题,而具有“light”ui 的面板具有浅蓝色标题。按钮使用 ui 为工具栏按钮提供与常规按钮不同的外观。

theme-neutral 主题包含许多不同 Ext JS 组件的主题 Mixins(或 UI Mixins)。您可以调用这些 mixins 来为组件生成新的 ui。每个组件的可用 mixins 都列在 API 文档中。例如,请参阅 Ext.panel.Panel 并向下滚动到“主题 Mixins”部分,以查看 Panel UI mixin 接受哪些参数。让我们使用这个 mixin 创建一个自定义 Panel ui

创建一个名为 my-theme/sass/src/panel/Panel.scss 的文件,并将以下内容添加到其中

@include extjs-panel-ui(
    $ui: 'highlight-framed',
    $ui-header-background-color: red,
    $ui-border-color: red,
    $ui-header-border-color: red,
    $ui-body-border-color: red,
    $ui-border-width: 5px,
    $ui-border-radius: 5px,
    $ui-header-color: white
);

此 mixin 调用创建一个名为 "highlight" 的新 Panel ui,它具有红色标题背景、红色边框、5px 边框、5px 边框半径和白色文本。要使用此 ui,请将 Panel 配置为将其 ui 属性设置为 'highlight'(以及 frame: true)。打开 demo-app/app/view/main/List.js 并将其内容替换为以下内容

Ext.define('App.view.main.List', {
    extend: 'Ext.grid.Panel',
    xtype: 'mainlist',

    ui: 'highlight',
    frame: true,

    requires: [
        'App.store.Personnel'
    ],

    title: 'Personnel',

    store: {
        type: 'personnel'
    },

    columns: [
        { text: 'Name',  dataIndex: 'name' },
        { text: 'Email', dataIndex: 'email', flex: 1 },
        { text: 'Phone', dataIndex: 'phone', flex: 1 }
    ],

    listeners: {
        select: 'onItemSelected'
    }
});

在 Web 浏览器中查看您的应用程序,您应该看到红色的“highlight”网格。

虽然 UI mixins 是配置组件多种外观的便捷方法,但不应过度使用它们。每次调用 UI mixin 都会生成额外的 CSS 规则。过度调用 UI mixins 可能会生成过大的 CSS 文件。

在 IE 中为 CSS3 效果切片图像

在某些主题中,许多组件都有圆角和线性渐变背景。使用 CSS3 在现代浏览器中实现这些效果很简单。但是,Ext JS 支持 IE8 和 IE9,这两个浏览器都不支持这些效果(或者以一种使组合效果成问题的方式支持)。

Sencha Cmd 通过在无头浏览器中渲染每个需要这些效果的组件,并从角落和渐变中切片图像,以用作 IE8/9 中组件标记中的背景图像,从而弥合了这一差距。当添加自定义 ui 时,您需要将它们包含在 Sencha Cmd 使用的切片清单中,以便使用自定义 ui 修饰的组件将被切片以在 IE8/9 中使用。

为此,我们需要告诉 Sencha Cmd 哪些组件和 ui 需要切片。为了为您在本指南前面创建的“highlight”面板 ui 的圆角创建切片,请编辑名为 my-theme/sass/example/custom.js 的文件并添加以下内容

Ext.theme.addManifest({
    xtype: 'panel',
    ui: 'highlight'
});

注意: 可以在同一个 addManifest 调用中添加多个清单条目,例如

Ext.theme.addManifest({
    xtype: 'panel',
    ui: 'highlight'
}, {
    xtype: 'button',
    ui: 'green'
});

如果您创建了需要切片的原始组件,则需要将任何适用的 ui 配置添加到切片清单中,如上所示。您还需要使用 custom.js 中的 Ext.theme.addShortcuts() 调用为自定义组件添加配置条目。

快捷方式配置以及传递给清单的 ui 将用于渲染自定义组件以进行切片。

有关如何使用 Ext.theme.addShortcutsExt.theme.addManifest 的更详细描述,请参阅 my-theme/sass/example/render.js 中找到的每个方法的内联文档说明。您可以参考 ext/classic/theme-base/sass/example/shortcuts.js 文件中框架组件的 addShortcuts 示例。

修改图像资源

作为修改图像资源的示例,让我们更改 MessageBox 组件的信息图标。将以下图像另存为 my-theme/resources/images/shared/icon-info.png。此图像资源将优先于父级 Crisp 主题中使用的图像资源,路径为 my-workspace/ext/classic/theme-crisp/resources/images/shared/icon-info.png

现在修改您的测试应用程序以显示使用自定义图标的 MessageBox。将以下 tbar 配置添加到应用程序 demo-app/app/view/main/List.js 文件中的“highlight”网格

...
tbar: [{
    text: 'Show Message',
    handler: function() {
        Ext.Msg.show({
            title: 'Info',
            msg: 'Message Box with custom icon',
            buttons: Ext.MessageBox.OK,
            icon: Ext.MessageBox.INFO
        });
    }
}]
...

现在,在浏览器中查看应用程序。当您单击“显示消息”按钮时,您应该看到 MessageBox 包含一张友善的面孔。

设置应用程序样式

应用程序之间不共享的样式属于应用程序本身,而不属于主题。 Sencha Cmd 提供了一种通过允许您将样式与 JavaScript 代码一起组织来轻松添加应用程序级样式的方法。

设置应用程序视图的样式

要编写与应用程序视图关联的 CSS 规则,请在与视图相同的文件夹中创建一个 .scss 文件,并使用与视图相同的基本名称。例如,要设置位于 demo-app/app/view/main/Main.js 中的视图 App.view.main.Main 的样式,您可以将该代码放在 demo-app/app/view/main/Main.scss 中。

让我们为应用程序应用程序中用户选项卡的内容设置样式

.content-panel-body h2 {
    color: orange;
}

content-panel-body CSS 类添加到应用程序 Main.js 文件中用户面板的配置中

...
title: 'Users',
iconCls: 'fa-user',
html: '<h2>Content appropriate for the current navigation.</h2>',
bodyCls: 'content-panel-body'
...

查看您的应用程序,您将看到 Users 视图中的 h2 元素现在是橙色的。虽然添加任意 CSS 样式的能力提供了最大的灵活性,但直接应用于 Ext JS 组件拥有的元素的任何样式都应尽可能使用 Ext JS 主题 API 来设置样式。使用主题 API 可以保护您的样式免受未来版本的 Ext JS 中破坏标记更改的影响。

其他注意事项

'default' 组件图像

各种组件都有与组件的 "default" ui 相关的图像(按钮、菜单等)。当您为其中一个组件创建自定义 ui 时,您会注意到在编译主题时,它会警告说找不到主题的图像。

WARNING: @theme-background-image: Theme image not found:

在刷新主题或应用程序时,Sencha Cmd 将查找图像,在图像名称中使用 ui 名称代替 "default"。例如,如果您为小按钮创建名称为 "admin" 的 mixin ui,Sencha Cmd 将警告说找不到 "admin-small-arrow.png"

此警告的解决方案是将文件名中带有“default”的任何图像资源从您扩展的主题复制到自定义主题的 resources/images 目录中。然后,您将重命名这些文件并将“default”替换为您的自定义 ui 的名称。对于扩展 Neptune 的自定义主题中的 "admin" 按钮 ui,您将从 ext/classic/theme-neptune/resources/images/button 文件夹复制 "default" 图像,并将它们粘贴到 packages/local/my-theme/resources/images/button/ 中。然后,您将所有 "default" 实例重命名为 "admin"。例如

$ mv default-small-arrow.png admin-small-arrow.png

Ext.button.Button

在创建自定义 ui 时,按钮 ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

按钮比例可以配置为 smallmediumlarge,其中 small 是默认值。为按钮创建自定义 UI 时,您需要为应用程序中使用的每个比例提供一个按钮 mixin。

注意: 应该避免使用 extjs-button-ui mixin,而应使用特定于比例的 mixins 为按钮设置样式。

@include extjs-button-small-ui(
    $ui: 'green',
    $background-color: green
);

@include extjs-button-medium-ui(
    $ui: 'green',
    $background-color: green
);

@include extjs-button-large-ui(
    $ui: 'green',
    $background-color: green
);

使用 -toolbar 按钮 mixins 时也是如此。每个 mixin 都有一个比例,应单独包含在 Button.scss 文件中,以便支持所有按钮比例。此外,在使用 -toolbar 按钮 mixins 时,您需要将 -toolbar 添加到应用程序中按钮的 ui 配置中。以下是小型工具栏按钮 mixin 的示例 mixin

@include extjs-button-toolbar-small-ui(
    $ui: 'green',
    $background-color: green
);

这将修饰工具栏中配置的按钮,例如

xtype: 'toolbar',
items: [{
    text: 'Toolbar Button',
    ui: 'green-toolbar'
}]

Ext.panel.Panel

面板可以配置为 frame: true,默认情况下为 frame: false。因此,默认情况下,如果您具有 ui: 'highlight'ui 配置,则生成的 Panel.scss 看起来像

@include extjs-panel-ui(
    $ui: 'highlight',
    $ui-header-background-color: red,
    $ui-border-color: red,
    $ui-header-border-color: red,
    $ui-body-border-color: red,
    $ui-border-width: 5px,
    $ui-border-radius: 5px
);

但是,这只会将样式应用于非框架面板。为了设置配置为 frame: trueui: 'highlight' 的面板的样式,您需要在 Panel.scss 文件中将 -framed 添加到 $ui 名称中。通常,框架版本和非框架版本都将在 Panel.scss 中表示

@include extjs-panel-ui(
    $ui: 'highlight',
    $ui-header-background-color: red,
    $ui-border-color: red,
    $ui-header-border-color: red,
    $ui-body-border-color: red,
    $ui-border-width: 5px,
    $ui-border-radius: 5px
);

@include extjs-panel-ui(
    $ui: 'highlight-framed',
    $ui-header-background-color: red,
    $ui-border-color: red,
    $ui-header-border-color: red,
    $ui-body-border-color: red,
    $ui-border-width: 5px,
    $ui-border-radius: 5px
);

Ext.menu.Menu

在创建自定义 ui 时,菜单 ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

Ext.toolbar.Breadcrumb

在创建自定义 ui 时,面包屑导航 ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

Ext.tab.Tab

在创建自定义 ui 时,选项卡 ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

创建选项卡 ui 时,请务必包含您要设置样式的​​所有适用的状态变量,包括 -active 选项卡状态,例如 $ui-color-active$ui-background-color-active 等。

Ext.tab.Bar

在创建自定义 ui 时,TabBar ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

注意: 当使用 extjs-tab-bar-ui mixin 创建 TabBar ui 时,您需要创建一个同名的相应 tab-ui

这将确保选项卡在您的主题中正确呈现。不创建匹配的选项卡主题可能会导致不可预测的选项卡渲染。

Ext.toolbar.Toolbar

在创建自定义 ui 时,工具栏 ui 图像需要从父主题复制到自定义主题。有关更多详细信息,请参阅上面的“'default' 组件图像”部分。

从 Ext JS 5.x 升级

虽然 Ext JS 5 和 6 之间的大部分主题更新都发生在幕后,但在升级主题时,仍有一些更改需要注意。

sass/etc/all.scss 中定义的任何变量都应移动到 sass/var/all.scss(或由 sass/var/all.scss @import-ed 的 .scss 文件)。

推荐)从变量声明的末尾删除 !default

推荐)将您的自定义主题文件夹从应用程序/工作区中的根 packages/ 文件夹重新定位到 packages/local/

Ext JS 7.8.0 - Classic Toolkit