主题定制
组件的颜色、圆角、间距、字号、阴影都来自 CSS 变量(--ns- 开头),定义在 @ns/theme 里。定制主题就是改这些变量的值,不需要重新编译组件库。
暗色主题
在 <html> 上加 data-theme="dark" 就切到暗色,去掉或改成 light 就回到亮色:
// 切到暗色
document.documentElement.setAttribute('data-theme', 'dark')
// 切回亮色
document.documentElement.setAttribute('data-theme', 'light')
也可以给 <html> 加 class="dark",效果一样。
三种情况的优先顺序:
- 写了
data-theme="dark"(或class="dark"):暗色; - 写了
data-theme="light":亮色,即使系统是深色模式; - 都没写:跟随系统的深色模式设置(
prefers-color-scheme)。
所以如果项目不打算支持暗色,要在 <html> 上明确写 data-theme="light",否则用户的系统是深色模式时页面会自动变暗。
NsConfigProvider 的 theme 等同于在 <html> 上写 data-theme,作用于整个页面;不传 theme 时它不修改页面主题。
data-theme 也可以写在页面里的某个容器上,只让这一块用暗色:
<div data-theme="dark">
<!-- 这里面的组件是暗色 -->
</div>
弹出层(Select 的下拉、Tooltip、Modal 等)会挂到 body 下,不在这个容器里,所以不受局部容器的 data-theme 影响,仍然跟随根元素的主题。
配色方案
内置 6 套配色,在 <html>(或某个容器)上加 data-palette 切换,可以和暗色主题叠加。官网顶栏右侧的调色板按钮可以直接切换,看各个组件在每套配色下的效果。
data-palette | 风格 | 主色 |
|---|---|---|
| 不写 | 默认 | #1890ff |
classic | 经典商务 | #409eff |
cyberpunk | 科技感 | #0094b8 |
luxury | 沉稳金色 | #b8860b |
nature | 清新绿色 | #10b981 |
minimal | 极简靛蓝 | #6366f1 |
jade | 翡翠绿 | #18a058 |
jade 以绿色为主,成功色和主色相同;暗色下主色是薄荷绿 #63e2b7。实底按钮上的文字固定是白色,暗色下在这种浅亮的主色上不够清楚,nature、cyberpunk 的暗色也有同样的问题。
document.documentElement.setAttribute('data-palette', 'nature')
// 恢复默认配色
document.documentElement.removeAttribute('data-palette')
自定义变量
在自己的样式里覆盖变量即可,放在 @ns/ui/style.css 之后引入:
:root {
--ns-color-primary: #7c3aed;
--ns-color-primary-light: #8b5cf6; /* 悬停 */
--ns-color-primary-dark: #6d28d9; /* 按下 */
--ns-color-primary-bg: #f5f3ff; /* 亮色下的浅底色 */
--ns-border-radius: 4px;
}
/* 暗色下的浅底色:三种开启暗色的方式都要覆盖到 */
:root.dark,
[data-theme='dark'] {
--ns-color-primary-bg: rgba(124, 58, 237, 0.2);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
--ns-color-primary-bg: rgba(124, 58, 237, 0.2);
}
}
:root 上设的 -bg 和暗色主题的选择器优先级相同,又写在后面,切到暗色时仍然生效,亮色的浅底色放在深色背景上会很刺眼,所以要像上面这样给暗色再设一次。暗色下没有单独设置的 -bg、-bg-hover 会按当前的功能色自动算出(功能色加 20%、30% 的不透明度),只改了功能色、没改 -bg 时不用写后面两段。
只想改某个页面或某个区域,把选择器换成对应的容器,并给容器加上 ns-theme-scope 类:
<div class="report-page ns-theme-scope">…</div>
.report-page {
--ns-color-primary: #0f766e;
--ns-color-primary-light: #3f918b;
--ns-color-primary-dark: #0c5e58;
--ns-color-primary-bg: #e7f1f0;
}
浅色阶(--ns-color-primary-light-3 … -light-9)是在声明它的元素上按当时的主色算好的,子元素继承的是算好的结果。容器带上 ns-theme-scope 类,浅色阶才会在容器上按新主色重新计算;-light、-dark、-bg 这几个固定值的变体要像上面这样自己写。
暗色下要单独设置时,选择器要覆盖三种开启方式::root.dark、[data-theme='dark'],以及 @media (prefers-color-scheme: dark) 里的 :root:not([data-theme='light']),写法见上面第一个例子。
变量一览
下面是常用变量。完整定义见 packages/theme/src/variables.scss,暗色的取值见 dark.scss。
功能色
每种功能色都有同一套后缀。primary 可以换成 success、warning、danger、info、help。
| 变量 | 用途 |
|---|---|
--ns-color-primary | 主色 |
--ns-color-primary-light、-lighter | 比主色浅一档、两档,常用于悬停 |
--ns-color-primary-dark、-darker | 比主色深一档、两档,常用于按下 |
--ns-color-primary-bg、-bg-hover | 浅底色及其悬停色,用于提示框、标签的底色 |
--ns-color-primary-light-3、-5、-7、-8、-9 | 浅色阶,数字越大越浅。由主色和背景色混合得到,改了主色、换配色、切暗色都会自动跟着变 |
另有 --ns-color-white、--ns-color-black、--ns-color-transparent。
文字、背景、边框
| 变量 | 用途 |
|---|---|
--ns-text-color | 正文 |
--ns-text-color-secondary | 次要文字 |
--ns-text-color-tertiary | 辅助说明 |
--ns-text-color-disabled | 禁用文字 |
--ns-text-color-placeholder | 占位文字 |
--ns-bg-color | 组件和页面的底色 |
--ns-bg-color-secondary、-tertiary | 比底色深一档、两档的背景,用于表头、斑马纹等 |
--ns-bg-color-page | 页面底色(内容区外面那一层) |
--ns-bg-color-hover、-active | 悬停、按下时叠加的半透明背景 |
--ns-bg-color-disabled | 禁用背景 |
--ns-fill-color、-light、-dark | 填充色:滑块和进度条的轨道、骨架屏等 |
--ns-mask-color | 弹窗、抽屉的遮罩 |
--ns-border-color | 边框 |
--ns-border-color-light、-lighter | 较浅的边框、分割线 |
--ns-border-color-hover | 输入类组件悬停时的边框 |
圆角、间距、尺寸
| 变量 | 取值 |
|---|---|
--ns-border-radius-sm / --ns-border-radius / -lg / -xl | 2px / 6px / 8px / 12px |
--ns-border-radius-round / -circle | 9999px / 50% |
--ns-spacing-1 … --ns-spacing-12 | 4px 起,每档加 4px(--ns-spacing-4 是 16px) |
--ns-size-xs / -sm / -md / -lg / -xl | 24px / 32px / 40px / 48px / 56px |
--ns-component-size-large / --ns-component-size / --ns-component-size-small | 40px / 32px / 24px(控件高度,含边框) |
字体
| 变量 | 取值 |
|---|---|
--ns-font-family、--ns-font-family-mono | 正文字体、等宽字体 |
--ns-font-size-xs / -sm / -base / -lg / -xl | 12px / 14px / 14px / 16px / 20px |
--ns-font-size-2xl … -5xl | 24px / 30px / 38px / 48px |
--ns-line-height-tight / -normal / -relaxed / -loose | 1.25 / 1.5 / 1.75 / 2 |
--ns-font-weight-normal / -medium / -semibold / -bold | 400 / 500 / 600 / 700 |
阴影、过渡
| 变量 | 用途 |
|---|---|
--ns-shadow-sm、--ns-shadow、-md、-lg、-xl、-2xl | 由浅到深的阴影 |
--ns-transition-duration-fast / -normal / -slow | 150ms / 200ms / 300ms |
--ns-transition-timing-function | 过渡曲线 |
组件弹层(对话框、抽屉、下拉、提示等)的层级不由 CSS 变量控制,从 2000 起,写在各弹层的内联样式里。主题里的 --ns-z-index-*(1000~1080)只给 ns-z-dropdown、ns-z-modal 这类工具类用,改它们不会影响组件弹层。
工具类
主题里带了一批 ns- 开头的工具类,可以直接写在业务页面的元素上:
| 类别 | 例子 |
|---|---|
| 文字 | ns-text-left、ns-text-center、ns-text-primary、ns-text-secondary、ns-ellipsis、ns-ellipsis-2 |
| 背景 | ns-bg-primary、ns-bg-primary-light、ns-bg-secondary |
| 布局 | ns-flex、ns-flex-col、ns-items-center、ns-justify-between、ns-gap-2 |
| 圆角、阴影、边框 | ns-rounded、ns-rounded-lg、ns-shadow、ns-shadow-md、ns-border |
| 其他 | ns-hidden、ns-cursor-pointer、ns-overflow-auto、ns-w-full |
完整列表见 packages/theme/src/base.scss。
在组件库的 SCSS 之外使用 mixin
@ns/theme 还提供了一组 SCSS mixin(断点、文本截断、滚动条、弹性布局等),业务项目用 SCSS 时可以引入:
@use '@ns/theme/scss/mixins.scss' as ns;
.title {
@include ns.text-ellipsis(2);
}
.sidebar {
// 断点名:sm 640px、md 768px、lg 1024px、xl 1280px、2xl 1536px
@include ns.breakpoint-down('md') {
display: none;
}
}
注意只引 mixins,不要在组件的样式里 @use '@ns/theme' 整个主题,那样会把全部变量和重置样式再输出一份。