Dojo 应用程序支持主题

theme.classes 方法

theme.classes 将部件的 CSS 类名转换应用程序或部件的主题类名。

theme.classes<T extends ClassNames>(css: T): T;

• 注意事项 1： 主题的重写只在 CSS 类一级，而不是 CSS 类中的单个样式属性。
• 注意事项 2： 如果当前激活的主题没有重写给定的样式类，则部件会退而使用该类的默认样式属性。
• 注意事项 3： 如果当前激活的主题的确重写了给定的样式类，则 只会 将主题中指定的 CSS 属性应用到部件上。例如，如果部件的默认样式类包含 10 个 CSS 属性，但是当前的主题只指定了一个，则部件渲染时只会使用这一个 CSS 属性，并丢掉在主题中未重写的其他 9 个属性。

theme 中间件属性

• theme （可选）
  • 如果指定，则所提供的主题会重写部件使用的任何主题，并且优先于应用程序的默认主题，以及应用程序中切换的任何其他主题。
• classes （可选）
  • 在为部件传入外部样式类一节有详细描述。
• variant （可选）
  • 从当前的主题变体中返回 root 类。
  • 应该应用到部件的根节点上。

可主题化部件示例

下面是一个可主题化部件的 CSS 模块文件：

src/styles/MyThemeableWidget.m.css

/* requirement 4, i.e. this widget is intended for wider distribution,
therefore its outer-most VDOM element uses the 'root' class: */
.root {
	font-family: sans-serif;
}

/* widgets can use any variety of ancillary CSS classes that are also themeable */
.myWidgetExtraThemeableClass {
	font-variant: small-caps;
}

/* extra 'fixed' classes can also be used to specify a widget's structural styling, which is not intended to be
overridden via a theme */
.myWidgetStructuralClass {
	font-style: italic;
}

在相应的可主题化的部件中使用这些样式：

src/widgets/MyThemeableWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';

import * as css from '../styles/MyThemeableWidget.m.css';

/* requirement 1: */
const factory = create({ theme });

export default factory(function MyThemeableWidget({ middleware: { theme } }) {
	/* requirement 2 */
	const { root, myWidgetExtraThemeableClass } = theme.classes(css);
	return (
		<div
			classes={[
				/* requirement 3: */
				root,
				myWidgetExtraThemeableClass,
				css.myWidgetExtraThemeableClass,
				theme.variant()
			]}
		>
			Hello from a themed Dojo widget!
		</div>
	);
});

.commonBase {
	border: 4px solid black;
	border-radius: 4em;
	padding: 2em;
}

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';

import * as css from '../styles/MyThemeableWidget.m.css';
import * as commonCss from '../styles/MyThemeCommonStyles.m.css';

const factory = create({ theme });

export default factory(function MyThemeableWidget({ middleware: { theme } }) {
	const { root } = theme.classes(css);
	const { commonBase } = theme.classes(commonCss);
	return (
		<div classes={[root, commonBase, css.myWidgetExtraThemeableClass, theme.variant()]}>
			Hello from a themed Dojo widget!
		</div>
	);
});

重写部件实例的主题

部件的使用者可以将一个有效的主题传给部件实例的 theme 属性，来重写特定部件实例的主题。当需要在应用程序的不同部分以多种方式显示给定的部件时，这个功能就能派上用场。

例如，在可主题化部件示例的基础上构建：

src/themes/myTheme/styles/MyThemeableWidget.m.css

.root {
	color: blue;
}

src/themes/myThemeOverride/theme.ts

import * as myThemeableWidgetCss from './styles/MyThemeableWidget.m.css';

export default {
	'my-app/MyThemeableWidget': myThemeableWidgetCss
};

src/widgets/MyApp.tsx

import { create, tsx } from '@dojo/framework/core/vdom';

import MyThemeableWidget from './src/widgets/MyThemeableWidget.tsx';
import * as myThemeOverride from '../themes/myThemeOverride/theme.ts';

const factory = create();

export default factory(function MyApp() {
	return (
		<div>
			<MyThemeableWidget />
			<MyThemeableWidget theme={myThemeOverride} />
		</div>
	);
});

此处，渲染了两个 MyThemeableWidget 实例，如果指定了应用程序范围的主题，则第一个部件会使用此主题，否则使用部件的默认样式。相比之下，第二个部件始终使用 myThemeOverride 中定义的主题。

为部件传入额外的样式

主题机制提供了一种简便的方式，为应用程序中的每个部件统一应用自定义样式，但当用户希望为给定的部件实例应用额外的样式时，在这种场景下主题机制就不够灵活。

可以通过可主题化部件的 classes 属性来传入额外的样式类。这些样式类是追加的，不会重写部件已有的样式类，它们的目的是对已经存在的样式进行细粒度的调整。提供的每一组额外的样式类都需要按照两个级别的 key 进行分组：

1. 合适的部件主题 key，用于指定应用样式类的部件，包括其中的任何子部件。
2. 小部件使用的某个已存在的 CSS 类，部件使用者可以在单个 DOM 元素上扩展样式，一个部件上可扩展多个样式。

例如，额外的样式类属性的类型定义为：

type ExtraClassName = string | null | undefined | boolean;

interface Classes {
	[widgetThemeKey: string]: {
		[baseClassName: string]: ExtraClassName[];
	};
}

作为一个提供额外样式类的示例，下面调整 Dojo combobox 实例，以及其中的子部件 text input。此操作会将 combobox 使用的 text input 控件的背景色以及其自身面板的背景色改为蓝色。combobox 控件面板中的下拉箭头也会变为红色：

src/styles/MyComboBoxStyleTweaks.m.css

.blueBackground {
	background-color: blue;
}

.redArrow {
	color: red;
}

src/widgets/MyWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';

import ComboBox from '@dojo/widgets/combobox';
import * as myComboBoxStyleTweaks from '../styles/MyComboBoxStyleTweaks.m.css';

const myExtraClasses = {
	'@dojo/widgets/combobox': {
		controls: [myComboBoxStyleTweaks.blueBackground],
		trigger: [myComboBoxStyleTweaks.redArrow]
	},
	'@dojo/widgets/text-input': {
		input: [myComboBoxStyleTweaks.blueBackground]
	}
};

const factory = create();

export default factory(function MyWidget() {
	return (
		<div>
			Hello from a tweaked Dojo combobox!
			<ComboBox classes={myExtraClasses} results={['foo', 'bar']} />
		</div>
	);
});

注意，部件的作者负责显式地将 classes 属性传给所有的要使用样式类的子部件，因为 Dojo 本身无法将这个属性注入给或自动传给子部件。

更改当前激活的主题

theme 中间件中的 .set(theme) 函数用于在整个应用程序级别更改当前激活的主题。为 .set 传入所需的主题，这将让应用程序树中所有可主题化的部件失效，并使用新的主题重新渲染。

src/widgets/ThemeSwitcher.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';

import myTheme from '../themes/MyTheme/theme';
import alternativeTheme from '../themes/MyAlternativeTheme/theme';

const factory = create({ theme });

export default factory(function ThemeSwitcher({ middleware: { theme } }) {
	return (
		<div>
			<button
				onclick={() => {
					theme.set(myTheme);
				}}
			>
				Use Default Theme
			</button>
			<button
				onclick={() => {
					theme.set(alternativeTheme);
				}}
			>
				Use Alternative Theme
			</button>
		</div>
	);
});