数据网格布局、样式和主题

其他资源

• 主题
• 现代主题
• 经典主题

示例

• 样式行和列
• 标题工具

Ext JS 主题

Ext JS 提供的默认主题可直接用于创建干净、专业的应用程序。但是，您可能希望提供自己的样式，以匹配您的个人设计美学或现有企业设计的样式。

注意：您可以使用我们的图形工具 Sencha Themer 构建自定义主题。

从历史上看，对应用程序进行样式处理意味着创建样式表，其中包含用于调整或装饰组件渲染中使用的各个 HTML 元素的规则。这种方法会出现几个问题。第一个问题是，您现在必须在所有受支持的浏览器中进行样式处理。其次，随着框架的发展，组件的底层元素可能会发生变化，这会给您带来在样式规则中追赶更改的不愉快任务。使用 Ext JS 主题 API 对组件进行样式处理可为您解决这些问题。

主题可以在工作空间中的任意数量的 Ext JS 应用程序中共享（工作空间是由 Sencha Cmd 定义的简单文件系统结构）。主题允许您一次设置样式，并一遍又一遍地应用该样式，确信应用程序的外观和感觉的一致性。

本指南列出了主题所需的要求，并介绍了创建自定义主题的基础知识。由于许多细节因您使用的是经典工具包还是现代工具包而异，因此本指南重点介绍了共同的原则。具体内容请参阅以下指南：Ext JS Modern 工具包主题 和 Ext JS Classic 工具包主题。

要求

Sencha Cmd 6.5+

Sencha Cmd 是一款用于打包和部署 Ext JS 应用程序的命令行工具。要在 Ext JS 6.5+ 中构建主题，必须在计算机上安装 Sencha Cmd 6.5 或更高版本。有关安装和开始使用 Sencha Cmd 的更多信息，请参阅 Sencha Cmd 简介。

Java JRE

Java JRE 是运行 Sencha Cmd 的必需品。只要有可能，我们建议运行 JRE 的最新版本（撰写本文时为版本 1.8）。但是，运行 sencha app watch 需要版本 1.7 或更高版本。此命令在应用程序目录中运行，并在修改主题源时自动更新已编译的主题。Sencha Cmd 具有包含 JRE 的安装程序或不包含 JRE 的独立安装程序。如果您还没有合适的 JRE，我们建议使用包含 JRE 的安装程序（如果您的平台有）。

注意：如果没有 Java JRE 1.7+ 和 sencha app watch，您需要使用 sencha app build --development 在每次更改后手动重新构建应用程序的样式。

Ext JS

自定义主题基于 Ext JS SDK 中包含的默认主题。下载 Ext JS 并将 Ext JS 开发工具包 (SDK) 解压到您选择的位置。我们建议在您的主目录中创建一个名为 sencha-sdks 的文件夹。

构建自定义主题

安装完上述要求后，您可以继续创建自定义主题。主题只是 Sencha Cmd 包的一种特定类型。所有包都可以包含 JavaScript、CSS 样式和资源，这些资源将在 Sencha Cmd 构建它们时并入应用程序。正如我们将看到的，主题包利用了所有这些类型的资产。

创建工作区

工作区是 Sencha Cmd 将应用程序（以及主题或其他代码包）与 Ext JS 框架的共享副本连接起来的方式。如果您只有一个要构建的应用程序，Sencha Cmd 可以将工作区和应用程序合并到一个目录中。

对于本教程，我们将创建一个工作区，以便多个应用程序可以访问自定义主题。从您要创建工作区（例如，“my-workspace”）的目录中运行以下命令

$ sencha workspace init
$ sencha framework add ~/sencha-sdks/ext-7.1.0

在 Windows 中，将 ~/sencha-sdks/ 替换为 %USERPROFILE%\sencha-sdks\。如果您选择了其他路径，请在此处使用适当的路径。

sencha workspace init 命令将在当前目录中创建 Sencha 工作区的脚手架。sencha framework add 命令将必要的 Ext JS SDK 文件复制到工作区，以便主题和应用程序可以找到这些依赖项。

此工作区是您的自定义主题包所在的位置。您还将在此处创建将使用您的自定义主题的应用程序。运行上述命令后，您将在工作区目录中找到以下文件

• ext65/ - Ext JS SDK（由 sencha framework add 填充）。
• workspace.json - 工作区的配置描述符。
• .gitignore - 一个启动文件，用于保持 Git 存储库的干净。

生成主题包

Sencha Cmd 通过生成包含所有必要文件的主题包来简化创建自定义主题的过程。按照以下步骤生成您的主题

1. 运行：sencha generate workspace/path/to/workspace
2. 转到工作区目录。
3. 运行：sencha -sdk ../ext generate app NewExtApp new-app
4. 运行：sencha workspace init
5. cd new-app
6. 运行：sencha generate theme my-theme

这告诉 Sencha Cmd 在工作区的 packages/local 目录中生成名为 my-theme 的主题包。让我们看看自定义主题文件夹的默认内容

• “package.json” - 这是包定义文件。它告诉 Sencha Cmd 有关包的某些信息，例如其名称和依赖关系（即它需要的包）。
• “sass/” - 此目录包含主题的所有 Fashion 源文件。源文件分为 4 个主要部分
  • sass/var/ - 按类名组织的变量定义。
    • sass/var/all.scss - 全局变量设置。
  • sass/src/ - 使用 sass/var 中定义的变量的规则和 UI 混合调用。
  • sass/etc/ - 其他实用函数或混合。
  • sass/example - 使用 Sencha Cmd 为 IE8/9 执行图像切片（请勿删除）。（仅限经典）
• “resources/” - 图像和其他静态资源。
• “overrides/” - Ext JS 组件类的 JavaScript 覆盖。

sass/src 和 overrides 中的文件和文件夹应按您要设置样式或覆盖的组件类名进行组织。例如，与 Ext.panel.Panel 相关的主题代码应放置在名为 sass/src/panel/Panel.scss 的文件中。根据关联的类将混合调用和样式规则放在适当的文件中非常重要，以便 Sencha Cmd 只能在构建中包含应用程序所需的代码。

相同的组织可以应用于 sass/var/。或者，如果您只有少量变量要设置，则可以选择仅使用 sass/var/all.scss 文件。由于设置变量不会影响生成的 CSS 的大小，因此将所有主题变量保留在单个文件中或按类名拆分到多个文件中之间的选择是个人偏好或项目指南的问题。

配置主题继承

所有 Sencha 主题包都是更大主题层次结构的一部分。每个主题包都扩展父主题或基本主题。创建自定义主题的下一步是选择要扩展哪个主题。Ext JS 为每个工具包附带了多个主题

现代工具包

• theme-material - Material Design 主题。
• theme-ios - iOS 主题。
• theme-triton - 现代扁平无边框主题。
• theme-neptune - 现代无边框主题。

经典工具包

• theme-triton - 使用字体图标的现代主题。扩展“theme-neptune”。
• theme-crisp - 简约主题。扩展“theme-neptune”。
• theme-crisp-touch - 基于 Crisp 的触控主题。扩展“theme-crisp”。
• theme-neptune - 现代无边框主题。
• theme-neptune-touch - 基于 Neptune 的触控主题。扩展“theme-neptune”。
• theme-classic - 经典蓝色 Ext JS 主题。
• theme-gray - 灰色主题。扩展“theme-classic”。

您的自定义主题应该扩展哪个主题？对于现代工具包，我们建议使用 theme-material 或 theme-triton，而对于经典工具包，我们建议使用 theme-triton、theme-crisp 或 theme-neptune 作为自定义主题的起点（或可能在为平板电脑设置主题时使用 theme-neptune-touch 或 theme-crisp-touch）。这些主题包含开箱即用创建有吸引力的主题所需的所有代码。

theme-base 和（在经典中）theme-neutral 主题应被视为抽象的，不应直接扩展。

在本教程中，我们将创建一个扩展 theme-triton 的自定义主题。第一步是使用它要扩展的主题的名称配置您的自定义主题。这是通过将 packages/local/my-theme/package.json 中的 extend 属性从其默认值更改为所需值来完成的

"extend": "theme-triton"

您的自定义主题现在配置为使用 Triton 主题作为基础。您的自定义主题最初与默认 Triton 主题相同。在以下步骤中，您将进行自己的更改以开始区分您的自定义主题。

构建主题

构建主题会在您的主题包目录中创建一个 build 目录。在 my-theme/build/resources 中，您会找到一个名为 my-theme-all.css 的文件。此文件包含主题中所有 Ext JS 组件的所有样式规则。构建的主题文件包含每个 Ext JS 组件的所有样式，对于不使用 Sencha Cmd 的应用程序很有用。

注意：在 Sencha Cmd 应用程序中使用该主题时，无需构建主题。当 Sencha Cmd 构建应用程序时，它会直接从主题源中合并所需的 .js 和 .scss 文件。

生成测试应用程序

为了快速开发和测试我们的自定义主题，我们需要将其托管在 Ext JS 应用程序中。该应用程序应根据您的需要设置为使用现代或经典工具包。要创建应用程序，请从工作区目录运行以下命令

$ mkdir demo-app
$ cd demo-app

$ sencha app init --ext65 --modern App
  -- or --
$ sencha app init --ext65 --classic App

配置应用程序的主题

要将测试应用程序配置为使用自定义主题，请找到设置 "theme" 的行，该行位于 demo-app/app.json 中，并将其更改为

"theme": "my-theme",

查看应用程序

Sencha Cmd 现已在此子目录中生成了名为 App 的应用程序。接下来，我们将对主题和示例应用程序进行更改。我们希望 Sencha Cmd 检测到这些更改，并自动将它们编译到应用程序使用的输出 CSS 中。要实现此目的，请运行以下命令

$ sencha app watch --fashion

提醒：sencha app watch 命令需要 Java JRE 1.7 或更高版本。如果您无法运行 sencha app watch，则需要在对主题进行每次更改后运行 sencha app build --development。为简洁起见，我们假设您正在运行 sencha app watch。

在运行 sencha app watch 之后，您可以使用 URL 在浏览器中加载您的应用程序

http://localhost:1841/demo-app/

--fashion 开关将指示浏览器在您对应用程序主题进行更改时刷新应用程序中的样式 - 通常在不到一秒的时间内！

注意：仅在现代浏览器上支持使用 --fashion 进行实时更新。主题中对样式的大多数更改都会在无需浏览器刷新时接近实时更新。但是，修改组件尺寸的主题更改可能需要手动刷新浏览器。

主题 API

Ext JS Classic 和 Modern 工具包对其 API 具有相同的基本方法：它们定义变量以配置组件的默认外观，并且它们提供可生成自定义外观的混合。这些自定义外观被分配为您选择的名称，并且这些名称使用 ui 配置属性应用于组件实例。由于与 ui 配置的这种关系，这些混合通常称为“UI 混合”或“主题混合”。

这些变量的名称因工具包而异，但有一些通用变量，如 $base-color，适用于两者。有关变量的完整列表，请参阅 Global_CSS。

在 Classic 工具包中，ui 配置是一个字符串（例如 "custom"）。此字符串键入到指定此名称的混合调用的输出中。在 Modern 工具包中，ui 配置更像 CSS 类。它可以是一组用空格分隔的名称。每个名称都映射到传递给混合调用的名称，但这些调用的结果更具可组合性。有关 ui 配置的更多详细信息，请查阅相应的工具包主题指南和 API 文档。

配置主题变量

让我们从修改 $base-color 开始，$base-color 是许多 Ext JS 组件颜色派生的值。由于在默认主题中使用了 $base-color，因此对 $base-color 进行全局更改将对 Ext JS 库中的大多数组件产生影响。

创建文件 packages/local/my-theme/sass/src/Component.scss 并添加以下代码

$base-color: #317040;

$base-color 的值必须是有效的 HTML 颜色代码；请参阅 HTML 颜色代码 网页。

此时，您应该看到我们之前指定为 $base-color 的绿色应用于屏幕上的组件。

注意：主题变量都被定义为动态的，因此不需要 dynamic() 声明来设置它们（如上所示）。但是，如果您想定义自己的变量，我们建议使它们动态

$my-custom-color: dynamic(red);

主题 JS 覆盖

有时，主题需要更改组件的某个方面，而该方面只能通过 JavaScript 进行配置。这可以通过向您的主题包添加 JavaScript 覆盖轻松实现。为了演示如何执行此操作，让我们更改自定义主题中面板的 titleAlign 配置。创建一个名为 my-theme/overrides/panel/Panel.js 的新文件并添加以下代码

Ext.define('MyTheme.panel.Panel', {
    override: 'Ext.panel.Panel',
    titleAlign: 'center'
});

当您在浏览器中查看应用程序时，您会注意到所有面板标题都居中对齐。虽然可以通过这种方式覆盖任何 Ext JS 组件配置，但最佳做法是仅使用覆盖来更改影响组件的视觉外观（而不是功能）的配置。

修改图像资产

默认情况下，所有必需的图像资产都从父主题继承，但在某些情况下，您可能需要覆盖图像。这可以通过将所需的图像放在 my-theme/resources/images/ 中并为其指定与它打算从基本主题覆盖的图像相同的名称来轻松完成。

在许多现代主题（如 theme-triton）中，几乎没有图像。这些主题使用矢量字体图标。因此，您可以用这种方式替换的图像取决于您选择的基准主题。

添加自定义实用程序

如果您的主题需要与组件样式无关的功能或混合（例如实用程序），则应将它们放在主题的 my-theme/sass/etc 目录中。

您可以根据需要整理此目录中的文件，但 Sencha Cmd 在构建中包含的唯一文件是 my-theme/sass/etc/all.scss。所有其他文件都必须由 all.scss 文件导入（@import）。有关遵循此模式的示例，请参阅 ext/classic/theme-base/sass/etc/。

为您的应用程序设置样式

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

为应用程序的视图设置样式

要编写与应用程序视图关联的 CSS 规则，您需要在同一文件夹中创建一个 .scss 文件，其基本名称与视图相同。例如，要设置视图 App.view.main.Main 的样式，您可以在该文件夹中添加 Main.scss

demo-app/
   app/
      view/
         main/
            Main.js
            Main.scss
            MainController.js
            MainModel.js

虽然添加任意 CSS 样式的能力提供了最大的灵活性，但最好避免直接设置 Ext JS 组件拥有的元素的样式。相反，应尽可能使用 Ext JS 主题 API 设置它们的样式。使用主题 API 可以保护您的样式免受未来版本 Ext JS 中的标记更改的影响。

在您的应用程序中更改主题变量

应用程序充当主题层次结构中的最终级别。因此，应用程序可以更改主题变量。

让我们继续使用上面创建的 demo-app 应用程序，并在应用程序中覆盖主题的 $base-color。创建 Application.scss 文件

demo-app/
   app/
      Application.js
      Application.scss

Application.scss 文件是全局设置的简单选项，因为它与 Application 类的全局性质相匹配。并向此文件添加以下内容

$base-color: #724289;

在浏览器中查看应用程序，您将看到基本颜色已更改为紫色。

在应用程序中设置主题

要在应用程序中执行重要的主题工作，您应该以与主题相同的方式创建一个 sass 文件夹结构，并告知 Sencha Cmd 您的样式适用于所有命名空间（不仅仅是应用程序）。通常位于主题的 sass 文件夹中的代码可以放在应用程序的 sass 文件夹中。

Sass 命名空间

当 Sencha Cmd 构建您的样式时，它会查看应用程序中使用的所有 JavaScript 类。然后，它会包含所有与这些类相符的 .scss 文件。此过程使用 sass.namespace 将类名（例如 Ext.button.Button）与包、主题或应用程序的磁盘上的文件对齐。

例如，在主题中，您可能拥有文件 sass/var/button/Button.scss 和文件 sass/src/button/Button.scss。这些文件将被视为匹配，因为主题的默认 sass.namespace 是 Ext。

但是，应用程序的默认 sass.namespace 是其自己的命名空间（App）。这意味着 Sencha Cmd 不会将 demo-app/sass/var/button/Button.scss 识别为 Ext.button.Button 类的匹配项。相反，它将匹配 App.button.Button。要包含与所有命名空间匹配的文件，您需要在 app.json 中将 sass.namespace 设置为空字符串

"sass": {
    "namespace": ""
}

进行此更改后，Sencha Cmd 将 demo-app/sass/var/Ext/button/Button.scss 和 demo-app/sass/src/Ext/button/Button.scss 与 Ext.button.Button 匹配。

这也意味着，如果您想使用 sass 文件夹来组织视图的样式，您将需要使用 App 子文件夹。例如，sass/src/App/view/main/Main.scss 是将匹配 App.view.main.Main 的路径。虽然这是以前版本中的模式，并且仍然受支持，但将视图样式放在与其 .js 文件并排的 .scss 文件中（如前所述）是一种更易于维护的结构。

生成样式的组织

Sencha Cmd 在编译应用程序时会组合来自主题、应用程序和任何必需包的样式（请参阅 Sencha Cmd 包指南）。了解 Sencha Cmd 组合这些文件的方式非常重要，这样您就知道可以从主题或必需包中使用什么，以及这些内容何时可用。

all.scss 文件的结构如下

+---------------------------------------+
| inclusion flags                       |
+-----------+-----------+---------------+
|           |           | base          |
|           | theme     +---------------+
|           |           | derived       |
|           +-----------+---------------+
|           |                           |
|    etc    | packages (dep order)      |
|           |                           |
|           +---------------------------+
|           |                           |
|           | application               |
|           |                           |
+-----------+---------------------------+
|           |           | base          |
|           | theme     +---------------+
|           |           | derived       |
|           +-----------+---------------+
|           |                           |
|    var    | packages (dep order)      |
|           |                           |
|           +---------------------------+
|           |                           |
|           | application               |
|           |                           |
+-----------+-----------+---------------+
|           |           | base          |
|           | theme     +---------------+
|           |           | derived       |
|           +-----------+---------------+
|           |                           |
|    src    | packages (dep order)      |
|           |                           |
|           +---------------------------+
|           |                           |
|           | application (*)           |
|           |                           |
+-----------+---------------------------+

    * - Includes application styles that are placed
        next to their corresponding .js files.

在 sass/var 和 sass/src 的频段内，给定主题、包和应用程序的各个 .scss 文件始终按顺序排列，以匹配 JavaScript 类层次结构。例如，如果 base 主题在其 sass/var 文件夹中具有 Ext.Container 和 Ext.Component 的 .scss 文件，则 Ext.Component 的文件将包含在 Ext.Container 的文件之前，因为它扩展了 Ext.Component。

此结构的目标和基本原理如下

• sass/etc 中包含实用程序等
  • 基本主题的实用程序可供派生主题使用。
  • 包实用程序可以使用当前主题提供的功能。
  • 应用程序实用程序能够使用其主题和任何必需的包。
• 在 sass/var 中，关注的是变量控制和派生计算。
  • 主题排在第一位，以便为其变量设置值。
  • 派生主题可以更改变量，因为它们遵循其基本主题。
  • 包变量按其包依赖顺序引入。
  • 应用程序排在最后，以便其变量覆盖主题和包。
• 对于 sass/src，此顺序产生适当的规则级联，以便
  • 派生主题规则胜过其基本主题的规则。
  • 应用程序规则最后级联，以便它们始终具有最终权限。

包含标志

包含标志变量是一组只读变量，定义为 true 或 false，适用于可能包含的每个 JavaScript 类。如果该类包含在应用程序构建中，则此变量的值为 true。Sencha Cmd 以 $include- 前缀动态创建这些变量，后跟完整类名，其部分由 -（而不是 .）分隔，且全部为小写。例如，如果构建使用 Ext.Img，则可以在自定义混合中测试 true

@if $include-ext-img {
    // styling contingent upon the presence of Ext.Img in the app
}

注意：在指南的大部分内容中，我们提倡使用 sencha app watch 来增量构建应用程序，因为应用程序和自定义主题都会发生更改。但是，$include- 变量在开发中全部设置为 true（这是 sencha app watch 运行的环境）。为了测试主题对 $include- 变量检查的使用，您需要构建应用程序进行测试或生产

$ sencha app build --testing
$ sencha app build --production

在应用程序之间共享主题

您可以轻松地将刚刚构建的主题与第二个应用程序共享。只需导航到工作区目录并运行以下命令（注意：如果您按照上述步骤操作并运行 sencha app watch，则首先需要使用 Ctrl+C 结束它）

$ mkdir another-app
$ cd another-app

$ sencha app init --ext65 --modern (or --classic) AnotherApp

这告诉 Sencha Cmd 在 another-app 目录中生成一个名为 AnotherApp 的应用程序，并使用与您创建的第一个应用程序相同的 Ext JS SDK。

下一步是告诉应用程序使用自定义主题。编辑 another-app/app.json 并将主题更改为

"theme": "my-theme",

为了确保在进行更改时拾取应用程序和主题的更改，请再次将工作目录更改为应用程序目录并运行

$ sencha app watch --fashion

当您在浏览器中查看 another-app/index.html 页面时，您现在将看到一个使用与 App 相同自定义主题的启动应用程序。

后续步骤

这些涵盖了所有 Ext JS 主题的通用概念和常见做法。有关每个工具包的具体信息，请参阅以下指南：Ext JS Modern 工具包主题和Ext JS Classic 工具包主题。

Ext JS Modern 工具包主题指南

在本指南中，我们将逐步了解 Ext JS 6.2 中引入的现代工具包主题的变化。有很多令人兴奋的新变化，可以提供更简单的主题、动态更新等等。随着这些更新，还有一些您应该了解的新概念。

让我们讨论现代工具包中主题的约定和最佳做法。

动态变量

所有变量都使用dynamic()指示符定义。这确保了最后一个变量声明获胜并在整个范围内保持有效。此外，变量可以相互派生，而无需考虑顺序。

例如

$calendar-days-time-color: dynamic($color);

文件命名

所有非规则生成代码都放置在主题的sass/var/目录中，该目录中的文件与组件的类名匹配。这通常包括所有组件变量和 UI 混合声明。

由于所有var文件都包含在构建中，无论是否实际需要相应的类，这允许变量自由地派生自任何其他变量。将混合包含在sass/var/目录中可确保派生的主题可以在sass/src/目录中的任何代码调用它们之前覆盖这些混合。

所有规则生成代码都位于主题的sass/src/目录中，该目录中的文件与组件的类名匹配。这包括对 UI 混合的调用以及不包含在混合正文内的规则。

在构建时，仅当需要相应的组件时才包含src文件。这确保了仅将所需的规则包含在 CSS 输出中。

基本样式与可配置样式

与组件的核心功能相关的布局特定样式和样式放置在theme-base/sass/src/文件夹中，该文件夹中的文件与组件的类名匹配。在这些规则中设置的属性不可使用变量配置，因为更改它们可能会破坏组件的功能或布局。

通常不可配置的 CSS 属性示例有

• 显示
• 可见性
• 位置
• 溢出
• z 索引

与组件的核心功能或布局无关的可配置样式使用变量控制。这些变量在theme-neptune/sass/var目录中与组件的类名匹配的scss文件中定义。使用这些变量的规则包含在同一文件中的 UI 混合中。

常见可配置样式的示例有

• 背景色
• 颜色
• 填充
• 边框半径
• 字体大小

Neptune 主题是所有其他主题的基础，并且包含框架支持的主题功能，即使它本身可能不会全部使用它们。

派生自theme-neptune的主题通常不会定义新的 UI 混合或创建自己的 CSS 规则。相反，它们只是设置theme-neptune中定义的变量的值。

变量命名约定

组件变量以 xtype 开头，并以要设置样式的 CSS 属性名称结尾，例如

$button-font-family: dynamic(helvetica);
$button-color: dynamic(#fff);
$button-background-color: dynamic(red);

如果组件具有各种状态，例如悬停、聚焦和按下，则状态的名称紧跟在 xtype 之后，但在 CSS 属性名称之前

$button-hovered-background-color: dynamic(blue);

如果组件具有控制子元素样式的变量，则要设置样式的子元素的名称包含在 xtype 和状态（如果存在）之后。

例如，在设置按钮的“徽章”元素的样式时

$button-badge-color: dynamic(#fff);
$button-hovered-badge-color: dynamic(green);

如果“状态”是指子元素的状态，则它位于该元素名称之后。例如，如果选项卡具有与选项卡分开的悬停状态的关闭图标

$tab-close-icon-hovered-background-color: dynamic(red);

组件具有用于边框宽度、边框颜色和边框样式的单独变量，并且所有三个属性都接受单个值或值列表，以便在需要时可以分别指定 4 个边

$button-border-color: dynamic(red yellow green blue);
$button-border-width: dynamic(1px 3px);
$button-border-style: dynamic(solid);

变量使用以下名称表示组件状态

• 当用户按下组件或组件处于按下状态时，“按下”
• 如果组件具有与“按下”分开的“按下”状态，则为“按下”
• 当鼠标指针位于元素上方时，“悬停”
• 当元素获得焦点时，“聚焦”
• 当组件被禁用时，“禁用”。

由于“聚焦”有时可以与其他状态组合，因此组件可以提供表示状态组合的变量，例如

$button-focused-pressed-border-color

普通模式和大模式

每个主题都有两种尺寸模式：普通模式和大模式。大模式会增加间距和尺寸，以更适合触摸屏。主题通过检查主题的overrides/init.js中的Ext.platformTags，并在页面上的<html>元素中添加x-big的 CSS 类名，来选择是否使用大模式。例如，Triton 主题仅在手机上加载时才启用大模式，否则它会使用普通模式。

Ext.theme.getDocCls = function() {
    return Ext.platformTags.phone ? 'x-big' : '';
};

设置影响组件视觉大小的属性（如字体大小、行高和内边距）的变量都有大变量对应。大变量的末尾始终附加-big后缀

$button-padding: dynamic(1rem);
$button-padding-big: dynamic(1.2rem);

CSS 规则使用 .x-big 选择器来定位大模式

.#{$prefix}button {
    padding: $padding;

    .#{$prefix}big & {
        padding: $padding-big;
    }
}

组件 UI

大多数组件都有一个 UI 混合，用于生成该组件的多个视觉呈现。这些混合命名为[xtype]-ui。例如button-ui或panel-ui。

UI 混合为组件的每个全局变量都有一个参数。此外，参数名称与全局变量名称相同。唯一的例外是混合参数的名称中不包含 xtype。

例如，名为$button-border-radius的全局变量将对应于名为$border-radius的button-ui混合的参数。

UI 混合的参数默认为null，如果调用方未指定，则不会产生任何输出。这意味着当调用混合时，它会生成一组样式，表示与默认 UI 的增量。这最大限度地减少了创建新 UI 所需的 CSS 规则数，因为混合会自动从输出中消除所有null值。

默认 UI 的样式使用不包含 UI 名称的 CSS 类名应用。例如，x-button，而不是x-button-default。这是最大限度地减少创建其他 UI 所需规则数的关键。例如，所有按钮都将具有x-button类以及一个或多个可选的x-button-[ui]类。它允许默认 UI 作为所有其他 UI 的基本样式集。

要生成其他 UI，请仅调用传递与默认 UI 不同的参数的混合。例如，以下混合调用生成一个名为“操作”的 UI，该 UI 在默认 UI 的基础上通过将背景色更改为红色来构建，但通过级联继承默认 UI 的所有其他属性。此 UI 调用的输出是最小的。它仅包含设置背景色所需的规则，不包含其他任何内容。

@include button-ui(
    $ui: 'action',
    $background-color: red
);

派生 UI

具有 UI 混合的组件的子类通常有自己的 UI 混合和一组用于配置该混合的全局变量。

默认值与超类变量不同的子类变量将为null。这确保它们将通过父 CSS 类继承正确的值，而不是重新定义冗余值。

组件使用设置为x-[xtype]的classCls来完成此继承（请参阅下面关于 CSS 类名的部分）。

此模式的一个示例是扩展工具栏的网格分页工具栏组件

// theme-neptune/sass/var/grid/plugin/PagingToolbar.scss
$pagingtoolbar-background-color: dynamic(null);

@mixin pagingtoolbar-ui(
    $ui: null,
    $xtype: pagingtoolbar,
    $background-color: null,
    $prev-icon: null
) {
    $ui-suffix: ui-suffix($ui);

    // Call base toolbar mixin.
    // Only produces output for non-null parameters
    @include toolbar-ui(
        $ui: $ui,
        $xtype: $xtype,
        $background-color: $background-color
    );

    // paging toolbar specific styles
    .#{$prefix}#{$xtype}#{$ui-suffix} {
        .#{$prefix}icon-prev {
            @include icon($prev-icon);
        }
    }
}

// theme-neptune/sass/src/grid/plugin/PagingToolbar.scss
@include pagingtoolbar-ui(
    $background-color: $pagingtoolbar-background-color;
);

在派生主题中配置主题 UI

主题提供的其他 UI 通常无法通过全局变量配置，或者至少无法过度配置。相反，这些 UI 被包装在它们自己的混合中，派生主题可以覆盖这些混合以更改参数

@mixin button-action-ui() {
    @include button-ui(
        $ui: 'action',
        $background-color: red
    );
}

主题为每个其他 UI 提供一个变量，该变量默认为“true”，但可以覆盖为“false”以禁用 UI 的生成。此变量将与相应的混合具有相同的名称

@if $button-action-ui {
    @include button-action-ui;
}

可组合 UI

UI 通常是可组合的。例如，如果需要两种单独的按钮呈现，一个红色的“操作”按钮和一个圆形的红色“操作”按钮，只需创建一个“操作”UI 和“圆形”UI

// sass/var
$button-action-ui: dynamic($enable-default-uis);
$button-confirm-ui: dynamic($enable-default-uis);

@mixin button-action-ui() {
    @include button-ui(
        $ui: 'action',
        $background-color: red
    );
}

@mixin button-round-ui() {
    @include button-ui(
        $ui: 'round',
        $border-radius: 10000px
    );
}

// sass/src
@if $button-action-ui {
    @include button-action-ui
}

@if $button-round-ui {
    @include button-round-ui
}

要组合 UI，只需在组件配置中使用任意数量的 UI 名称，并用空格分隔

ui: 'action round'

如果多个 UI 设置相同的属性，则级联中的最后一个 UI 获胜，即最后一个被调用的混合获胜。可组合 UI 通常努力将其关注领域限制在样式的各个方面（颜色、大小、边框半径等），以便在组合它们时几乎没有歧义。

使用可组合用户界面可确保生成的 CSS 代码保持非常 DRY，避免不必要的 CSS 规则重复。在上面的示例中，我们避免了对可能需要圆角的每个用户界面的 background-color 规则进行重复。任何用户界面都可以与“round”用户界面组合以添加圆角。

CSS 类名

保持 CSS 类名命名一致性非常重要，因为它们在向框架中的组件生成的 DOM 元素添加语义和结构方面发挥着主要作用。这种命名一致性有两个目的

1. 它提高了 SASS 代码的可读性和可维护性，并减少了出错的可能性。
2. 对于不使用 API 的用户，它提供了一个清晰易懂的 DOM 结构以进行样式设置。

主元素和用户界面 CSS 类

组件在其主元素上具有 x-[xtype] 的类名。例如，文本字段组件将具有 x-textfield 的 CSS 类名。

组件有两种可能的方法来设置此主 CSS 类。它们可以在其类定义的主体上设置 classCls 或 baseCls，尽管首选 classCls。设置其中任何一个都将向主元素添加 CSS 类，并将其用作也添加到主元素中的特定于用户界面的类名的前缀。classCls 和 baseCls 配置仅在可继承性上有所不同。classCls 由子类继承，并且是这些子类的 classCls 的补充，而 baseCls 则不是。

此外，在使用 classCls 时，将为类层次结构中的每个 classCls 添加一个特定于用户界面的 CSS 类名。例如，一个“ui”设置为 foo 的 Ext.field.Password 组件将具有以下用户界面类

• x-passwordfield-foo
• x-textfield-foo
• x-field-foo

此模式确保样式通过类层次结构正确继承，并允许组件仅为它们添加的功能提供样式。对于不希望继承样式的边缘情况，组件可以设置 classClsRoot:true 以防止从祖先继承 classCls。

引用元素 CSS 类

引用元素遵循模式 x-[referencePrefix]-el。例如，表单字段的 bodyElement 引用元素将具有 CSS 类 x-body-el。为了保持一致性，元素引用将在 JavaScript 侧具有 Element 后缀。CSS 类名上的 -el 后缀有助于将引用元素与具有相同名称的 xtype 的潜在组件区分开来。

用于组件配置和状态的 CSS 类

反映组件配置的 CSS 类名遵循模式 x-[configName]-[configValue]，并放置在组件的主元素上。例如，具有 labelAlign: 'left' 配置的表单字段在主元素上添加了 x-label-align-left 的 CSS 类名。

布尔配置的 CSS 类名通常遵循以下两种模式之一

1. 真值会导致添加新类。例如，当值为 true 时，具有 checked 配置的复选框将具有 x-checked CSS 类，但当值为 false 时不会具有该类。

2. 假值会导致添加新类。当默认值为 true 且组件仅在假值状态下需要额外样式时，这有时很有用。例如，当 rowLines 配置为 false 时，List 组件具有 x-no-row-lines CSS 类。

同样，反映组件状态的类名遵循模式 x-[state]，并放置在组件的主元素上。

例如，处于按下状态的按钮将在其主元素上具有类 x-pressed。

在主元素上设置组件状态和配置 CSS 类，而不是在引用元素上设置，允许组件限定状态或配置。即使类仅影响子元素或元素的样式，这也是正确的。这样还可以得到一个更稳定的 DOM 结构，因为即使修改了内部 DOM 结构，这些类名也不会改变位置。

CSS 选择器

由于引用、配置和状态 CSS 类在其名称中不包含 xtype 信息，因此必须将它们与组件的 classCls 或 baseCls 结合使用，以避免与可能具有相同配置或状态类名的其他组件冲突。例如，要设置按钮主元素的按下状态的样式，可以使用以下选择器

.x-button.x-pressed

UI 混合使用 UI 特定的 CSS 类名与引用、配置和状态 CSS 类结合使用。例如，如果按钮的 UI 为“foo”，则可以按如下方式设置按下状态的样式

.x-button-foo.x-pressed

子项与后代选择器

在设置组件内部元素的样式时，应优先使用后代选择器（例如 .x-foo .x-bar），而不是直接子项选择器（例如 .x-foo > .x-bar）。这样可以使标记更灵活，并允许它容忍更多更改，例如在 x-foo 和 x-bar 之间插入一个包装元素，而不会破坏样式。

此规则的唯一例外是存在嵌套的可能性。例如，面板可以使用 .x-panel > .x-body-el 这样的选择器，以便仅设置其自身的主体元素的样式，而不是嵌套在其中的其他面板的主体元素的样式。在某些情况下，当容器元素与其子项之间存在数量可变的 DOM 元素时，UI 特定的类名会添加到子项元素。

Ext.Container 就是一个例子。它为其 innerElement 添加了每个 classCls 的 UI 特定的类，因为 innerElement 和元素之间可能存在数量可变的 DOM 祖先，具体取决于容器是否有停靠项。

Ext JS Classic 工具包的主题

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

要求

本指南假设您已满足 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 拉取您的应用程序

http://localhost:1841/demo-app/

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

主题组件

如上一个 指南 中所述，组件的主题 API 由变量和混合组成。组件的默认外观由其变量决定，而自定义外观可以通过调用“UI 混合”来定义和命名。

配置主题变量

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

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

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

使用主题混合

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

theme-neutral 主题包含许多不同的 Ext JS 组件的主题混合（或 UI 混合）。你可以调用这些混合来为组件生成新的 ui。每个组件的可用混合在 API 文档中列出。例如，请参阅 Ext.panel.Panel 并向下滚动到“主题混合”部分，了解 Panel UI 混合接受哪些参数。让我们使用此混合来创建自定义 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
);

此混合调用创建一个名为 "highlight" 的新 Panel ui，它具有红色标题背景、红色边框、5px 边框、5px 边框半径和白色文本。要使用此 ui，请使用 'highlight' 作为其 ui 属性（以及 frame: true）配置 Panel。打开 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 混合是配置组件多种外观的便捷方式，但它们不应该被过度使用。每次调用 UI 混合都会生成额外的 CSS 规则。对 UI 混合的过多调用可能会产生过大的 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。此图像资产将优先于 my-workspace/ext/classic/theme-crisp/resources/images/shared/icon-info.png 中父 Crisp 主题中使用的图像资产。

现在修改你的测试应用程序以显示使用自定义图标的 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 文件，其基本名称与视图相同。例如，要设置视图 App.view.main.Main 的样式，该视图位于 demo-app/app/view/main/Main.js 中，你应将该代码放入 demo-app/app/view/main/Main.scss 中。

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

.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'
...

查看您的应用程序，您会看到用户视图中的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"的混合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 时，您需要为应用程序中使用的每个比例提供按钮混合。

注意：应该避免使用extjs-button-ui混合来支持使用特定于比例的混合样式按钮。

@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
);

在使用-toollbar按钮混合时也适用相同的情况。每个都有一个比例，并且应该分别包含在Button.scss文件中以支持所有按钮比例。此外，在使用-toolbar按钮混合时，您需要将-toolbar添加到应用程序中按钮的ui配置。下面是一个小工具栏按钮混合的示例

@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配置ui: 'highlight'，则生成的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 文件中的$ui名称中添加-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时，需要将选项卡栏 ui 图像从父主题复制到自定义主题。有关更多详细信息，请参阅上面的“'default' 组件图像”部分。

注意：使用 extjs-tab-bar-ui 混合创建 TabBar ui 时，您需要创建同名的相应 tab-ui。

这将确保标签在您的主题中正确呈现。不创建匹配的标签主题可能会导致标签呈现不可预测。

Ext.toolbar.Toolbar

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

从 Ext JS 5.x 升级

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

在 sass/etc/all.scss 中定义的任何变量都应移动到 sass/var/all.scss（或由 sass/var/all.scss @import 的 .scss 文件）。

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

（推荐）将自定义主题文件夹从应用程序/工作空间中的根 packages/ 文件夹重新放置到 packages/local/。