动态配色

mdui 提供了动态配色功能。只需提供一个颜色值,mdui 就能自动生成一套完整的配色方案。此外,mdui 还支持从指定的壁纸中提取主色调,并据此生成配色方案。

你可以随时点击文档页面右上角的 图标,切换配色方案,查看各个组件在不同配色方案下的显示效果。

一套配色方案实际上是一组 CSS 自定义属性。mdui 组件中的颜色值都引用了这一组 CSS 自定义属性,因此可以一次性更新所有组件的配色方案。完整的 CSS 自定义属性列表请参见 设计令牌 - 颜色

生成配色方案

你可以使用 setColorScheme 函数来生成配色方案。该函数接受一个十六进制颜色值作为参数,生成一套配色方案,并将页面的 <html> 元素设置为该配色方案。例如:

import { setColorScheme } from 'mdui/functions/setColorScheme.js';

// 根据 #0061a4 生成一套配色方案,并将 <html> 设置为该配色方案
setColorScheme('#0061a4');

你还可以在第二个参数中指定 target 属性,用于指明在哪个元素上设置配色方案。例如:

import { setColorScheme } from 'mdui/functions/setColorScheme.js';

// 根据 #0061a4 生成一套配色方案,并将 .foo 元素设置为该配色方案
setColorScheme('#0061a4', {
  target: document.querySelector('.foo')
});

默认情况下生成的配色方案仅包含 设计令牌 - 颜色 中所列出的颜色。你可以在第二个参数中指定 customColors 属性,mdui 会根据你给出的自定义颜色名和颜色值生成一组自定义颜色组。例如:

import { setColorScheme } from 'mdui/functions/setColorScheme.js';

// 根据 #0061a4 生成一套配色方案,并修改了原有的 error 颜色组的值,并添加了一组新的 music 颜色组
setColorScheme('#0061a4', {
  customColors: [
    {
      name: 'error',
      value: '#69F0AE'
    },
    {
      name: 'music',
      value: '#FFC107'
    }
  ]
});

一组自定义颜色组包含四个 CSS 自定义属性:

  • --mdui-color-{name}
  • --mdui-color-on-{name}
  • --mdui-color-{name}-container
  • --mdui-color-on-{name}-container

其中的 {name} 为你传入的 customColors 中的 name 字段名,即自定义颜色名。

自定义颜色名可以是默认配色方案中的已有颜色名,如 primarysecondarytertiaryerror 这些都是默认配色方案中已包含的。如果你指定了这些值作为自定义颜色名,则生成的配色方案中对应的四个 CSS 自定义属性,将用你指定的颜色值来生成。例如上面示例中指定了名为 error 的自定义颜色名,因为 error 是默认配色方案中已有的颜色名,且其对应的 CSS 自定义属性被 mdui 组件用于表示错误状态,因为现在颜色值被设置为一个绿色的值,所以 mdui 组件中的错误状态也将变为绿色。

自定义颜色名也可以是新增的,例如上面示例中的 music,是默认配色方案中不存在的,则生成的配色方案将额外包含四个 CSS 自定义属性。可以在你自己的样式中引用这些 CSS 自定义属性:

<style>
  .music {
    background-color: rgb(var(--mdui-color-music));
    color: rgb(var(--mdui-color-on-music));
  }

  .music-container {
    background-color: rgb(var(--mdui-color-music-container));
    color: rgb(var(--mdui-color-on-music-container));
  }
</style>

<div class="music">Music</div>
<div class="music-container">Music Container</div>

你还可以使用 removeColorScheme 函数来移除通过上述方法生成的配色方案。你可以传入参数来指定移除哪个元素上的配色方案,默认情况下,它会移除 <html> 上的配色方案。

从壁纸中提取颜色

mdui 提供了 getColorFromImage 函数,用于从一个给定的 Image 实例中提取主色调。该函数返回一个 Promise,resolve 的值即为提取的十六进制颜色值。

你可以使用从该函数获得的颜色值,然后调用上述文档中介绍的 setColorScheme 函数来设置配色方案。例如:

import { getColorFromImage } from 'mdui/functions/getColorFromImage.js';
import { setColorScheme } from 'mdui/functions/setColorScheme.js';

const image = new Image();
image.src = 'image1.png';

getColorFromImage(image).then(color => setColorScheme(color));
MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
Button 按钮ButtonIcon 图标按钮Fab 浮动操作按钮SegmentedButton 分段按钮Chip 纸片Card 卡片Checkbox 复选框Radio 单选框Switch 开关切换Slider 滑块RangeSlider 范围滑块List 列表Collapse 折叠面板Tabs 选项卡Dropdown 下拉组件Menu 菜单Select 选择框TextField 文本框LinearProgress 线性进度指示器CircularProgress 圆形进度指示器Dialog 对话框Divider 分割线Avatar 头像Badge 徽标Icon 图标Tooltip 工具提示Snackbar 消息条NavigationBar 底部导航栏NavigationDrawer 侧边抽屉栏NavigationRail 侧边导航栏BottomAppBar 底部应用栏TopAppBar 顶部应用栏Layout 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库