@quiteer/web

Appearance

@quiteer/unocss ​

面向 Vite 的 UnoCSS 集成插件与可复用配置集合。提供统一的预设组合、主题、规则与快捷类，并以插件形式一键启用。

特性 ​

  • 集成即用：导出 Vite 插件函数，开箱加载统一的 uno.config 配置
  • 预设组合：默认启用 presetWind4、presetIcons、presetWebFonts
  • 主题与快捷：提供可复用的 theme 与 shortcuts 集合
  • 自定义规则：支持组件层规则与通用规则扩展
  • 生产友好：构建外部化原生依赖，避免跨平台 .node 模块打包问题

安装 ​

  • 主项目（使用者）需安装：
    • pnpm add -D @quiteer/unocss
    • 使用 Vite 5+（vite@>=5）

快速开始 ​

ts
// vite.config.ts
import UnoPreset from '@quiteer/unocss'
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue(),
    UnoPreset() // 加载统一的 UnoCSS 配置
  ]
}

在 Qvite 中使用 ​

  • 若使用 @quiteer/vite（qvite），只需开启 UnoCSS：
ts
// qvite.config.ts
import { defineConfig } from '@quiteer/vite'

export default defineConfig({
  UnoCSS: true
})
  • 启用后，qvite 会自动注入 import 'uno.css' 到虚拟 HTML，确保样式生效（实现位置：packages/qvite/src/transform.ts:40-64）。

内置插件 ​

@quiteer/unocss 默认集成了以下 UnoCSS 预设和转换器：

默认配置 ​

  • shortcuts
ts
import type { PresetUnoTheme, UserShortcuts } from 'unocss'

export const shortcuts = {
  // Flex
  'flex-center': 'flex justify-center items-center',
  'flex-x-center': 'flex justify-center',
  'flex-y-center': 'flex items-center',
  'flex-col': 'flex flex-col',
  'flex-col-center': 'flex-center flex-col',
  'flex-col-stretch': 'flex-col items-stretch',
  'flex-between': 'flex justify-between items-center',
  'i-flex-center': 'inline-flex justify-center items-center',
  'i-flex-x-center': 'inline-flex justify-center',
  'i-flex-y-center': 'inline-flex items-center',
  'i-flex-col': 'flex-col inline-flex',
  'i-flex-col-center': 'flex-col i-flex-center',
  'i-flex-col-stretch': 'i-flex-col items-stretch',
  'flex-1-hidden': 'flex-1 overflow-hidden',

  // Absolute / Fixed
  'absolute-lt': 'absolute left-0 top-0',
  'absolute-lb': 'absolute left-0 bottom-0',
  'absolute-rt': 'absolute right-0 top-0',
  'absolute-rb': 'absolute right-0 bottom-0',
  'absolute-tl': 'absolute-lt',
  'absolute-tr': 'absolute-rt',
  'absolute-bl': 'absolute-lb',
  'absolute-br': 'absolute-rb',
  'absolute-center': 'absolute-lt flex-center size-full',
  'fixed-lt': 'fixed left-0 top-0',
  'fixed-lb': 'fixed left-0 bottom-0',
  'fixed-rt': 'fixed right-0 top-0',
  'fixed-rb': 'fixed right-0 bottom-0',
  'fixed-tl': 'fixed-lt',
  'fixed-tr': 'fixed-rt',
  'fixed-bl': 'fixed-lb',
  'fixed-br': 'fixed-rb',
  'fixed-center': 'fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2',
  'abs-center': 'absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2',
  'abs-full': 'absolute inset-0',

  // Dimensions
  'wh-full': 'w-full h-full',
  'w-screen-w': 'w-100vw',
  'h-screen-h': 'h-100vh',

  // Text
  'nowrap-hidden': 'overflow-hidden whitespace-nowrap',
  'ellipsis-text': 'nowrap-hidden text-ellipsis',
  'ellipsis': 'truncate',
  'text-ellipsis': 'truncate',

  // Interaction
  'cursor-pointer': 'cursor-pointer select-none',
  'hover-opacity': 'hover:opacity-80 transition-opacity cursor-pointer',

  // ============ 进场/退场动画 shortcuts ============

  // 1. 淡入淡出
  'anim-fade': 'transition-opacity duration-250 ease-in-out',
  'anim-fade-enter': 'opacity-0',
  'anim-fade-leave': 'opacity-0',

  // 2. 从右侧滑入/滑出（适合抽屉、右侧面板）
  'anim-slide-right': 'transition-transform duration-300 ease-layout',
  'anim-slide-right-enter': 'translate-x-full',
  'anim-slide-right-leave': 'translate-x-full',

  // 3. 从左侧滑入/滑出（适合左侧菜单）
  'anim-slide-left': 'transition-transform duration-300 ease-layout',
  'anim-slide-left-enter': '-translate-x-full',
  'anim-slide-left-leave': '-translate-x-full',

  // 4. 缩放淡入（适合弹窗、卡片）
  'anim-scale-fade': 'transition-[transform,opacity] duration-250 ease-in-out',
  'anim-scale-fade-enter': 'scale-95 opacity-0',
  'anim-scale-fade-leave': 'scale-90 opacity-0',

  // 5. ✅ 宽度塌陷动画（核心！用于侧边栏展开/收起）
  'anim-width-collapse': 'overflow-hidden transition-width duration-300 ease-layout',
  'anim-width-collapse-enter': 'w-0!',
  'anim-width-collapse-leave': 'w-0!',

  // 6. 高度塌陷（适合折叠面板）
  'anim-height-collapse': 'overflow-hidden transition-height duration-300 ease',
  'anim-height-collapse-enter': 'h-0!',
  'anim-height-collapse-leave': 'h-0!',

  // ============ 辅助类 ============
  // 强制内联样式优先级（用于动画结束状态）
  'w-0!': 'w-0 !important',
  'h-0!': 'h-0 !important'
} satisfies UserShortcuts<PresetUnoTheme>
  • theme
ts
import type { PresetUnoTheme } from 'unocss'

export const theme: PresetUnoTheme = {}
  • rules
ts
import type { Rule } from 'unocss'

const baseRules: Rule[] = [
  [/^wh-(\d+)$/, ([, d]) => ({ width: `${Number(d) / 4}rem`, height: `${Number(d) / 4}rem` })]
]

export const buttonRules: Rule[] = [
  [/^btn-(primary|secondary)$/, ([_, variant]) => {
    const colors: Record<string, string> = {
      primary: '#3b82f6',
      secondary: '#6366f1'
    }
    return {
      'background-color': colors[variant],
      'color': 'white',
      'padding': '0.5rem 1rem',
      'border-radius': '0.25rem',
      'font-weight': '500'
    }
  }, { layer: 'components' }]
]

export const cardRules: Rule[] = [
  [/^card$/, () => ({
    'border-radius': '0.5rem',
    'box-shadow': '0 1px 3px rgba(0,0,0,0.1)',
    'padding': '1rem',
    'background-color': 'white'
  }), { layer: 'components' }]
]

export const rules: Rule[] = [
  ...baseRules,
  ...buttonRules,
  ...cardRules
]

如何拓展配置 ​

在根目录下创建 uno.config.ts 配置文件，即可拓展配置。

  • defineConfig

可以使用 defineConfig 函数来获取代码提示。

  • unoConfig

可以使用 unoConfig 来获取默认配置。

ts
// uno.config.ts
import { defineConfig,unoConfig } from '@quiteer/unocss/uno.config.ts'

const myConfig = defineConfig({
  rules: [[/^wh-(\d+)$/, ([, d]) => ({ width: `${Number(d)/4}rem`, height: `${Number(d)/4}rem` })]]
})

export default myConfig

配合 IDE 插件代码提示

  • 虽然已经把 unocss 相关的包都内聚了，但是为了代码高亮提示还是要在根目录下创建 uno.config.ts 文件。
  • 检查是否已经安装了对应插件，windcss 插件会跟 unocss 插件冲突

如果你对当前配置满意，就不需要在 uno.config.ts 文件中配置了。

ts
// uno.config.ts
export default {}

Released under the MIT License.

Copyright © 2025-11-present Quiteer