@autobg/unocss v1.5.0

🎨 @autobg/unocss

能够根据本地图片路径为元素生成完整的背景图和宽高样式的 UnoCSS 预设。

✨ 核心特性

• 🚀 完美支持 Vite 构建工具
• 🔄 智能识别 图片尺寸并自动应用
• 📍 灵活支持 相对路径和路径别名
• 🎨 无缝集成 UnoCSS 生态系统
• 📐 多种模式 提供灵活的缩放选项

⚠️ 注意：暂不支持 unocss@66.1.0 版本，该版本处于 beta 阶段，preset 机制有所变化。

📦 安装

pnpm add @autobg/unocss

⚙️ 配置

Vite 项目

// uno.config.ts
import { autobgPreset } from '@autobg/unocss'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    autobgPreset({
      // 使用绝对路径，而不是 process.cwd()。
      // 因为 VSCode 的 unocss 扩展在调用 preset 的 transformer 时不会传递项目根目录路径。
      // 这会导致代码高亮工具提示不正确，但不会影响实际的类名生成。
      root: import.meta.env.dirname,

      // 转换 width 和 height 的值，可以为其添加样式单位
      // 默认会转换为 `px` 单位
      // 这只是一个临时方案，未来可能会废弃
      transformSize: value => `${value}px`,
    }),
  ],
})

Webpack 支持说明

目前暂不支持 Webpack，主要原因：

• Webpack 的 transformer 处理机制导致路径无法正确替换
• UnoCSS 官方的 bg-[url()] 规则在 Webpack 环境中同样存在兼容性问题

🎯 使用指南

基础用法

轻松指定背景图片路径：

<div className="autobg-['url(/foo.png)']" />
<div className="autobg-['url(@/assets/foo.png)']" />
<div className="autobg-['url(../assets/foo.png)']" />

等比缩放

固定宽度或高度

指定一个维度，另一个维度将按原图比例自动计算：

// 指定宽度
<div className="autobg-['url(/foo.png)']-w200" />

// 使用分隔符连接数值
<div className="autobg-['url(/foo.png)']-w-200" />

// 指定高度
<div className="autobg-['url(/foo.png)']-h200" />

// 使用分隔符连接数值
<div className="autobg-['url(/foo.png)']-h-200" />

💡 提示：暂不支持样式单位（如 px、rem 等），这会导致缩放比例无法正确计算。 特别注意 w-200 中的 - 仅作为分隔符，不表示负值。

百分比缩放

使用百分比值控制缩放比例：

// 宽度百分比
<div className="autobg-['url(/foo.png)']-w78%" />

// 高度百分比
<div className="autobg-['url(/foo.png)']-h78%" />

💡 提示：百分比必须以 % 结尾，否则将被视为普通数值。

整体缩放比例

不指定具体维度时，将按整体比例均匀调整：

// 小数形式（0.78倍缩放）
<div className="autobg-['url(/foo.png)']-0.78" />

// 百分比形式（缩放至78%）
<div className="autobg-['url(/foo.png)']-78%" />

使用 aspect-ratio 属性

利用现代 CSS 的 aspect-ratio 属性保持元素宽高比，实现更灵活的布局控制。

特别适用于需要响应式缩放的场景，当父元素尺寸动态变化时尤为有效：

// 父元素高度可能会动态变化
<div className="h200">
  {/* 子元素会自动保持图片原始宽高比并适应父元素 */}
  <div className="autobg-aspect-['url(/foo.png)']-h"></div>
</div>

当父元素的高度发生变化时，子元素会自动保持原始图片的宽高比例，实现等比例缩放。

基础用法

不指定宽高时，仅生成背景和宽高比：

<div className="autobg-aspect-['url(/foo.png)']" />

📐 指定生成宽度或高度

自动生成一个维度的值（默认100%）：

// 生成高度，保持原图宽高比
<div className="autobg-aspect-['url(/foo.png)']-h" />

// 生成宽度，保持原图宽高比
<div className="autobg-aspect-['url(/foo.png)']-w" />

自定义比例

设置宽高：

<div className="autobg-aspect-['url(/foo.png)']-h78%" />
<div className="autobg-aspect-['url(/foo.png)']-h78" />
<div className="autobg-aspect-['url(/foo.png)']-h78rem" />

<div className="autobg-aspect-['url(/foo.png)']-w78%" />
<div className="autobg-aspect-['url(/foo.png)']-w78" />
<div className="autobg-aspect-['url(/foo.png)']-w78rem" />

💡 提示：在 aspect 模式下，值会直接设置到 width 或 height 属性上，不会经过转换。

📋 规则总览

⚙️ 配置项详解

📄 许可证

MIT