postcss-rule-unit-converter

基于规则的通用 PostCSS 单位转换插件。

场景示例文档：COOKBOOK.zh-CN.md
API 文档：API.zh-CN.md
迁移文档：MIGRATION.zh-CN.md
Preset 编写指南：PRESET_AUTHORING.zh-CN.md

特性

一个插件统一处理 rpx、px、rem、vw、vh 以及自定义单位
按规则顺序匹配转换
内置常见单位的双向 preset
复用仓库里现有的属性过滤、选择器黑名单、文件排除等能力
同时支持单个 preset 和按场景封装好的 preset group

心智模型

每条规则负责匹配一种源单位并生成一个新值。
规则按顺序执行。
如果多条规则都能命中同一个源单位，先写的那条优先。
需要组合多组 preset 和自定义规则时，用 composeRules(...) 明确最终顺序。

用法

import postcss from 'postcss'
import unitConverter, { composeRules, presets } from 'postcss-rule-unit-converter'

const result = await postcss([
  unitConverter({
    rules: composeRules(
      presets.remToViewport({ viewportWidth: 375 }),
      presets.pxToRem({ rootValue: 16 }),
    ),
  }),
]).process('.title{font-size:1rem;margin:16px}', { from: undefined })

分组 Preset

import postcss from 'postcss'
import unitConverter, { composeRules, presets } from 'postcss-rule-unit-converter'

const result = await postcss([
  unitConverter({
    rules: composeRules(
      presets.rpxPresetGroup({
        ratio: 2,
        rootValue: 16,
        viewportWidth: 375,
        viewportHeight: 667,
      }),
      {
        from: 'em',
        to: 'rpx',
        factor: 32,
      },
    ),
  }),
]).process('.demo{font-size:32rpx;left:10vw}', { from: undefined })

内置的分组 preset：

presets.rpxPresetGroup() 把 px/rem/vw/vh 归一成 rpx
presets.pxPresetGroup() 把 rem/rpx/vw/vh 归一成 px
presets.viewportPresetGroup() 把 px/rem/rpx 归一成单一目标轴的 vw 或 vh
presets.webPresetGroup() 提供一组偏 Web 场景的 px/rem/vw/vh/rpx 常用规则

从 `postcss-units-to-px` 迁移

presets.unitsToPx() 支持和 postcss-units-to-px 同形状的 unitMap：

import postcss from 'postcss'
import unitConverter, { presets } from 'postcss-rule-unit-converter'

const result = await postcss([
  unitConverter({
    propList: ['*'],
    rules: presets.unitsToPx({
      unitMap: {
        rem: 16,
        vw: false,
        foo: null,
      },
      transform(value, unit, context) {
        return unit === 'foo' && context.prop === 'margin' ? value * 10 : undefined
      },
    }),
  }),
]).process('.demo{font-size:1rem;width:1vw;margin:2foo}', { from: undefined })

对象形式的 unitMap 会覆盖并合并默认的 rem/em/vw/vh/vmin/vmax/rpx 映射。Map 和数组形式会保留用户传入顺序，并且不合并默认值。单个单位规则为 false 时跳过该单位；为 null 时走 transform(value, unit, context) 兜底。

自定义 Preset

单条 preset，自带导出的类型：

import type { PresetFactory, RemBasedPresetOptions } from 'postcss-rule-unit-converter'
import postcss from 'postcss'
import unitConverter, {
  definePreset

} from 'postcss-rule-unit-converter'

const remToDp: PresetFactory<RemBasedPresetOptions> = definePreset((options = {}) => {
  const { rootValue = 16, minValue, to = 'dp' } = options
  return {
    from: 'rem',
    to,
    minValue,
    transform: (value, context) => {
      const resolvedRootValue = typeof rootValue === 'function'
        ? rootValue(context.input)
        : rootValue
      return value * resolvedRootValue
    },
  }
})

const result = await postcss([
  unitConverter({
    rules: [remToDp({ rootValue: 20 })],
  }),
]).process('.demo{font-size:1rem}', { from: undefined })

分组 preset，自带导出的类型：

import type { PresetGroupFactory, RemBasedPresetOptions } from 'postcss-rule-unit-converter'
import postcss from 'postcss'
import unitConverter, {
  definePresetGroup

} from 'postcss-rule-unit-converter'

type MyPresetOptions = RemBasedPresetOptions & {
  ratio?: number
}

const mobilePresetGroup: PresetGroupFactory<MyPresetOptions> = definePresetGroup((options = {}) => {
  const { rootValue = 16, ratio = 2 } = options
  return [
    {
      from: 'rem',
      to: 'rpx',
      transform: (value, context) => {
        const resolvedRootValue = typeof rootValue === 'function'
          ? rootValue(context.input)
          : rootValue
        return value * resolvedRootValue * ratio
      },
    },
    {
      from: 'px',
      to: 'rpx',
      factor: ratio,
    },
  ]
})

const result = await postcss([
  unitConverter({
    rules: mobilePresetGroup({ rootValue: 16, ratio: 2 }),
  }),
]).process('.demo{font-size:1rem;margin:16px}', { from: undefined })

自定义 transform 规则：

import postcss from 'postcss'
import unitConverter from 'postcss-rule-unit-converter'

const result = await postcss([
  unitConverter({
    rules: [
      {
        from: /^x$/,
        to: 'px',
        transform(value, context) {
          return context.prop === 'letter-spacing' ? value * 4 : value * 8
        },
      },
    ],
  }),
]).process('.demo{letter-spacing:2x;margin:2x}', { from: undefined })

使用建议

想保留兜底声明时，用 replace: false。
想避免多条 preset 对同一源单位发生竞争时，用 propList 把适用范围收窄。
项目里如果有一个主单位体系，优先使用 preset group。
如果你要严格控制命中顺序，优先直接写显式规则数组。
使用 presets.viewportPresetGroup() 时，建议显式指定 viewportUnit: 'vw' 或 viewportUnit: 'vh'。
在业务里沉淀可复用 preset 时，优先使用 definePreset(...) 和 definePresetGroup(...)。
RuleContext.fromUnit 是用于规则匹配的源单位；rawUnit 保留原始大小写；rawValue 是 Number(...) 前的数字文本；match 是完整匹配片段。
字符串单位 matcher 会归一化为小写。默认正则下 'px' 匹配小写 px；需要匹配 PX/Px 时使用 /^px$/i 或自定义 unitRegex。
默认正则会跳过字符串、url(...) 和 var(...)。自定义 unitRegex 会完全替换默认正则；如果仍要跳过这些内容，需要在自定义正则里保留跳过分支。
如果你想直接抄场景配置，优先看 cookbook。

Presets

自定义 preset 辅助类型：

definePreset()
definePresetGroup()
type PresetFactory<TOptions>
type PresetGroupFactory<TOptions>
presets.remToPx()
presets.remToRpx()
presets.remToRpxRatio()
presets.remToRpxByRatio()
presets.remToResponsivePixel()
presets.remToViewport()
presets.remToVw()
presets.remToVh()
presets.pxToRem()
presets.pxToViewport()
presets.pxToVw()
presets.pxToVh()
presets.pxToRpx()
presets.rpxToPx()
presets.rpxToRem()
presets.rpxToVw()
presets.rpxToVh()
presets.vwToPx()
presets.vhToPx()
presets.vwToRem()
presets.vhToRem()
presets.vwToRpx()
presets.vhToRpx()
presets.pxPresetGroup()
presets.rpxPresetGroup()
presets.viewportPresetGroup()
presets.webPresetGroup()
presets.unitsToPx()

postcss-rule-unit-converter ​

特性 ​

心智模型 ​

用法 ​

分组 Preset ​

从 postcss-units-to-px 迁移 ​

更多示例 ​

自定义 Preset ​

使用建议 ​

Presets ​