@autobg/babel.macro v1.5.0

🎨 @autobg/babel.macro

基于 babel-plugin-macros 的宏工具，专为 styled-components 设计。通过简单的本地图片路径，自动获取图片尺寸并设置相应的 CSS 样式。

✨ 核心特性

• 🚀 支持 Vite 和 Webpack 构建工具
• 🔄 识别图片尺寸并自动应用
• 📍 灵活支持相对路径和路径别名
• 📐 支持多种灵活的缩放模式
• 🎨 提供常规和 aspect-ratio 两种模式
• 📏 支持单位转换（px、rem、vw）

📦 安装

pnpm add @autobg/babel-macro babel-plugin-macros styled-components

⚙️ 配置

Vite 配置

// vite.config.ts
import { resolve } from 'node:path'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    react({
      include: /\.(jsx|tsx)$/,
      babel: {
        plugins: [
          'babel-plugin-macros',
          'styled-components',
        ],
        babelrc: false,
        configFile: false,
      },
    }),
  ],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
})

Webpack 配置

// craco.config.ts
import type { CracoConfig } from '@craco/types'
import { resolve } from 'node:path'
import { defineAutobgMacro } from '@autobg/babel.macro'

export default {
  webpack: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
  babel: {
    plugins: [
      // 你也可以用 .babel-plugin-macrosrc.js
      ['babel-plugin-macros', {
        autobg: defineAutobgMacro({
          unit: 'px',
        }),
      }],
      ['babel-plugin-styled-components', { displayName: true }],
    ],
  },
} satisfies CracoConfig

注意：以上 Webpack 配置示例使用 craco，但同样适用于其他 Webpack 配置，只要确保正确配置了 babel 插件即可。

🎯 使用指南

基础用法

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

const Foo = styled.div`
  /* 基本用法 - 自动设置背景图和尺寸 */
  ${autobg('@/assets/foo.png')}
`

等比缩放

固定宽度或高度

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

const Foo = styled.div`
  /* 固定宽度，高度按比例自动计算 */
  ${autobg('@/assets/foo.png', 'w', 100)}
  ${autobg('@/assets/foo.png', 'width', 100)}

  /* 固定高度，宽度按比例自动计算 */
  ${autobg('@/assets/foo.png', 'h', 100)}
  ${autobg('@/assets/foo.png', 'height', 100)}
`

整体缩放比例

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

const Foo = styled.div`
  /* 数值形式（0.75倍缩放） */
  ${autobg('@/assets/foo.png', 0.75)}
  ${autobg('@/assets/foo.png', 's', 0.75)}
  ${autobg('@/assets/foo.png', 'scale', 0.75)}

  /* 百分比形式（缩放至75%） */
  ${autobg('@/assets/foo.png', '75%')}
  ${autobg('@/assets/foo.png', 's', '75%')}
  ${autobg('@/assets/foo.png', 'scale', '75%')}
`

使用 aspect-ratio 属性

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

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

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

// 父元素高度可能会动态变化
const Parent = styled.div`
  height: 200px;
`

// 子元素会自动保持图片原始宽高比并适应父元素
const Child = styled.div`
  ${autobg.aspect('@/assets/foo.png', 'height')}
`

export function Component() {
  return (
    <Parent>
      <Child />
    </Parent>
  )
}

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

基础用法

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

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

const Foo = styled.div`
  ${autobg.aspect('@/assets/foo.png')}
  /* 需要手动设置宽度或高度 */
  width: 100%;
`

📐 指定生成宽度或高度

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

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

// 生成高度，保持原图宽高比
const HeightAuto = styled.div`
  ${autobg.aspect('@/assets/foo.png', 'height')}
  ${autobg.aspect('@/assets/foo.png', 'h')}
`

// 生成宽度，保持原图宽高比
const WidthAuto = styled.div`
  ${autobg.aspect('@/assets/foo.png', 'width')}
  ${autobg.aspect('@/assets/foo.png', 'w')}
`

自定义比例

设置宽高：

import autobg from '@autobg/babel.macro'
import { styled } from 'styled-components'

// 设置高度值，保持原图宽高比
const HeightCustom = styled.div`
  ${autobg.aspect('@/assets/foo.png', 'height', '78%')}
  ${autobg.aspect('@/assets/foo.png', 'h', '78px')}
  ${autobg.aspect('@/assets/foo.png', 'h', '78rem')}
`

// 设置宽度值，保持原图宽高比
const WidthCustom = styled.div`
  ${autobg.aspect('@/assets/foo.png', 'width', '78%')}
  ${autobg.aspect('@/assets/foo.png', 'w', '78px')}
  ${autobg.aspect('@/assets/foo.png', 'w', '78rem')}
`

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

📋 缩放选项总览

💡 提示：使用路径别名或 public 目录下的图片时，需要确保 alias 和 publicPath 配置与构建工具配置保持一致。

📝 配置项说明

📄 许可证

MIT