为 Ext JS Classic Toolkit 设置主题

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

要求

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

• 下载 Sencha Cmd 6.5+ 版本
  • 使用非 JRE 安装程序时，下载 Java JRE 1.8+
• 下载 Sencha Ext JS 6.5+ 版本

设置

本指南假定您有一个工作区，自定义 my-theme 和 demo-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.addShortcuts 和 Ext.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' 组件图像”部分。

按钮比例可以配置为 small、medium 或 large，其中 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: true 和 ui: '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/。