Modern Toolkit 中的主题
许多类在使用配置对象创建（实例化）类时都有使用的快捷名称。快捷名称称为别名（如果类扩展 Ext.Component，则称为xtype）。对于适用的类，别名/xtype 会列在类名称旁边以供快速参考。
框架类或其成员可以指定为私有或受保护。否则，类/成员为公共。公共、受保护和私有是访问描述符，用于传达如何以及何时使用类或类成员。
公共类和类成员可供任何其他类或应用程序代码使用，并且可以依赖它们在主要产品版本中保持稳定和持久。公共类和成员可以通过子类安全地进行扩展。
受保护类成员是稳定的公共成员，旨在供拥有类或其子类使用。受保护的成员可以通过子类安全地进行扩展。
私有类和类成员由框架内部使用，不打算供应用程序开发人员使用。私有类和成员可以在任何时候在不发出通知的情况下更改或从框架中省略，并且不应在应用程序逻辑中依赖它们。
静态标签。*请参见下文的静态。下面是一个示例类成员，我们可以对其进行剖析以显示类成员的语法（在本例中，从 Ext.button.Button 类中查看的 lookupComponent 方法）。
让我们看看成员行的每一部分
lookupComponent）( item )）Ext.Component）。对于不返回 undefined 以外任何内容的方法，可以省略此项，或者可能显示多个可能的值，用正斜杠 / 分隔，表示返回的内容可能取决于方法调用的结果（即，如果 get 方法调用成功，则方法可能返回一个组件，如果失败则返回 false，将显示为 Ext.Component/Boolean）。PROTECTED - 请参见下面的标志部分）Ext.container.Container）。如果成员来自当前类，则源类将显示为蓝色链接；如果成员是从祖先或混合类继承的，则显示为灰色。查看源）item : Object）进行列出。undefined 以外的值，则“返回”部分将注明返回的类或对象类型以及描述（示例中的 Ext.Component）自 3.4.0 起可用 - 示例中未显示），紧跟在成员描述之后默认为：false）API 文档使用许多标志来进一步传达类成员的功能和意图。标签可以用文本标签、缩写或图标表示。
classInstance.method1().method2().etc();false，则标记为可阻止的事件将不会触发- 表示框架类
- 单例框架类。*有关更多信息，请参见单例标志
- 组件类型框架类（Ext JS 框架中任何扩展 Ext.Component 的类）
- 表示当前查看版本中新增的类、成员或指南
- 表示类型为 config 的类成员
- 表示类型为 property 的类成员
- 表示类型为 method 的类成员
- 表示类型为 event 的类成员
- 表示类型为 theme variable 的类成员
- 表示类型为 theme mixin 的类成员
- 表示当前查看版本中新增的类、成员或指南
在 API 文档页面上类名称正下方是一行按钮，对应于当前类拥有的成员类型。每个按钮显示按类型划分的成员数（应用筛选器后会更新此计数）。单击按钮将导航到该成员部分。将鼠标悬停在成员类型按钮上将显示一个弹出菜单，其中包含该类型的所有成员，以便快速导航。
与类配置选项相关的 Getter 和 Setter 方法将显示在方法部分以及 API 文档和成员类型菜单的配置部分中，位于它们所处理的配置正下方。Getter 和 Setter 方法文档将位于配置行中，以便于参考。
您的页面历史记录保存在本地存储中，并显示在顶部标题栏正下方（使用可用空间）。默认情况下，仅显示与您当前正在查看的产品/版本匹配的搜索结果。您可以通过单击历史记录栏右侧的 按钮并选择“全部”单选选项来扩展显示内容。这将在历史记录栏中显示所有产品/版本的所有近期页面。
在历史记录配置菜单中，您还将看到最近访问的页面列表。结果按“当前产品/版本”和“全部”单选选项进行筛选。单击 按钮将清除历史记录栏以及保存在本地存储中的历史记录。
如果在历史记录配置菜单中选择了“全部”，则将启用“在历史记录栏中显示产品详细信息”复选框选项。选中后，每个历史页面的产品/版本将与历史记录栏中的页面名称一起显示。将光标悬停在历史记录栏中的页面名称上也将以工具提示的形式显示产品/版本。
可以使用页面顶部的搜索字段搜索 API 文档和指南。
在 API 文档页面上，还有一个筛选器输入字段，用于使用筛选器字符串筛选成员行。除了按字符串筛选外，您还可以按访问级别、继承和只读筛选类成员。这是使用页面顶部的复选框完成的。
API 类导航树底部的复选框筛选类列表，以包括或排除私有类。
单击空搜索字段将显示您最近的 10 次搜索，以便快速导航。
每个 API 文档页面（Javascript 原语页面除外）都有一个与该类相关的元数据菜单视图。此元数据视图将具有以下一个或多个
Ext.button.Button 类具有备用类名称 Ext.Button）。备用类名称通常用于向后兼容。可运行的示例（小提琴）在页面上默认展开。您可以使用代码块左上角的箭头单独折叠和展开示例代码块。您还可以使用页面右上角的切换按钮切换所有示例的折叠状态。切换所有状态将在页面加载之间记住。
类成员在页面上默认折叠。您可以使用成员行左侧的箭头图标或使用右上角的展开/折叠全部切换按钮展开和折叠成员。
在较窄的屏幕或浏览器上查看文档将导致针对较小尺寸进行优化的视图。桌面视图和“移动”视图之间的主要区别是
可以通过单击 API 文档页面顶部的类名来查看类源。可以通过单击成员行右侧的“查看源”链接来查看类成员的源。
在本指南中，我们将逐步了解 Ext JS 6.2 中 Modern Toolkit 引入的主题更改。有很多令人兴奋的新变化，可以更轻松地进行主题设置、动态更新等等。随着这些更新，还有一些你应该了解的新概念。
让我们讨论一下 Modern Toolkit 中主题设置的约定和最佳实践。
所有变量都使用 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 属性示例
与组件的核心功能或布局无关的可配置样式使用变量进行控制。这些变量在与组件的类名相匹配的scss文件中定义，该文件位于theme-neptune/sass/var目录中。使用这些变量的规则包含在同一文件中的 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);
组件具有用于 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并向页面上的<html>元素添加 CSS 类名x-big，来选择是否使用大模式。例如，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 混合，用于生成该组件的多个视觉效果。这些混合称为[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，它通过将背景色更改为 red 来构建默认 UI，但通过级联继承默认 UI 的所有其他属性。此 UI 调用的输出是最小的。它仅包含设置背景色所需的规则，没有其他内容。
@include button-ui(
$ui: 'action',
$background-color: red
);
具有 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 被包装在它们自己的混合中，派生主题可以覆盖这些混合以更改参数
@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
// 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。可组合 UI 通常努力将其关注领域限制在样式的各个方面（颜色、大小、边框半径等），以便在组合它们时几乎没有歧义。
使用可组合 UI 可确保生成的 CSS 代码保持非常 DRY，避免不必要的 CSS 规则重复。在上面的示例中，我们避免了对可能需要圆度的每个 UI 的背景色规则进行重复。任何 UI 都可以与“圆形”UI 组合以添加圆度。
保持 CSS 类名的命名一致性非常重要，因为它们在向框架中的组件生成的 DOM 元素添加语义和结构方面发挥着主要作用。这种命名的一致性有两个目的
组件在其主元素上具有 x-[xtype] 的类名。例如，文本字段组件将具有 x-textfield 的 CSS 类名。
组件有两种可能的方式来设置此主 CSS 类。它们可以在其类定义的主体上设置 classCls 或 baseCls，但首选 classCls。设置其中任何一个都会将 CSS 类添加到主元素，并将其用作也添加到主元素的 UI 特定类名的前缀。classCls 和 baseCls 配置仅在其可继承性上有所不同。classCls 由子类继承，并且是这些子类的 classCls 的附加内容，而 baseCls 则不是。
此外，在使用 classCls 时，将为类层次结构中的每个 classCls 添加一个 UI 特定的 CSS 类名。例如，一个将“ui”设置为 foo 的 Ext.field.Password 组件将具有以下 UI 类
此模式确保通过类层次结构正确继承样式，并允许组件仅为它们添加的功能提供样式。对于不希望继承样式的边缘情况，组件可以设置 classClsRoot:true 以防止从祖先继承 classCls。
参考元素遵循模式 x-[referencePrefix]-el。例如，表单字段的 bodyElement 参考元素将具有 CSS 类 x-body-el。为了保持一致性，元素引用将在 JavaScript 侧具有 Element 后缀。CSS 类名上的 -el 后缀有助于将参考元素与具有相同名称的 xtype 的潜在组件区分开来。
反映组件配置的 CSS 类名遵循模式 x-[configName]-[configValue]，并放置在组件的主元素上。例如，具有 labelAlign: 'left' 配置的表单字段在主元素上添加了 CSS 类名 x-label-align-left。
布尔配置的 CSS 类名通常遵循以下两种模式之一
真值会导致添加一个新类。例如，当值为 true 时，具有选中配置的复选框将具有 x-checked CSS 类，但当值为 false 时不会具有该类。
假值会导致添加一个新类。当默认值为 true 且组件仅在 falsey 状态下需要其他样式时，这有时很有用。例如，当 rowLines 配置为 false 时，List 组件具有 x-no-row-lines CSS 类。
同样，反映组件状态的类名遵循模式 x-[state]，并放置在组件的主元素上。
例如，处于按下状态的按钮将在其主元素上具有类 x-pressed。
在主元素上设置组件状态和配置 CSS 类，而不是在参考元素上设置，允许状态或配置作用于组件。即使类仅影响子元素或元素的样式，也是如此。这也导致更稳定的 DOM 结构，因为即使修改了内部 dom 结构，这些类名也不会改变位置。
由于引用、配置和状态 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 的选择器，以便仅设置其自身的 body 元素的样式，而不设置嵌套在其中的其他面板的 body 元素的样式。在某些情况下，当容器元素与其子元素之间存在数量不定的 dom 元素时，将向子元素添加 UI 特定的类名。
此示例为 Ext.Container。它为其 innerElement 添加了每个 classCls 的 UI 特定类，因为 innerElement 和元素之间可能存在数量不定的 DOM 祖先，具体取决于容器是否有停靠项。
Ext JS | 使用条款