Tui Plus Vapor

Appearance

主题配置 ​

主题配置是 tui-vitex 编译器的重要功能之一，它允许开发者通过 theme.json 文件来定义和管理应用的颜色、间距、字体等样式变量，支持 light 和 dark 两种主题模式。

主题配置文件 ​

基本结构 ​

theme.json 文件的基本结构如下：

json
{
  "light": {
    "bg": {},      // 背景色
    "fg": {},      // 前景色
    "tc": {},      // 文本颜色
    "bc": {},      // 边框颜色
    "text": {},    // 文本级别
    "border": {},  // 边框级别
    "fontsize": {}, // 字体大小
    "margin": {},  // 外边距
    "padding": {}, // 内边距
    "radius": {},  // 边框圆角
    "sizeratio": {} // 尺寸比例
  },
  "dark": {
    // 深色主题配置
  }
}

详细配置 ​

1. 颜色配置 ​

json
{
  "light": {
    "bg": {
      "primary": {
        "normal": "#007AFF",
        "dark": "#0056b3",
        "light": "#4da3ff",
        "plain": "#e6f0ff"
      },
      "info": {
        "normal": "#5AC8FA",
        "dark": "#0096cc",
        "light": "#8ddbff",
        "plain": "#e6f7ff"
      }
    },
    "tc": {
      "primary": {
        "normal": "#007AFF",
        "dark": "#0056b3",
        "light": "#4da3ff",
        "plain": "#e6f0ff"
      }
    }
  }
}

2. 文本配置 ​

json
{
  "light": {
    "text": {
      "1": "#333333",  // 一级文本（最主要）
      "2": "#666666",  // 二级文本
      "3": "#999999",  // 三级文本
      "4": "#c0c4cc"   // 四级文本（最次要）
    }
  }
}

3. 间距配置 ​

json
{
  "light": {
    "margin": {
      "large": "24rpx",
      "medium": "16rpx",
      "small": "8rpx",
      "mini": "4rpx"
    },
    "padding": {
      "large": "24rpx",
      "medium": "16rpx",
      "small": "8rpx",
      "mini": "4rpx"
    }
  }
}

4. 字体大小配置 ​

json
{
  "light": {
    "fontsize": {
      "large": "32rpx",
      "medium": "28rpx",
      "small": "24rpx",
      "mini": "20rpx"
    }
  }
}

主题变量生成 ​

生成原理 ​

tui-vitex 会根据 theme.json 配置生成对应的 CSS 变量：

  1. 颜色变量：--tui-bg-primary-normal
  2. 文本变量：--tui-text-1
  3. 间距变量：--tui-margin-medium
  4. 字体变量：--tui-fontsize-large

生成过程 ​

ts
// 生成主题样式配置
function createThemeConfig(keyPrefix, attrName, dir = '') {
  const types = ['info', 'primary', 'error', 'warning', 'success'];
  const effects = ['normal', 'dark', 'light', 'plain'];
  const themeVar = 'TuiTheme';

  const config = {};

  // 生成所有组合
  types.forEach(type => {
    effects.forEach(effect => {
      const typeChar = type.charAt(0);
      const effectChar = effect.charAt(0);
      const key = `${keyPrefix}-${typeChar}${effectChar}`;
      config[key] = `\${${themeVar}}-${attrName}${dir}-${type}-${effect}`;
    });
  });

  // 生成默认类型
  types.forEach(type => {
    const typeChar = type.charAt(0);
    const key = `${keyPrefix}-${typeChar}`;
    config[key] = `\${${themeVar}}-${attrName}${dir}-${type}-normal`;
  });

  return config;
}

主题使用 ​

在元子化样式中使用 ​

html
<view class="tbg-pn tp-m">
  <text class="ttl1 tfsm">Hello World</text>
</view>

在 CSS 中使用 ​

css
.custom-class {
  background-color: var(--tui-bg-primary-normal);
  color: var(--tui-text-1);
  padding: var(--tui-padding-medium);
}

在 UTS 中使用 ​

ts
import { getTuiThemeConfig } from '@/uni_modules/tui-plus-vapor/common/model/theme.uts';

// 获取主题配置
const primaryColor = getTuiThemeConfig('bg', 'primary', 'normal');

主题切换 ​

自动切换 ​

tui-vitex 会根据系统主题自动切换 light 和 dark 模式：

  1. 获取系统主题：通过 uni.getSystemInfo 获取系统主题
  2. 应用主题：根据系统主题应用对应的样式变量
  3. 监听变化：通过 uni.onOsThemeChange 监听主题变化

手动切换 ​

开发者也可以通过代码手动切换主题：

ts
// 设置应用主题
uni.setAppTheme({
  theme: 'dark' // 'light' 或 'dark'
});

// 监听应用主题变化
uni.onAppThemeChange(res => {
  console.log('主题切换为:', res.theme);
});

主题继承 ​

tui-vitex 支持主题继承，你可以基于默认主题进行扩展：

json
{
  "light": {
    "extends": "default", // 继承默认主题
    "bg": {
      "primary": {
        "normal": "#1989fa" // 覆盖主色
      }
    }
  }
}

性能优化 ​

  1. 按需加载：只加载当前主题的样式变量
  2. 缓存机制：缓存生成的主题配置
  3. 最小化：生产环境下最小化主题变量

最佳实践 ​

  1. 统一管理：将所有样式变量集中在 theme.json 中管理
  2. 语义化命名：使用有意义的变量名
  3. 合理分组：按功能和用途分组变量
  4. 版本控制：对主题配置进行版本控制
  5. 文档化：为主题配置添加注释和文档

常见问题 ​

主题不生效 ​

  • 检查 theme.json 格式是否正确
  • 确认主题变量是否正确引用
  • 检查是否正确配置了 light 和 dark 模式

主题切换卡顿 ​

  • 优化主题变量数量
  • 避免在运行时频繁切换主题
  • 使用 CSS 变量而不是内联样式

通过合理配置主题，你可以创建一致、美观且易于维护的应用界面，同时支持深色模式等现代 UI 特性。