xtf-linkui

Appearance

主题系统 ​

xtf-linkui 采用 CSS 变量主题系统，通过 themeManager 统一管理，支持内置主题切换、运行时自定义、局部覆盖三种使用方式。

实现文件：uni_modules/xtf-linkui/libs/theme/、uni_modules/xtf-linkui/theme/

一、内置主题 ​

组件库内置 4 套主题（定义在 libs/theme/themes.js）：

主题标识说明
浅色light默认主题，明亮清晰（紫罗兰主色 #6366f1）
暗色dark暗黑模式，夜间舒适（深蓝底色）
新拟态neo软拟物风格，柔和凹凸阴影
中国红china-red品牌红色主题（主色 #e60012）

说明：theme/ 目录下另有 glass.scss 提供毛玻璃相关的静态样式兜底，如需毛玻璃主题可基于 light 叠加 --xtf-color-glass 等变量实现。

二、三层 Token 体系 ​

主题配置由三层 token 组成，最终扁平化为 --xtf-* CSS 变量：

1. 基础 token（全局几何与动效） ​

分组CSS 变量前缀包含内容
spacing--xtf-space-*间距：xs / sm / md / lg / xl / page
radius--xtf-radius-*圆角：sm / md / lg / xl / full / squircle
shadow--xtf-shadow-*阴影：soft / card / glass / neo / inset
typography--xtf-font-*字体族、字号、行高、字重
motion--xtf-motion-*动画时长、缓动、缩放

2. 语义色 colors ​

控制整个系统的视觉角色：

  • 主色：primary / primarySoft
  • 状态色：success / warning / danger / info
  • 背景层级：background / surface / surfaceMuted / surfaceElevated
  • 文字层级：text / textHeading / textSecondary / textCaption / textLabel / textLink / textInverse / textDisabled
  • 边框/遮罩：border / overlay / mask / glass

映射规则：colors.primary → --xtf-color-primary。

3. 组件 token componentTokens ​

精细控制高视觉权重组件的视觉变量。支持的组件分组包括：

button / input / card / text / avatar / badge / navbar / tabs / divider / popup / dialog / toast / table / timeline / countdown / upload / image / actionSheet / watermark / checkbox / grid / signature / backTop / tag / list / loading / drawer / empty / swiper / steps / picker / calendar 等。

映射规则：componentTokens.card.bg → --xtf-card-bg。

三、主题管理器 themeManager ​

themeManager 是主题系统的核心，导出自 @/uni_modules/xtf-linkui。

常用方法 ​

方法说明
initTheme(options)初始化主题，优先读取本地缓存，options 可指定 theme / overrides
setTheme(name, overrides)切换主题，overrides 为覆盖对象（会持久化）
resetTheme()恢复默认主题
getThemeName()获取当前主题名
getTheme()获取完整主题配置
getThemeVars()获取当前扁平化的 CSS 变量
registerTheme(name, themeConfig)注册自定义主题（基于 light 合并）
hasTheme(name)判断主题是否已注册
subscribe(listener)订阅主题变化

初始化（推荐在 App.vue） ​

js
import { themeManager } from '@/uni_modules/xtf-linkui'

export default {
  onLaunch() {
    themeManager.initTheme()
  }
}

全局切换主题 ​

js
import { themeManager } from '@/uni_modules/xtf-linkui'

themeManager.setTheme('dark')
themeManager.setTheme('china-red', {
  colors: { primary: '#b4000f' }
})

四、使用主题的方式对比 ​

方式作用范围持久化适用场景
themeManager.setTheme全局✅全局换肤、跟随系统
xtf-config-provider theme局部子树❌页面/区域独立主题
xtf-config-provider theme-vars局部子树❌局部覆盖若干变量
registerTheme + setTheme全局✅注册品牌主题

局部覆盖示例 ​

通过 xtf-config-provider 的 theme 与 theme-vars 实现局部视觉定制，不影响全局：

vue
<template>
  <xtf-config-provider
    theme="light"
    :theme-vars="{
      colors: { primary: '#0f766e', primarySoft: 'rgba(15, 118, 110, 0.14)' },
      componentTokens: { card: { bg: 'rgba(255, 255, 255, 0.9)' } }
    }"
  >
    <view>这里使用局部覆盖后的主题</view>
  </xtf-config-provider>
</template>

五、CSS 变量直接使用 ​

组件库所有样式均基于 --xtf-* CSS 变量，业务侧可直接引用：

css
.card {
  background: var(--xtf-color-surface);
  border: 1rpx solid var(--xtf-color-border);
  border-radius: var(--xtf-radius-lg);
  box-shadow: var(--xtf-shadow-card);
}

常用工具类（定义于 theme/index.scss）：

类名说明
.xtf-theme-surface内容面色背景
.xtf-theme-card卡片风格容器
.xtf-theme-glass玻璃态容器

六、注册自定义主题 ​

通过 registerTheme 注册完整自定义主题，再通过 setTheme 切换：

js
import { themeManager } from '@/uni_modules/xtf-linkui'

themeManager.registerTheme('my-brand', {
  colors: {
    primary: '#c62828',
    primarySoft: 'rgba(198, 40, 40, 0.14)',
    background: '#fff8f7',
    surface: '#ffffff',
    text: '#2c1616',
    border: '#f0d6d4'
  },
  componentTokens: {
    card: { bg: 'rgba(255, 255, 255, 0.84)' },
    toast: { lightBg: 'rgba(255, 255, 255, 0.98)' }
  }
})

themeManager.setTheme('my-brand')

注册的主题基于内置 light 主题合并，未提供的字段自动继承。

详细的字段说明、推荐流程与常见问题见 主题定制。

MIT Licensed

Copyright © 2026 xtf-linkui