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