指南

主题定制

One UI 始终包含不可覆盖的内置 default 主题。oneTheme.init() 可以注册多套全局主题，每套自定义主题都会按 colors、typography、border 和 radius 分组，从内置 default 深度继承未填写的字段。

初始化多套主题

import { OneButton, oneTheme } from '@geektech/one';

oneTheme.init({
  defaultTheme: 'brand',
  themes: {
    brand: {
      colors: { primary: '#326bff', primaryHover: '#2457dc' },
      typography: { fontFamily: 'Inter, sans-serif', lineHeight: '1.6' },
      border: { color: '#cbd5e1', width: '1px', style: 'solid' },
      radius: { sm: '4px', md: '8px', lg: '12px' },
    },
    night: {
      colors: { surface: '#101510', text: '#f4f8f4', muted: '#a8b3aa' },
    },
  },
});

const defaultButton = new OneButton({ children: ['默认主题'] });
const nightButton = new OneButton({ children: ['夜间主题'] });
defaultButton.on('click', () => oneTheme.switch('default'));
nightButton.on('click', () => oneTheme.switch('night'));
console.log(oneTheme.currentTheme);

初始化会立即应用 defaultTheme；再次调用 init() 会替换此前注册的自定义主题。oneTheme.switch() 只接受已注册名称，并在成功写入全部变量后更新 currentTheme。

作用域、错误与持久化

主题服务只作用于全局 document.documentElement，不提供局部主题容器。配置字段、名称或 CSS 值无效时抛出 OneThemeConfigError；切换到未知名称时抛出 OneThemeNotFoundError；没有浏览器根节点时抛出 OneThemeEnvironmentError。失败操作不会改变当前主题。

读取 CSS 回退值

原有的扁平 ONE_THEME_DEFAULTS 仍用于读取组件 CSS 的默认回退值；嵌套的 ONE_DEFAULT_THEME 则描述完整内置主题。

import { ONE_THEME_DEFAULTS } from '@geektech/one';

const primaryColor = ONE_THEME_DEFAULTS.colorPrimary;
const cardRadius = ONE_THEME_DEFAULTS.radiusMd;

主题 token

全局 CSS 变量覆盖

:root {
  --one-color-primary: #326bff;
  --one-radius-md: 12px;
}

局部 CSS 变量覆盖

这只是现有 CSS 变量覆盖能力，不会创建可由 oneTheme 管理或切换的局部主题。

.checkout-panel {
  --one-color-primary: #7c3aed;
  --one-shadow-card: none;
}