Modern Toolkit 中的主题
许多类在创建（实例化）具有配置对象的类时都有快捷名称。快捷名称被称为 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 - 示例中未显示），紧随成员描述之后Defaults to: false）API 文档使用许多标志来进一步传达类成员的功能和意图。标签可以用文本标签、缩写或图标表示。
classInstance.method1().method2().etc();false，则标记为可预防的事件将不会触发- 表示框架类
- Singleton 框架类。 *有关更多信息，请参阅 singleton 标志
- 组件类型框架类（Ext JS 框架中扩展 Ext.Component 的任何类）
- 表示类、成员或指南在当前查看的版本中是新的
- 表示 config 类型的类成员
- 表示 property 类型的类成员
- 表示 method 类型的类成员
- 表示 event 类型的类成员
- 表示 theme variable 类型的类成员
- 表示 theme mixin 类型的类成员
- 表示类、成员或指南在当前查看的版本中是新的
在 API 文档页面的类名正下方是一行按钮，对应于当前类拥有的成员类型。每个按钮显示按类型划分的成员计数（此计数会随着过滤器的应用而更新）。单击按钮将导航到该成员部分。将鼠标悬停在成员类型按钮上将显示该类型的所有成员的弹出菜单，以便快速导航。
与类 config 选项相关的 Getter 和 setter 方法将显示在方法部分以及 API 文档和成员类型菜单的 config 部分中，就在它们工作的 config 下方。Getter 和 setter 方法文档将在 config 行中找到，以便于参考。
您的页面历史记录保存在本地存储中，并在顶部标题栏下方显示（使用可用的实际空间）。默认情况下，显示的唯一搜索结果是与您当前查看的产品/版本匹配的页面。您可以通过单击历史记录栏右侧的 按钮并选择“全部”单选选项来扩展显示的内容。这将显示历史记录栏中所有产品/版本的所有最近页面。
在历史记录配置菜单中，您还将看到最近访问页面的列表。结果由“当前产品/版本”和“全部”单选选项过滤。单击 按钮将清除历史记录栏以及本地存储中保存的历史记录。
如果在历史记录配置菜单中选择“全部”，则将启用“在历史记录栏中显示产品详细信息”的复选框选项。选中后，每个历史页面的产品/版本将在历史记录栏中的页面名称旁边显示。将光标悬停在历史记录栏中的页面名称上方也会显示产品/版本作为工具提示。
可以使用页面顶部的搜索字段搜索 API 文档和指南。
在 API 文档页面上，还有一个过滤器输入字段，该字段使用过滤器字符串过滤成员行。除了按字符串过滤外，您还可以按访问级别、继承和只读过滤类成员。这是通过使用页面顶部的复选框完成的。
API 类导航树底部的复选框过滤类列表，以包含或排除私有类。
单击空的搜索字段将显示您最近的 10 次搜索，以便快速导航。
每个 API 文档页面（JavaScript 原始类型页面除外）都有一个与该类相关的元数据菜单视图。此元数据视图将具有以下一项或多项
Ext.button.Button 类具有 Ext.Button 的备用类名）。备用类名通常为了向后兼容性而维护。可运行的示例 (Fiddles) 默认在页面上展开。您可以使用代码块左上角的箭头单独折叠和展开示例代码块。您还可以使用页面右上角的切换按钮切换所有示例的折叠状态。切换所有状态将在页面加载之间记住。
类成员默认在页面上折叠。您可以使用成员行左侧的箭头图标或右上角的展开/折叠所有切换按钮全局展开和折叠成员。
在较窄的屏幕或浏览器上查看文档将导致针对较小外形尺寸优化的视图。桌面视图和“移动”视图之间的主要区别在于
可以通过单击 API 文档页面顶部的类名来查看类源代码。可以通过单击成员行右侧的“查看源代码”链接来查看类成员的源代码。
在本指南中，我们将逐步介绍 Ext JS 6.2 中 modern toolkit 引入的主题更改。有很多令人兴奋的新变化，可以更轻松地进行主题设置、动态更新等等。随着这些更新，您应该了解一些新概念。
让我们讨论 modern toolkit 中主题设置的约定和最佳实践。
所有变量都使用 dynamic() 指示符定义。这确保了最后一个变量声明获胜并在整个范围内保持有效。此外，变量可以彼此派生，而无需担心顺序。
例如
$calendar-days-time-color: dynamic($color);
所有非规则生成代码都放置在主题的 sass/var/ 目录中，文件名与 Component 的类名匹配。这通常包括所有组件变量和 UI mixin 声明。
由于所有 var 文件都包含在构建中，无论是否实际需要相应的类，这都允许变量自由地从任何其他变量派生。在 sass/var/ 目录中包含 mixin 可确保派生主题可以在 sass/src/ 目录中的任何代码调用这些 mixin 之前覆盖它们。
所有规则生成代码都位于主题的 sass/src/ 目录中，文件名与 Component 的类名匹配。这包括对 UI mixin 的调用以及不包含在 mixin 主体内的规则。
在构建时，只有在需要相应的 Component 时才包含 src 文件。这确保了 CSS 输出中仅包含所需的规则。
布局特定样式和与 Component 核心功能相关的样式放置在 theme-base/sass/src/ 文件夹中，文件名与 Component 的类名匹配。这些规则中设置的属性不能使用变量配置，因为更改它们可能会破坏 Component 的功能或布局。
通常不可配置的 CSS 属性示例包括
与组件的核心功能或布局无关的可配置样式使用变量控制。这些变量在 theme-neptune/sass/var 目录中与组件类名匹配的 scss 文件中定义。使用这些变量的规则包含在同一文件中的 UI mixin 中。
常见的可配置样式示例包括
Neptune 主题是所有其他主题的基础，包含框架支持的主题功能，即使它本身可能并非全部使用。
从 theme-neptune 派生的主题通常不定义新的 UI mixin 或创建自己的 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 和状态（如果存在）之后。
例如，在设置按钮的“badge”元素的样式时
$button-badge-color: dynamic(#fff);
$button-hovered-badge-color: dynamic(green);
如果“state”指的是子元素的状态，则它位于该元素的名称之后。例如，如果选项卡有一个关闭图标，该图标具有与选项卡不同的悬停状态
$tab-close-icon-hovered-background-color: dynamic(red);
组件具有单独的变量用于 border-width、border-color 和 border-style，所有这三个属性都接受单个值或值列表，以便可以在需要时单独指定 4 个边
$button-border-color: dynamic(red yellow green blue);
$button-border-width: dynamic(1px 3px);
$button-border-style: dynamic(solid);
变量使用以下名称来指示组件状态
由于“focused”有时可以与其他状态组合，因此组件可能会提供指示状态组合的变量，例如
$button-focused-pressed-border-color
每个主题都有两种尺寸模式：正常和大。大模式增加了间距和尺寸，使其更适合触摸屏。主题通过检查主题的 overrides/init.js 中的 Ext.platformTags 并将 x-big 的 CSS 类名添加到页面上的 <html> 元素来选择是否使用大模式。例如，Triton 主题仅在手机上加载时启用大模式，否则，它使用正常模式。
Ext.theme.getDocCls = function() {
return Ext.platformTags.phone ? 'x-big' : '';
};
设置影响组件视觉尺寸的属性（如 font-size、line-height 和 padding）的变量具有大的对应项。大变量始终在末尾附加 -big 后缀
$button-padding: dynamic(1rem);
$button-padding-big: dynamic(1.2rem);
CSS 规则使用 .x-big 选择器定位大模式
.#{$prefix}button {
padding: $padding;
.#{$prefix}big & {
padding: $padding-big;
}
}
大多数组件都有一个 UI mixin，用于生成该组件的多个视觉效果。这些 mixin 被命名为 [xtype]-ui。例如 button-ui 或 panel-ui。
UI mixin 为每个组件的全局变量都有一个参数。此外，参数名称与全局变量名称相同。唯一的例外是 mixin 参数的名称中不包含 xtype。
例如，名为 $button-border-radius 的全局变量将对应于名为 $border-radius 的 button-ui mixin 的参数。
UI mixin 的参数默认为 null，如果调用者未指定，则不会产生任何输出。这意味着当调用 mixin 时，它会生成一组样式，这些样式表示与默认 UI 的增量。这最大限度地减少了创建新 UI 所需的 CSS 规则数量，因为 mixin 会自动从输出中消除任何 null 值。
默认 UI 的样式使用不包含 UI 名称的 CSS 类名应用。例如，x-button，而不是 x-button-default。这是最大限度地减少创建其他 UI 所需规则数量的关键。例如，所有按钮都将具有 x-button 类以及一个或多个可选的 x-button-[ui] 类。它允许默认 UI 充当所有其他 UI 的基本样式集。
要生成其他 UI，请调用 mixin，仅传递与默认 UI 不同的参数。例如，以下 mixin 调用生成一个名为“action”的 UI，该 UI 通过将 background-color 更改为 red 来构建在默认 UI 之上，但通过级联从默认 UI 继承所有其他属性。此 UI 调用的输出最少。它仅包含设置 background-color 所需的规则，没有其他内容。
@include button-ui(
$ui: 'action',
$background-color: red
);
具有 UI mixin 的 Component 的子类通常有自己的 UI mixin 和一组完整的全局变量，用于配置该 mixin。
与超类变量没有不同默认值的子类变量将为 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 被包装在它们自己的 mixin 中，派生主题可以覆盖这些 mixin 以更改参数
@mixin button-action-ui() {
@include button-ui(
$ui: 'action',
$background-color: red
);
}
主题为每个附加 UI 提供一个变量，该变量默认为“true”，但可以覆盖为“false”以禁用 UI 的生成。此变量将具有与相应 mixin 相同的名称
@if $button-action-ui {
@include button-action-ui;
}
UI 通常是可组合的。例如，如果需要两个单独的按钮渲染，一个红色“action”按钮和一个圆形红色“action”按钮，只需创建一个“action”UI 和“round”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，只需在组件 config 中使用任意数量的 UI 名称，以空格分隔
ui: 'action round'
如果多个 UI 设置相同的属性，则获胜者是级联中的最后一个，即最后调用的 mixin。可组合 UI 通常力求将其关注领域限制在样式的不同方面（颜色、尺寸、边框半径等），以便在组合它们时几乎没有歧义。
使用可组合 UI 可确保生成的 CSS 代码保持非常 DRY（不要重复自己），从而避免不必要的 CSS 规则重复。在上面的示例中，我们避免了每个可能需要圆角的 UI 的 background-color 规则的重复。任何 UI 都可以与“round”UI 组合以添加圆角。
保持 CSS 类名命名的一致性非常重要，因为它们在向框架中 Components 生成的 DOM 元素添加语义和结构方面起着重要作用。这种命名一致性有两个目的
Components 在其主元素上具有 x-[xtype] 的类名。例如，TextField 组件将具有 x-textfield 的 CSS 类名。
Components 有两种可能的方式来设置此主 CSS 类。它们可以在其类定义的主体上设置 classCls 或 baseCls，尽管 classCls 是首选。设置其中任何一个都将 CSS 类添加到主元素，并将其用作也添加到主元素的 UI 特定类名的前缀。classCls 和 baseCls config 仅在可继承性上有所不同。classCls 由子类继承，并且是对这些子类的 classCls 的补充，而 baseCls 则不是。
此外，当使用 classCls 时，将为类层次结构中的每个 classCls 添加 UI 特定 CSS 类名。例如，将“ui”设置为 foo 的 Ext.field.Password 组件将具有以下 UI 类
此模式确保样式在类层次结构中正确继承，并允许 Components 仅为其添加的功能提供样式。对于不希望继承样式的情况，Components 可以设置 classClsRoot:true 以防止从祖先继承 classCls。
参考元素遵循模式 x-[referencePrefix]-el。例如，表单字段的 bodyElement 参考元素将具有 CSS 类 x-body-el。为了保持一致性，元素参考将在 JavaScript 端具有 Element 后缀。CSS 类名上的 -el 后缀有助于区分参考元素和可能具有相同 xtype 的 Component。
反映 Component 配置的 CSS 类名遵循模式 x-[configName]-[configValue]，并放置在 Component 的主元素上。例如，具有 labelAlign: 'left' config 的表单字段在主元素上添加了 x-label-align-left 的 CSS 类名。
布尔值 config 的 CSS 类名通常遵循以下两种模式之一
真值导致添加新类。例如，具有 checked config 的复选框在值为 true 时将具有 x-checked CSS 类，但在为 false 时不会具有该类。
假值导致添加新类。当默认值为 true 并且组件仅在假值状态下需要其他样式时，这有时很有用。例如，当 rowLines 配置为 false 时，List 组件具有 x-no-row-lines CSS 类。
同样，反映 Component 状态的类名遵循模式 x-[state]，并放置在 Component 的主元素上。
例如，处于按下状态的按钮将在其主元素上具有类 x-pressed。
在主元素而不是参考元素上设置 Component 状态和配置 CSS 类允许将状态或配置限定为 Component 的范围。即使这些类仅影响子元素或元素的样式也是如此。这也导致了更稳定的 DOM 结构，因为即使内部 dom 结构被修改，这些类名也不会更改位置。
由于参考、config 和状态 CSS 类名在其名称中不包含 xtype 信息，因此它们必须与 Component 的 classCls 或 baseCls 结合使用，以避免与其他可能具有相同 config 或状态类名的 Components 冲突。例如，要设置按钮主元素的按下状态的样式，可以使用以下选择器
.x-button.x-pressed
UI mixin 将 UI 特定 CSS 类名与参考、config 和状态 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 之类的选择器，以便仅设置其自身 body 元素的样式，而不是设置嵌套在其中的其他面板的 body 元素的样式。在某些情况下，当容器元素与其子元素之间存在数量不等的 dom 元素时，会将 UI 特定类名添加到子元素。
例如，Ext.Container 就是一个例子。它会为其 innerElement 的每个 classCls 添加一个用户界面特定的类，因为根据容器是否包含停靠项目，innerElement 和元素之间可能存在不同数量的 DOM 祖先元素。
Ext JS | 使用条款