编译时样式生成方案

VaporCSS

为 UniApp X 蒸汽模式量身定制的元子化样式系统，编译时生成，零运行时开销。

快速开始使用示例技术特点

生成策略

编译时

运行时开销

零

适配机制

external-class

介绍

VaporCSS 是一套为 UniApp X 蒸汽模式量身定制的元子化样式系统，采用编译时样式生成方案，为开发者提供简洁、高效、可维护的样式解决方案。

核心功能：

• 🎨 编译时生成：样式在构建时生成，零运行时开销
• 🎯 主题系统：通过 theme.json 统一管理主题
• 🔧 完美兼容：与 UniApp X external-class 机制天然适配
• 📦 按需生成：只生成项目中使用的样式，减小包体积
• 💪 强大灵活：支持自定义规则和主题定制

适用场景：

• 需要高效样式管理的 uni-app x 项目
• 追求开发效率和代码质量的团队
• 需要跨平台兼容的复杂应用
• 对构建性能有要求的大型项目

技术特点：

• 编译期处理：所有增强都在编译期完成，不影响运行时性能
• 模块化设计：清晰的模块化结构，便于扩展和维护
• 跨平台支持：支持所有 uni-app x 支持的平台
• 性能优化：内置多种性能优化策略
• 开发体验：提供良好的开发体验和调试能力

快速开始

安装配置

1. 在 vite.config.ts 中引入 VaporCSS

import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import TuiCollector from "./uni_modules/tui-vitex";
import theme from "./theme.json";

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

2. 在 App.uvue 中引入编译产物 (只要引用了编译器，会自动引入样式文件)

@import url("./uni_modules/tui-vitex/autocss.css");

3. 开始使用

<template>
  <view class="p-4 bg-primary c-white r-20"> Hello VaporCSS! </view>
</template>

为什么选择 VaporCSS

1. 性能优势

• 零运行时开销：样式在编译时生成，避免运行时样式计算
• 按需生成：只生成项目中使用的样式，减小包体积
• 稳定可靠：编译时确定样式行为，避免运行时意外

2. UniApp X 适配

• 蒸汽模式兼容：与 UniApp X 蒸汽模式的样式隔离机制完美适配
• external-class 集成：提供标准化的组件样式扩展方案
• 跨平台一致：在不同平台保持样式一致性

3. 开发体验

• 简洁语法：使用简短的类名表达复杂样式
• 主题统一：通过 theme.json 统一管理设计
• 自动生成：无需手动编写重复样式代码

工作原理

VaporCSS 的核心是 tui-vitex 编译插件，它在 Vite 编译阶段完成以下工作：

1. 收集：扫描项目中的元子化样式类
2. 解析：根据规则和主题变量解析样式
3. 生成：生成最终的 CSS 样式文件
4. 输出：将样式输出到 uni_modules/tui-vitex/autocss.css

工作流程：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  模板中的样式类  │ ──> │  tui-vitex 编译  │ ──> │  生成的 CSS 文件  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        ↑                       ↑                       ↑
        │                       │                       │
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  theme.json 配置  │ ──> │  主题变量解析   │     │  项目中引入使用  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

主题系统

VaporCSS 通过 theme.json 管理设计，支持以下配置：

• 颜色系统：主题色、文本色、边框色等
• 间距系统：内边距、外边距的标准化值
• 圆角系统：不同尺寸的圆角值
• 字体系统：字体大小、字重等

示例配置：

{
  "id": "DefaultMode",
  "name": "默认主题",
  "unit": "rpx",
  "primarynormal": "#2979ff",
  "successnormal": "#19be6b",
  "warningnormal": "#ff9900",
  "errornormal": "#fa3534",
  "colornormal": "#333333",
  "radiusmedium": 16,
  "paddingmedium": 20
  // 更多配置...
}

external-class 最佳实践

在 UniApp X 蒸汽模式中，组件样式隔离更严格，推荐使用 external-class 暴露样式扩展点：

组件开发建议

<template>
  <view class="button" :class="[buttonClass]">
    <text :class="[textClass]">Hello VaporCSS</text>
  </view>
</template>

<script setup>
 defineOptions({
	styleIsolation: 'app-and-page',
	externalClasses: ['button-class', 'text-class'] // 暴露按钮样式扩展点 // 暴露文本样式扩展点
})
 const props = withDefaults(defineProps<>(), {
	 buttonClass: String,
     textClass: String
});
</script>

<style scoped>
.button {
  /* 基础样式 */
}
.text {
  /* 基础文本样式 */
}
</style>

使用方式

<template>
  <t-button
    text=" VaporCSS 类名"
    button-class="bg-primary c-white p-4 r-20"
    text-class="font-medium"
  >
    也可以使用写在style中的类名
  </t-button>
</template>

推荐使用方式

1. 页面开发

直接使用 VaporCSS 类名处理通用样式：

<view class="f faic fjcb p-4 bg-white"
      display: flex;
      flex: 1;
      align-items: center;
      justify-content: space-between;
      padding: 4rpx;
      background-color: white;
  <text class="s-40 sta-c">
      font-size: 40rpx;
      text-align: center;
  </text>
  <button class="bg-primary c-white">
      background-color: primary;
      color: white;
  </button>
</view>

2. 组件开发

• 内部样式：使用稳定的结构类名
• 外部扩展：通过 external-class 暴露样式入口
• 主题变量：使用 theme.json 中的设计

3. 主题定制

通过修改 theme.json 实现全局主题定制，无需修改组件代码。

与其他 CSS 方案对比

特性	VaporCSS	传统 CSS	运行时 CSS 框架
运行时开销	无	无	有
包体积	小（按需生成）	大（全量）	中（动态生成）
开发体验	优秀	一般	良好
UniApp X 适配	完美	一般	一般
主题系统	内置	手动	部分支持

后续阅读

• 主题系统：了解如何配置和使用主题变量
• 布局样式：掌握 Flex、Grid 等布局类
• 文本样式：学习文本相关的样式类
• 颜色系统：了解颜色类的使用方法
• 间距系统：掌握间距类的使用
• 边框与圆角：学习边框和圆角样式
• 动画效果：了解内置的动画类

VaporCSS 为 UniApp X 开发者提供了一套现代化、高效的样式解决方案，让样式开发变得简单而愉快！