UnoCSS preset-rem-to-px 完全指南:将 rem 单位一键转换为 px
UnoCSS preset-rem-to-px 完全指南:将 rem 单位一键转换为 px
presetRemToPx 是 UnoCSS 官方提供的功能型预设(feature preset),用于在生成 CSS 时将所有工具类中的 rem 单位自动转换为 px,适合需要像素级精确设计、与像素制设计系统对齐或 rem 支持不佳的环境(如邮件模板)。阅读本文后,你将掌握该预设的安装配置、baseFontSize 换算规则、与 preset-wind4 内建处理器的配合方式,以及使用时的顺序与作用范围等关键注意事项。
什么是 preset-rem-to-px
在 UnoCSS 的预设体系中,工具类(utilities)的尺寸值默认大量使用 rem 单位。例如 Wind3 / Mini 预设的间距工具类 p-4 生成的是 padding: 1rem,字号工具类 text-lg 生成的是 font-size: 1.125rem。presetRemToPx 的作用就是在 CSS 生成阶段把这些 rem 值统一换算成 px 值,让最终产出的样式表中不再出现 rem 单位。
在 SKILL.md 的预设清单中,它被归类为 Feature Presets(功能型预设),与 Preset Icons、Preset Typography、Preset Web Fonts、Preset Tagify 并列,主要面向特定场景的定制化需求,而非像 Wind3 / Wind4 那样的完整主预设。
从实现机制上看,它属于 UnoCSS 的 后处理(postprocess) 范畴:不是在源码提取阶段改写你的类名,而是在工具类已经生成 CSS 之后对产出做单位换算。这与 core-processors 中描述的处理器(processors)运行时机一致——处理器在 UnoCSS 生成 CSS 层之后、输出之前执行,接收某一层的 CSS 并返回替换后的内容。理解这一点有助于明白它为什么可以“影响所有含 rem 单位的 utilities”,同时也意味着它不改变你在 HTML / 模板中书写的类名,你仍然写 p-4、text-lg,只是生成的 CSS 变成了像素值。
安装与基础配置
presetRemToPx 随 unocss 主包一同导出,无需单独安装额外依赖。在项目根目录的 uno.config.ts(或 unocss.config.ts,UnoCSS 会自动识别,详见 core-config)中将其加入 presets 数组即可:
import { defineConfig, presetRemToPx, presetWind3 } from 'unocss'
export default defineConfig({
presets: [
presetWind3(),
presetRemToPx(),
],
})
配置要点:
- 必须与一个能产出
rem值的主预设搭配使用,例如presetWind3()或presetMini()。单独使用presetRemToPx没有任何意义,因为它本身不生成任何工具类。 - 顺序很重要:
presetRemToPx要放在生成rem值的预设之后,这与 preset-rem-to-px 文档“Order matters: place after the preset that generates rem values”的提示一致。预设的注册顺序会影响工具类匹配与最终产出,放反了可能导致转换不生效或行为异常。
工作原理:转换前与转换后的对比
预设的核心行为是把生成 CSS 中出现的所有 rem 数值按基准字号换算为 px。以间距工具类为例,文档给出了最直观的对照:
在 HTML 中书写:
<div class="p-4">
不启用该预设时,presetWind3 生成的 CSS 是:
.p-4 { padding: 1rem; }
启用 presetRemToPx 后,输出变为:
.p-4 { padding: 16px; }
默认基准字号(base font size)为 16,因此 1rem × 16 = 16px。这个换算作用于所有生成结果中携带 rem 单位的工具类,包括:
- 间距类:
p-*、m-*、gap-*、space-*等; - 尺寸类:
w-*、h-*、max-w-*、min-h-*等; - 排版类:
text-*(字号)、leading-*(行高)、tracking-*(字间距)等; - 其他以
rem表达的工具类属性。
同时需要注意:主题(theme)中的 rem 值也会被转换。UnoCSS 的主题是工具类取值的依据(见 core-theme),如果自定义主题里写了 spacing: { xl: '1.5rem' }、fontSize: { lg: '1.125rem' } 这类值,启用该预设后这些引用同样会被换算为 px,从而保证整份样式表单位一致。
典型适用场景
preset-rem-to-px 文档列举了四类最典型的使用场景:
- 需要像素级精确设计的项目(pixel-perfect):设计稿通常以像素标注,直接把
rem换算成px可以消除浏览器根字号设置带来的偏差,确保还原度; - rem 表现不佳的环境:当页面根元素字号不可控、或需要嵌入到字号基准未知的宿主页面时,
rem的继承特性反而成为隐患,用px更稳妥; - 与像素制设计系统保持一致:如果团队的设计令牌(design tokens)、组件库或既有样式体系全部基于
px,混用rem会增加维护成本,统一输出px更利于一致性; - 邮件模板(better compatibility):许多邮件客户端对
rem的支持不完善,甚至会忽略根字号设置,使用px能获得更好的跨客户端兼容性。
配置选项:baseFontSize
预设目前的核心选项是 baseFontSize,用于指定 1rem 换算成多少像素:
presetRemToPx({
// 基准字号,用于 rem → px 换算(默认值:16)
baseFontSize: 16,
})
自定义基准字号的示例:
presetRemToPx({
baseFontSize: 14, // 1rem = 14px
})
当你的设计体系以 14px 为根字号基准时(例如全局 html { font-size: 14px }),应当把 baseFontSize 同步设置为 14,这样 1rem 会换算为 14px,1.5rem 则为 21px,换算结果与页面实际渲染一致。默认值 16 对应浏览器标准根字号,适用于未显式修改根字号的项目。
与 preset-wind4 的配合:使用内建处理器
重点提示:使用 preset-wind4 时无需(也不应)再引入 presetRemToPx。 Wind4 预设内置了等价的 rem→px 处理能力,应改用其导出的 createRemToPxProcessor 处理器。这一点在 preset-rem-to-px 与 preset-wind4 两份文档中均有明确说明。
Wind4 的配置方式:
import { createRemToPxProcessor } from '@unocss/preset-wind4/utils'
export default defineConfig({
presets: [
presetWind4({
preflights: {
theme: {
// 对 theme 层(CSS 变量)中的 rem 值做换算
process: createRemToPxProcessor(),
}
},
}),
],
// 同时作用于工具类(utilities)的输出
postprocess: [createRemToPxProcessor()],
})
这里涉及 Wind4 与 Wind3 在架构上的差异:Wind4 会把主题值输出为 CSS 变量(--spacing: 0.25rem 等)并生成 theme、properties、base 等预置层(各层顺序见 core-layers 中 preset-wind4 的图层表)。因此要做完整的单位换算,需要两条路径同时处理:
preflights.theme.process:负责把主题预置层中 CSS 变量声明里的rem换算为px;postprocess:负责把生成的工具类规则里的rem换算为px。
在 Wind3 场景下,presetRemToPx 一个预设即可覆盖工具类与主题引用;在 Wind4 场景下,则要按上述两处分别挂载处理器。这也解释了为什么官方明确建议 Wind4 用户直接使用内建处理器而非 presetRemToPx。
使用注意事项
综合文档与仓库内相关参考,使用该预设时有以下几点需要留意:
1. 顺序要求
presetRemToPx 必须放置在生成 rem 值的主预设(如 presetWind3)之后。预设注册顺序错误可能导致换算不生效。
2. 作用范围是全局的
一旦启用,所有包含 rem 单位的工具类输出都会被换算,无法针对单个工具类豁免。如果项目中混用了必须保留 rem 的场景,需要提前评估影响面。
3. 主题中的 rem 同样被转换
自定义主题值(spacing、fontSize、borderRadius 等)中的 rem 会被一并换算,设计令牌的语义可能因此改变,配置时应对主题中的单位做一次全面核对。
4. 单位一致性
core-theme 文档在断点(breakpoints)一节也提醒过不要混用单位(例如 md: '40rem' 与 sm: '640px' 混用会导致断点排序异常,建议统一换算成 px)。这从侧面说明在配置层面保持单位一致是 UnoCSS 的最佳实践,presetRemToPx 恰好可以从输出侧帮你统一掉这一层差异。
5. 使用场景取舍
它适合像素制、邮件模板等场景;如果项目本身依赖 rem 的可访问性特性(随用户根字号缩放),则不建议启用,应保持默认的 rem 输出。
小结
presetRemToPx 是 UnoCSS 中一个“小而专”的功能型预设:它以 baseFontSize(默认 16)为基准,在 CSS 生成后把全部 rem 单位换算为 px,适用于像素级还原、邮件模板兼容和像素制设计体系统一等场景;在 Wind4 项目中则应改用 @unocss/preset-wind4/utils 导出的 createRemToPxProcessor,分别挂载到主题层处理器与 postprocess。使用时牢记“放在主预设之后、全局生效、主题值一并换算”三个要点,即可在保持类名书写习惯不变的前提下,获得完全像素化的样式输出。