介绍

Dojo 是基于 HTML 的技术，使用 CSS 为框架中的元素和用它开发的应用程序设置样式。

Dojo 鼓励将结构样式封装在各部件中，以便最大限度复用；同时将外观主题设置到应用程序所有部件上。用户为他们的应用程序设置样式和主题时，这种模式提供了固定的套路，即使混合使用 Dojo 的 @dojo/widgets 库中的部件、由第三方提供的部件或者为特定应用程序开发的内部使用的部件时也是如此。

基本用法

注意： 以下示例是按顺序在前一个示例的基础上构建的。每个示例都尽量简短，只突出显示跟上一个示例相比发生变化的部分。

这些示例假定应用程序名为：

package.json

{
    "name": "my-app"
}

应用程序名与部件主题的 key 有关。

为单个部件设置样式

• 为每个部件单独定义一个 CSS 模块
• 在部件的 TypeScript 代码中使用相应的类型化的样式类

src/styles/MyWidget.m.css

.root {
    font-family: sans-serif;
}

src/widgets/MyWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import * as css from '../styles/MyWidget.m.css';
const factory = create();
export default factory(function MyWidget() {
    return <div classes={[css.root]}>My Widget</div>;
});

让部件支持主题

• 注入 theme 中间件
• 使用 theme.classes 返回主题化的 css 类名，这样部件的默认样式就会被主题覆盖

src/widgets/MyWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';
import * as css from '../styles/MyWidget.m.css';
const factory = create({ theme });
export default factory(function MyWidget({ middleware: { theme } }) {
    const { root } = theme.classes(css);
    return <div classes={[root]}>My Widget</div>;
});

在部件中应用主题变体

• 在部件的 root 上设置 theme.variant 样式。
• 将 css 属性应用到正确的 DOM 层级上，并且不能暴露出部件的 DOM。

src/widgets/MyWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';
import * as css from '../styles/MyWidget.m.css';
const factory = create({ theme });
export default factory(function MyWidget({ middleware: { theme } }) {
    const { root } = theme.classes(css);
    const variantRoot = theme.variant();
    return <div classes={[root, variantRoot]}>My Widget</div>;
});

创建主题

• 使用自定义的主题样式属性重写部件默认的 CSS 类
• 通过合适的部件主题 key 将一个或多个重写后的样式链接到主题结构中

src/themes/MyTheme/MyWidget.m.css

.root {
    color: hotpink;
    background-color: slategray;
}

src/themes/MyTheme/theme.ts

import * as myWidgetCss from './MyWidget.m.css';
export default {
    'my-app/MyWidget': myWidgetCss
};

创建主题的变体

• 将主题变量作为 CSS 自定义属性存放在 variant 模块中
• 通过 var() 引用自定义属性
• 不依赖于本地变量或者公共的 variables.css 文件

src/themes/variants/default.m.css

/* single root class */
:root {
    --foreground: hotpink;
    --background: slategray;
}

src/themes/MyTheme/MyWidget.m.css

.root {
    color: var(--foreground);
    background-color: var(--background);
}

src/themes/MyTheme/index.tsx

import * as defaultVariant from './variants/default.m.css';
import * as myWidgetCss from './MyWidget.m.css';
export default {
    theme: {
        'my-app/MyWidget': myWidgetCss
    },
    variants: {
        default: defaultVariant
    }
};

指定默认的应用程序主题

theme 中间件可用于设置应用程序主题。要设置“默认的”或初始化主题，则使用 theme.set 函数，同时用 theme.get 函数确定是否需要设置主题。应该在应用程序的顶级部件中设置默认主题。

src/App.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';
import myTheme from '../themes/MyTheme/theme';
const factory = create({ theme });
export default factory(function App({ middleware: { theme }}) {
    // if the theme isn't set, set the default theme
    if (!theme.get()) {
        theme.set(myTheme);
    }
    return (
        // the application's widgets
    );
});

注意： 当同时使用基于函数的部件和基于类的部件时，应该使用应用程序注册器来注册主题。当使用基于类的部件时（如 @dojo/widgets） 也是如此。详情参考基于类部件的主题。

设置主题变体

如果将主题与 variants 一起使用，则自动选用 default 变体。使用 theme.set 函数来设置不同的变体——传入的变体名必须是主题导出的 variants 的 key 值。

import { create, tsx } from '@dojo/framework/core/vdom';
import theme from '@dojo/framework/core/middleware/theme';
import myTheme from '../themes/MyTheme/theme';
const factory = create({ theme });
export default factory(function App({ middleware: { theme }}) {
    // if the theme isn't set, set the default theme
    if (!theme.get()) {
        theme.set(myTheme, 'variant-name');
    }
    return (
        // the application's widgets
    );
});

更改应用程序主题

• 使用 theme 中间件 在可用的主题间切换

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