Set the width and height of elements based on the background image
npm install @autobg/postcss

基于 PostCSS 的插件,提供了名为 @autobg 和 @autobg-aspect 的 AtRule。通过简单的图片路径声明,即可自动设置元素的背景图片和尺寸。
- 🚀 支持 Vite 和 Webpack 构建工具
- 🔄 识别图片尺寸并自动应用
- 📍 灵活支持相对路径和路径别名
- 📐 支持多种灵活的缩放模式
- 🎨 提供 @autobg 和 @autobg-aspect 两种模式
``bash`
pnpm add @autobg/postcss
`ts
// vite.config.ts
import { resolve } from 'node:path'
import { postcssAutobg } from '@autobg/postcss'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: {
'@': resolve(__dirname, 'src'),
},
},
css: {
postcss: {
plugins: [
postcssAutobg(),
],
},
},
})
`
`ts
// craco.config.ts
import type { CracoConfig } from '@craco/types'
import { resolve } from 'node:path'
export default {
webpack: {
alias: {
'@': resolve(__dirname, 'src'),
},
},
style: {
postcss: {
mode: 'extends',
loaderOptions: {
postcssOptions: {
plugins: [postcssAutobg()],
}
}
}
},
} satisfies CracoConfig
`
> 注意:以上 Webpack 配置示例使用 craco,但同样适用于其他 Webpack 配置。
`css`
.foo {
/ 基本用法 - 自动设置背景图和尺寸 /
@autobg url('./assets/foo.png');
}
#### 固定宽度或高度
`css
.foo {
/ 固定宽度,高度按比例计算 /
@autobg url('./assets/foo.png') width(100px);
@autobg url('./assets/foo.png') w(100px);
/ 固定高度,宽度按比例计算 /
@autobg url('./assets/foo.png') height(100px);
@autobg url('./assets/foo.png') h(100px);
}
`
#### 整体缩放比例
`css
.foo {
/ 应用均匀缩放(数字) /
@autobg url('./assets/foo.png') scale(0.78);
@autobg url('./assets/foo.png') s(0.78);
/ 应用均匀缩放(百分比) /
@autobg url('./assets/foo.png') scale(78%);
@autobg url('./assets/foo.png') s(78%);
}
`
利用现代 CSS 的 aspect-ratio 属性保持元素宽高比,实现更灵活的布局控制。
特别适用于需要响应式缩放的场景,当父元素尺寸动态变化时尤为有效:
`css
/ 父元素高度可能会动态变化 /
.parent {
height: 200px;
}
.child {
/ 子元素会自动保持图片原始宽高比并适应父元素 /
@autobg-aspect url('./assets/foo.png') height();
}
`
当父元素的高度发生变化时,子元素会自动保持原始图片的宽高比例,实现等比例缩放。
#### 基础用法
不指定宽高时,仅生成背景和宽高比:
`css`
.foo {
@autobg-aspect url('./assets/foo.png');
/ 需要手动设置宽度或高度 /
width: 100%;
}
#### 📐 指定生成宽度或高度
自动生成一个维度的值(默认100%):
`css
.foo {
/ 生成高度,保持原图宽高比 /
@autobg-aspect url('./assets/foo.png') height();
@autobg-aspect url('./assets/foo.png') h();
/ 生成宽度,保持原图宽高比 /
@autobg-aspect url('./assets/foo.png') width();
@autobg-aspect url('./assets/foo.png') w();
}
`
> 💡 注意:所有方法参数都必须带括号,即使不传入具体数值。例如必须使用 height() 而不是 height,这是 PostCSS AtRule 函数调用的语法要求。
#### 自定义比例
设置宽高:
`css
.foo {
/ 设置高度值,保持原图宽高比 /
@autobg-aspect url('./assets/foo.png') height(78%);
@autobg-aspect url('./assets/foo.png') h(78px);
@autobg-aspect url('./assets/foo.png') h(78rem);
/ 设置宽度值,保持原图宽高比 /
@autobg-aspect url('./assets/foo.png') width(78%);
@autobg-aspect url('./assets/foo.png') w(78px);
@autobg-aspect url('./assets/foo.png') w(78rem);
}
`
> 💡 提示:在 aspect 模式下,值会直接设置到 width 或 height 属性上,不会经过转换。
| 选项 | 语法 | 功能描述 |
| ------------------- | ------------------------------------ | ---------------------------------------------------- |
| 宽度缩放 | @autobg url(...) width(值) | 固定宽度,高度按比例自动计算(值表示像素等具体单位) |@autobg url(...) height(值)
| 高度缩放 | | 固定高度,宽度按比例自动计算(值表示像素等具体单位) |@autobg url(...) scale(值或百分比)
| 整体缩放 | | 按比例统一缩放两个维度(数值或百分比表示缩放比例) |@autobg-aspect url(...) width()
| 宽高比模式-宽度 | | 生成宽度并设置 aspect-ratio,保持原图宽高比 |@autobg-aspect url(...) height()
| 宽高比模式-高度 | | 生成高度并设置 aspect-ratio,保持原图宽高比 |@autobg-aspect url(...) width(值)
| 宽高比模式-自定义宽 | | 设置宽度为指定值并保持原图宽高比 |@autobg-aspect url(...) height(值)
| 宽高比模式-自定义高 | | 设置高度为指定值并保持原图宽高比 |
如果遇到 css(unknownAtRules) 警告,请参考以下解决方案:
- 解决 Vue.js 项目中的 CSS unknownAtRules 错误
| 配置项 | 类型 | 默认值 | 说明 |
| ---------- | ------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| publicPath | string | 'public' | 静态资源目录路径,需要与构建工具配置保持一致 |Record
| alias | | { '@/': 'src/', '~': 'src/', '~@/': 'src/' } | 路径别名配置,需要与构建工具配置保持一致{}` |
不使用路径别名时,传入空对象
MIT