Tui Plus Vapor

Appearance

快速开始 ​

本文档将帮助你快速上手 tui-compiler 编译器，了解其基本用法和配置方式。

基本接入 ​

配置 Vite ​

在 vite.config.ts 中配置 tui-compiler 插件，无需手动导入主题配置：

ts
import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import TuiCollector from './uni_modules/tui-compiler';

export default defineConfig({
    devSourcemap: true,
    plugins: [
        TuiCollector(),
        uni()
    ]
});

主题配置 ​

插件启动时会自动检测项目根目录是否存在 theme.json，若不存在则自动创建默认主题配置文件。你也可以手动修改 theme.json 来定制主题。

引入样式 ​

插件会自动处理 App.uvue 和 main.uts 的依赖注入，无需手动配置。在模板中直接使用元子化样式类即可。

核心概念 ​

1. 元子化样式 ​

tui-compiler 会在编译阶段收集模板中的元子化样式类，并生成对应的 CSS 代码：

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

编译后会生成：

css
.tbg-pn {
  background-color: var(--tui-bg-primary-normal);
}
.tp-m {
  padding: var(--tui-padding-medium);
}
.ttl1 {
  color: var(--tui-text-1);
}

2. 主题变量 ​

通过 theme.json 配置主题变量，支持 light 和 dark 两种模式：

  • --tui-bg-primary-normal - 主背景色
  • --tui-text-1 - 一级文本颜色
  • --tui-padding-medium - 中等内边距

3. 环境变量 ​

支持 Vite 风格的环境变量配置：

ts
// .env.development
VITE_API_BASE_URL=https://dev-api.example.com

// .env.production
VITE_API_BASE_URL=https://api.example.com

在代码中使用：

ts
const apiUrl = import.meta.env.VITE_API_BASE_URL;

项目配置 ​

插件选项 ​

选项类型默认值描述
unitstring'px'样式单位（无需配置，默认 px）
themeobject/string-主题配置对象（不传则插件自动检测 theme.json）
debugbooleanfalse是否开启调试模式（计划中）

目录结构 ​

推荐的项目结构：

project/
├── vite.config.ts          # Vite 配置（配置 TuiCollector 插件）
├── theme.json             # 主题配置（插件自动检测创建）
├── .env.development       # 开发环境变量
├── .env.production        # 生产环境变量
├── App.uvue               # 应用入口
├── pages/                 # 页面目录
└── uni_modules/           # 模块目录
    └── tui-compiler/         # tui-compiler 编译器

开发流程 ​

  1. 编写模板：在 .uvue 文件中使用元子化样式类
  2. 编译构建：运行 npm run dev 或 npm run build
  3. 查看产物：检查生成的 autocss.css 文件
  4. 调试优化：根据需要调整主题配置和样式类

常见问题 ​

样式不生效 ​

  • 检查是否正确引入了 autocss.css
  • 确认主题配置是否正确
  • 检查样式类名是否拼写正确

环境变量未定义 ​

  • 确认 .env 文件格式正确
  • 检查变量名是否以 VITE_ 开头
  • 重新启动开发服务器

编译报错 ​

  • 检查模板语法是否正确
  • 确认 theme.json 格式是否正确
  • 查看控制台错误信息

最佳实践 ​

  1. 统一命名规范：使用一致的元子化样式类命名
  2. 合理组织主题：将相关样式变量分组管理
  3. 使用环境变量：区分不同环境的配置
  4. 定期清理：删除未使用的样式类
  5. 性能优化：避免过度使用复杂样式

通过以上步骤，你应该已经能够成功集成和使用 tui-compiler 编译器了。如果遇到问题，可以查看其他章节的详细文档或参考示例代码。