主题化 Ext JS

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

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

从历史上看，为应用程序设置样式意味着创建包含规则的样式表，以调整或装饰用于呈现组件的单个 HTML 元素。这种方法会带来一些问题。第一个问题是，您现在需要跨所有支持的浏览器进行样式设置。其次，随着框架的演变，组件的底层元素可能会发生变化，这会让您面临着在样式规则中追逐这些变化的不愉快任务。使用 Ext JS 主题 API 为组件设置样式可以为您解决这些问题。

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

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

要求

Sencha Cmd 6.5+

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

Java JRE

运行 Sencha Cmd 需要 Java JRE。我们建议尽可能运行最新版本的 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

配置应用程序的主题

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

"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 的基本方法相同：它们定义变量来配置组件的默认外观，并提供可以生成自定义外观的 mixin。这些自定义外观被分配您选择的名称，这些名称使用 ui 配置属性应用于组件实例。由于与 ui 配置的关系，这些 mixin 通常被称为“UI mixin”或“主题 mixin”。

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

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

配置主题变量

让我们从修改 $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，此顺序会产生正确的规则级联，以便
  • 派生主题规则胜过其基本主题的规则。
  • 应用程序规则最后级联，因此它们始终具有最终权限。

包含标志

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

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

注意：在大多数指南中，我们建议使用 sencha app watch 来增量构建应用程序，以对应用程序和自定义主题进行更改。但是，$include- 变量在开发中（sencha app watch 在其中运行的环境）都设置为 true。为了测试主题对 $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 工具包主题。