跳到主要内容

主题定制 ​

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:源码级新增(组件库仓库内) ​

适合要把主题沉淀进组件库本身的场景:

  1. 在 packages/tokens/src/themes/ 新增 <name>.json,只需写与默认值的差异组(如只覆盖 color,或 color + radius + shadow),结构参照 mono.json / aurora.json。
  2. 运行 pnpm --filter @ruanno-ui/tokens build,重新生成 dist/themes.css。
  3. 如需把新主题加入 RN_THEMES 常量与类型,同步修改 packages/ui/src/theme.ts。
  4. 组件级的皮肤微调(仅靠变量覆盖不够时)写在 packages/ui/src/styles/skins.css,注意选择器特异性要压过组件 scoped 样式。