在 Uni-App (Vue 3) 项目中配置 UnoCSS

凯哥1970
970 阅读3分钟

本指南将引导您如何在 uni-app (Vue 3 版本) 项目中集成并配置 UnoCSS，一个即时、按需的原子化 CSS 引擎。

前置选择：项目类型

在开始之前，请根据您的项目需求做出选择：

  • 独立前端项目: 如果您的项目仅包含前端部分，选择 uni-app 即可。
  • 包含后端管理: 如果您计划构建一个包含后端管理平台的完整项目，推荐直接使用 uni-admin，它已经集成了权限控制等多种常用功能。

image.png 注意，记得选择 vue3 的项目。

注意: 本指南默认您已创建了一个基于 Vue 3 的 uni-app 项目。

第一步：安装 unocss

首先，将 unocss 添加到您的项目开发依赖中。

pnpm add unocss -D

第二步：在 vite.config.ts 中引入

从 0.59.x 版本开始，UnoCSS 仅支持 ESM (ECMAScript Modules)。因此，我们需要在 Vite 配置文件中进行相应的调整。

// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";

export default defineConfig(async () => {
  // 动态导入 unocss/vite 插件
  const UnoCSS = (await import('unocss/vite')).default
  
  return {
    plugins: [
      uni(),
      UnoCSS(), // 添加 UnoCSS 插件
    ],
  }
});

注解: 此处使用 async/await 和动态 import() 是因为 unocss@0.59.x 及以上版本已不再支持 CommonJS，必须以 ESM 的方式异步加载。

第三步：在 main.ts 中导入样式

为了让 UnoCSS 生成的样式在整个应用中生效，您需要在项目的主入口文件 main.ts 中导入虚拟的样式文件。

// main.ts
import { createSSRApp } from "vue";
import App from "./App.vue";

// 关键：导入由 UnoCSS 生成的虚拟 CSS 文件
import "virtual:uno.css";

export function createApp() {
  const app = createSSRApp(App);
  return {
    app,
  };
}

注解: import "virtual:uno.css"; 这一行非常重要。它并非一个真实存在的文件，而是由 UnoCSS 插件在内存中生成的一个虚拟模块，包含了所有根据您的 class 名称按需生成的 CSS 规则。

第四步：创建并配置 unocss.config.ts

在项目根目录下创建一个 unocss.config.ts 文件，这是 UnoCSS 的核心配置文件。主要的配置项有 presets, transformers, rules, 和 shortcuts。

  • presets (预设) : 提供基础的原子化类名集合，例如 presetUno 提供了类似 Tailwind CSS 的默认工具类。
  • transformers (转换器) : 提供额外的功能，如属性化模式 (<div text-center>) 等。
  • rules (自定义规则) : 允许您创建自己的原子化类。您可以将一个或多个 CSS 声明定义为一个新的类名。
  • shortcuts (快捷方式) : 这是 rules 的一个强大补充，允许您将多个已有的原子化类组合成一个新的、更语义化的类名，极大地提高开发效率和可维护性。

配置文件示例:

// unocss.config.ts
import { defineConfig, presetUno, presetAttributify, presetIcons } from "unocss";

export default defineConfig({
  // 预设集合
  presets: [
    presetUno(),
    presetAttributify(), // 启用属性化模式
    presetIcons()        // 启用图标预设
  ],

  // 自定义规则
  rules: [
    // 在这里可以添加您的自定义规则，例如：
    // ['m-1', { margin: '0.25rem' }]
  ],

  // 自定义快捷方式
  shortcuts: {
    // 基础布局与标题
    'section-box': 'p-[10px] bg-white rounded-[10px] shadow-[0px_5px_2px_0px_#F5F5F5] mb-[20px]',
    'section-title': 'py-[12px] px-0 flex items-center justify-start',
    'title-h2': 'text-[18px] text-[#333] mx-[6px] my-0',
    'title-line': 'w-[4px] h-[12px] rounded-[10px] bg-[#2979ff]',
    'font-universal-head': 'pt-[20px] pr-0 pb-[30px] pl-[20px] h-[85px] text-[26px] font-["PingFangSC-Semibold,_PingFang_SC"] font-semibold text-[#1c1c1c] leading-[37px] flex items-center',
    
    // 常用组件样式及覆盖
    'universal-background': 'bg-[#f8fafc]!', // ! 表示 !important
    'uni-card-rounded': 'rounded-[10px]!', // 覆盖 uni-card 的圆角
    'uni-section-forms-item': 'mb-[30px]!',
    'table-content': 'mt-[16px]!',
    'uni-repair-table-scroll': 'min-h-[calc(100vh-417px)]! box-border', // 简化复杂的 calc 计算
    
    // 交互与状态
    'u-image-pointer': 'cursor-pointer',
    'opt-button': 'cursor-pointer p-2',
    'enable-scroll': 'overflow-y-auto!',
  }
});

注解: shortcuts 是 UnoCSS 的精髓之一。通过定义如 section-box 这样的快捷方式，您可以用一个类名来代替一长串的原子化类，使模板代码更加简洁、易读。这有助于在项目中形成一套统一的设计规范。

avatar
文章
阅读
粉丝