@rsbuild/plugin-rem

Rem 插件实现移动端页面的 rem 自适应布局，能够根据屏幕大小来动态调整字体大小，让网页在不同大小的屏幕上都能够自适应显示。

插件提供以下能力：

• 集成 postcss-pxtorem，将 CSS 中的 px 单位转换为 rem。
• 在 HTML 模版中插入运行时代码，对根元素 fontSize 进行设置。

Usage

安装：

1npm add @rsbuild/plugin-rem -D

在 rsbuild.config.ts 中注册:

1// rsbuild.config.ts
2import { pluginRem } from "@rsbuild/plugin-rem";
3
4export default {
5  plugins: [pluginRem()],
6};

选项

默认选项

1const defaultOptions = {
2  enableRuntime: true,
3  rootFontSize: 50,
4  screenWidth: 375,
5  rootFontSize: 50,
6  maxRootFontSize: 64,
7  widthQueryKey: "",
8  excludeEntries: [],
9  supportLandscape: false,
10  useRootFontSizeBeyondMax: false,
11  pxtorem: {
12    rootValue: 50,
13    unitPrecision: 5,
14    propList: ["*"],
15  },
16};

介绍

名称	类型	默认值	描述
enableRuntime	boolean	true	是否自动生成 runtime 代码来动态计算根元素字体大小
inlineRuntime	boolean	true	是否将 runtime 代码内联到 HTML 文件中。如果设置为 false，运行时代码会被抽取为一个独立的 convert-rem.[version].js 文件，并输出到产物目录下
rootFontSize	number	50	根元素字体值
maxRootFontSize	number	64	最大根元素字体值
widthQueryKey	string	''	根据 widthQueryKey 的值去 url query 中取 client width
screenWidth	number	375	UI 设计图宽度
excludeEntries	string[]	[]	设置不注入 runtime 代码的页面入口，通常需要配合 pxtorem.exclude 使用
supportLandscape	boolean	false	横屏时使用 height 计算 rem
useRootFontSizeBeyondMax	boolean	false	超过 maxRootFontSize 时，是否使用 rootFontSize
pxtorem	object	rootValue。默认与 rootFontSize 相同 unitPrecision: 5。精确位数 propList: ['*']。支持转换的 CSS 属性	postcss-pxtorem 插件属性

示例

1pluginRem({
2  rootFontSize: 30,
3  excludeEntries: ["404", "page2"],
4  pxtorem: {
5    propList: ["font-size"],
6  },
7});

使用指南

CSS 属性值转换

由于默认的 rootFontSize 为 50。开启 rem 转换后，会按照 1rem = 50px 的比例，对 CSS 样式做如下转换：

1/* input */
2h1 {
3  margin: 0 0 16px;
4  font-size: 32px;
5  line-height: 1.2;
6  letter-spacing: 1px;
7}
8
9/* output */
10h1 {
11  margin: 0 0 0.32rem;
12  font-size: 0.64rem;
13  line-height: 1.2;
14  letter-spacing: 0.02rem;
15}

Rsbuild 默认会对所有 CSS 属性进行转换，如果希望仅对 font-size 属性进行转换，可通过设置 pxtorem.propList 实现。

1pluginRem({
2  pxtorem: {
3    propList: ["font-size"],
4  },
5});

如何实现一些 CSS 属性不被转换为 REM？

pxtorem.propList 除了可以指定哪些属性需要被转换外，可以通过 ! 方式指定哪些元素不被转换：

1pluginRem({
2  pxtorem: {
3    propList: ["*", "!border-width"], // 不转换 border-width 属性
4  },
5});

如果只希望一些个别 CSS 属性不被转换为 REM 时，也可参考如下写法：

1/* `px` 转换为 `rem` */
2.convert {
3  font-size: 16px; // 转换为 1rem
4}
5
6/* `Px` 或 `PX` 会被 `postcss-pxtorem` 忽略，但是可以被浏览器正常识别 */
7.ignore {
8  border: 1px solid; // 忽略
9  border-width: 2px; // 忽略
10}

更多信息可参考 postcss-pxtorem。

根元素字体大小计算

页面根元素的字体大小的计算公式为：

根元素字体大小 = 当前客户端屏幕宽度  * 根元素字体值 / UI 设计图宽度

(即：pageRootFontSize = clientWidth * rootFontSize / screenWidth)

以屏幕宽度为 390 的手机端浏览器为例，根元素字体值的默认值为 50， UI 设计图宽度为 375。

此时计算出的页面根元素的字体大小为 52 (390 * 50 / 375)。 此时 1 rem 为 52px，CSS 样式中的 32px（0.64 rem），实际页面效果为 33.28 px。

1pluginRem({
2  rootFontSize: 50,
3  screenWidth: 375,
4});

设置根元素字体最大值

在桌面浏览器端，根据计算公式得到的页面根元素字体值往往过大，当计算出的结果超出了默认的最大根元素字体值时，则采用当前设置的最大根元素字体值为当前根元素字体值。

以屏幕宽度为 1920 的桌面浏览器为例，此时计算出的根元素的字体大小为 349，超出了最大根元素字体值 64。则采用 64 为当前的根元素字体值。

1pluginRem({
2  maxRootFontSize: 64,
3});

如何获取页面实际生效的 rootFontSize 值？

页面实际生效的 rootFontSize 会根据当前页面的情况动态计算。你可以通过打印 document.documentElement.style.fontSize 查看，也可通过 window.ROOT_FONT_SIZE 获取。

如何指定页面实际生效的 rootFontSize 值？

默认情况下，页面实际生效的 rootFontSize 会根据当前页面的情况动态计算，如果希望指定页面实际生效的 rootFontSize，可关闭 enableRuntime 配置，并在自定义 HTML 模版 中自行注入 document.documentElement.style.fontSize = '64px'。

1export default {
2  html: {
3    template: "./static/index.html",
4  },
5  plugins: [
6    pluginRem({
7      enableRuntime: false,
8    }),
9  ],
10};

如何判断 REM 是否生效？

1. CSS：查看生成的 .css 文件中对应属性的值是否从 px 转换成 rem。
2. HTML：打开页面控制台查看 document.documentElement.style.fontSize 是否存在有效值。

License

MIT.