主题定制
ruanno-ui 的组件样式全部消费 --rn-* CSS 变量,主题切换本质是整体替换这组变量的取值。主题通过在 <html> 上挂载 data-rn-theme 属性生效,无需重新加载样式。
内置主题
| 主题名 | 定位 |
|---|---|
classic | 经典蓝,默认通用主题(不挂属性时的缺省值) |
mono | 墨·浅:工程感黑白灰,紫罗兰点缀 |
mono-dark | 墨·深:mono 的暗色面 |
aurora | 曜·浅:消费级风格,渐变配色、大圆角、柔和阴影 |
aurora-dark | 曜·深:aurora 的暗色面 |
使用
ts
import { setRnTheme, getRnTheme, RN_THEMES } from "ruanno-ui";
setRnTheme("mono"); // 切换到 mono
getRnTheme(); // 读取当前主题名,默认 "classic"
RN_THEMES; // ["classic", "mono", "mono-dark", "aurora", "aurora-dark"]setRnTheme("classic") 会移除 data-rn-theme 属性,回到默认主题。
也可以不用 JS,直接在 HTML 上声明:
html
<html data-rn-theme="mono">
...
</html>自定义主题
方法 A:CSS 覆盖(业务项目内)
写一段以 [data-rn-theme="..."] 为选择器的 CSS,只覆盖需要改的变量,然后调用 setRnTheme 即可:
css
/* 你的全局样式文件,需在 ruanno-ui/style.css 之后引入 */
[data-rn-theme="mine"] {
--rn-color-primary: #7c3aed;
--rn-color-primary-hover: #8b5cf6;
--rn-color-primary-active: #6d28d9;
--rn-color-primary-soft: #f3efff;
--rn-radius-md: 12px;
}ts
import { setRnTheme } from "ruanno-ui";
setRnTheme("mine");最常用的可覆盖变量(完整清单见 packages/tokens/src/tokens.json):
- 颜色(19 个):
--rn-color-primary/-primary-hover/-primary-active/-primary-soft、-success、-warning、-danger/-danger-hover/-danger-soft、-info、-text/-text-secondary/-text-placeholder/-text-inverse、-bg/-bg-soft/-bg-mask、-border/-border-strong - 圆角:
--rn-radius-none/-sm/-md/-lg/-full - 阴影:
--rn-shadow-sm/-md/-lg
未覆盖的变量会回落到 :root 上的 classic 默认值,所以暗色主题务必至少覆盖 bg / text / border 系列。
方法 B:源码级新增(组件库仓库内)
适合要把主题沉淀进组件库本身的场景:
- 在
packages/tokens/src/themes/新增<name>.json,只需写与默认值的差异组(如只覆盖color,或color+radius+shadow),结构参照mono.json/aurora.json。 - 运行
pnpm --filter @ruanno-ui/tokens build,重新生成dist/themes.css。 - 如需把新主题加入
RN_THEMES常量与类型,同步修改packages/ui/src/theme.ts。 - 组件级的皮肤微调(仅靠变量覆盖不够时)写在
packages/ui/src/styles/skins.css,注意选择器特异性要压过组件 scoped 样式。