postcss-mobile-forever

⚠️ Warning

使用本插件转换的 vw 单位，或是其它使用动态根元素 font-size 结合 rem 单位，这两种方法生成的伸缩视图，不能触发浏览器的缩放功能（可以通过快捷键同时按下 Cmd/Ctrl 和 +/- 触发），不能满足针对缩放的可访问性标准，因此存在可访问性问题。查看一个关于 vw 伸缩视图的可访问性实验。

不同设备上的界面一致，不等于用户体验一致，使用 vw（或 rem）做移动端适配，是一种粗暴的、技术先于设计的适配方法，是一条技术捷径，请考虑站在用户的角度、利用专业知识，使用响应式设计开发页面，使得用户在大尺寸设备上看到更丰富的内容，在小尺寸设备上看到更简洁的内容。

postcss-mobile-forever 是一款 PostCSS 插件，用于将固定尺寸转为伸缩尺寸，得到一个能够等比例缩放的视图。mobile-forever 可以配合 scale-view 使用，前者用于编译阶段，后者用于运行时。mobile-forever 有 3 种转换伸缩视图的模式，适用不同的场景：

• vw-mode，不限制最大宽度，跟随屏幕的宽窄变化，视图将等比放大或缩小，通过 px->vw 实现
• mq-mode，媒体查询 media-query 模式，限制最大宽度，区分桌面端与横屏两种宽度，产包较大，可访问性较优，不支持 At 规则中的样式转换，通过 @media 实现
• max-vw-mode，限制最大宽度，不区分桌面端、横屏，达到预设宽度后即停止伸缩，产包较小，可访问性较差，通过 min(vw, px) 实现

后面的“配置参数”一节将介绍如何激活这些模式。mobile-forever 默认会矫正 fixed 定位的元素（例如将宽屏右下角的“Top”按钮矫正回中央视图区域），并支持逻辑属性的转换。

移动端模版和范例

下面是一个移动端模版列表，这些模版使用了 mobile-forever 进行配置，在宽屏上展示良好，下面的每一项都包含了在线演示链接和模版源码，通过源码可以参考 mobile-forever 的配置方法：

• vue3-vant-mobile，一个基于 Vue 3 生态系统的移动 web 应用模板，帮助你快速完成业务开发。（代码/演示，自动矫正定位代码/演示）
• vue3-vant4-mobile，👋👋👋 基于Vue3.4、Vite5、Vant4、Pinia、Typescript、UnoCSS等主流技术开发，集成 Dark Mode（暗黑）模式和系统主题色，且持久化保存，集成 Mock 数据，包括登录/注册/找回/keep-alive/Axios/useEcharts/IconSvg 等其他扩展。你可以在此之上直接开发你的业务代码！（代码/演示）
• fantastic-mobile，一款自成一派的移动端 H5 框架，支持多款 UI 组件库，基于 Vue3。（代码/演示）

安装和迁移

npm 安装最新版本（基于 postcss@^8.0.0）（yarn 则是 yarn add -D postcss postcss-mobile-forever）：

npm install --save-dev postcss postcss-mobile-forever

npm 安装最新的兼容版本（基于 postcss@^6.0.0）（yarn 则是 yarn add -D postcss-mobile-forever@legacy）：

npm install postcss-mobile-forever@legacy --save-dev

查看兼容版本的 mobile-forever 文档，目前兼容版本不支持逻辑属性的处理。

如果项目原本是基于 rem 做的移动端适配，可以参考文档“迁移”，迁移到 vw 移动端适配。

配置参数

查看使用 postcss-mobile-forever 适配移动端视图的流程图（白色图片），以理解配置的过程和一些关键的配置选项。

一大波配置参数正在靠近，不必焦虑，尽在掌握，深入之前可以先尝试最基础的配置参数。下方是一个基础配置（max-vw-mode），表示了应用正在基于 750px 的宽度开发，经过 mobile-forever 转换后，浏览器中，应用视图将被限制在 600px 宽度以内进行等比例缩放，当宽度大于 600px，视图将不改变，并且根元素 #app 的应用视图始终处于浏览器窗口的中央区域：

{
  "viewportWidth": 750,
  "appSelector": "#app",
  "maxDisplayWidth": 600
}

下面的每一项都是可选的，设定 viewportWidth 后激活 vw-mode，设定 maxDisplayWidth 后激活 max-vw-mode，设定 enableMediaQuery 后激活 mq-mode。

下面是属性 customLengthProperty 的子属性，用于自定义变量，并且每一个属性都是可选的。customLengthProperty 有两个作用，一个是指定转换方式，例如基于根包含块的 left 和 right，则需要 customLengthProperty.rootContainingBlockList_LR 进行指定，来得到正确的转换结果，另一个作用是，在媒体查询模式下，避免所有和长度有关的使用 CSS 变量的属性，都被添加到媒体查询中，用于指定真正需要添加到桌面端或横屏的自定义变量：

也可以通过在样式文件中添加注释，来标记局部的尺寸该如何转换，下面是一些标记注释：

• /* apply-without-convert */，标记在一行属性之后，表示属性不经过转换，将直接添加到桌面端和横屏（可用于属性覆盖的情况）；
• /* root-containing-block */，标记在选择器上面，用于表示当前选择器的包含块是根元素，是浏览器窗口（如果选择器中已有“position: fixed;”，则无需标注该注释）；
• /* not-root-containing-block */，标记在选择器上面，用于表示当前选择器所属元素的包含块不是根元素；
• /* mobile-ignore-next */，标记在一行属性的上面，表示下一行属性不需要进行转换；
• /* mobile-ignore */，标记在一行属性后面，表示当前行属性不需要进行转换；
• /* vertical-writing-mode */，标记在选择器上面，表示当前选择器是纵向书写模式，内部的逻辑属性需要被转换。

单元测试与参与开发

npm install
npm run test

修改源码后，编写单元测试，验证是否输出了预期的结果。另外，在文件夹 example/ 内提供了一些范例，可以用来模拟生产环境使用插件的场景，这些范例项目中依赖的 postcss-mobile-forever 来自源码，因此当修改源码后，可以通过在范例里 npm i 安装依赖，然后本地运行，通过浏览器验证自己的修改是否符合预期。

如果您是移动端模版的开发者，成功引入 postcss-mobile-forever 之后，您可以按照“移动端模版和范例”一节的格式，提交 PR，将您的模版仓库以及在线演示地址添加到后续的列表中，这样可以为您的模版提供更多的曝光，也能够表示您的移动端模版具有良好的桌面端体验。

一起开发，让程序的变量命名更合适、性能和功能更好。

输入输出范例和原理

插件配置：

{
  "viewportWidth": 750,
  "maxDisplayWidth": 560,
  "appSelector": "#app"
}

输入范例：

#app {
  width: 100%;
}

.nav {
  position: fixed;
  width   : 100%;
  height  : 72px;
  left    : 0;
  top     : 0;
}

输出范例：

#app {
  width       : 100%;
  max-width   : 560px !important;
  margin-left : auto !important;
  margin-right: auto !important;
}

.nav {
  position: fixed;
  width   : min(100%, 560px);
  height  : min(9.6vw, 53.76px);
  left    : calc(50% - min(50%, 280px));
  top     : 0;
}

查看原理。

注意事项

appSelector 所在元素的居中属性会被占用，包括 margin-left、margin-right、max-width，如果开启了 border，box-shadow 会被占用。

默认情况，插件会把所有 fixed 定位的元素的包含块当成根元素，如果希望跳过处理非根元素的包含块，请在选择器上方添加注释，/* not-root-containing-block */，这样设置后，插件会知道这个选择器内的计算方式统一使用非根包含块的计算方式：

/* not-root-containing-block */
.class {
  position: fixed;
  left: 50%;
}

对于包含块，插件默认的处理方式不能处理下面列表中的情况，如果下面某个情况设置在某个祖先元素上，那么当前定位为 fixed 元素的包含块就是那个祖先元素，而插件默认所有的 fixed 元素的包含块是浏览器窗口（visual viewport）：

• transform 或 perspective 的值不是 none；
• will-change 的值是 transform 或 perspective；
• filter 的值不是 none 或 will-change 的值是 filter（只在 Firefox 下生效）；
• contain 的值是 paint（例如：contain: paint;）；
• backdrop-filter 的值不是 none（例如：backdrop-filter: blur(10px);）。

本插件媒体查询模式的目标是在不同尺寸的屏幕上展示合适的视图，在宽一点的屏幕上展示大一点的视图，在扁一点的屏幕上展示小一点的视图，在窄一些的屏幕展示移动端竖屏视图，而非准确地识别具体的设备或平台来应用对应视图。

使用插件转换后的浏览器兼容性情况：媒体查询模式下会利用 CSS 函数 calc()，因此兼容性略有降低，Opera Mini 完全不可用，max-vw-mode 利用了 CSS 函数 max()、min() 以及 calc()，会有兼容性问题，IE、Opera Mini、QQ 浏览器 13.1 完全不可用，具体可以查看 caniuse min(), max()、caniuse calc()。

期望效果

在不同设备上，duozhuayu.com（多抓鱼）公用一套 UI，访问无障碍，没有巨大字体和全宽的问题。

查看“多抓鱼“在移动端、移动端横屏和桌面端的展示效果。

多抓鱼官网用百分比单位做适配，最大宽度是 600px，小于这个宽度则向内挤压，大于这个宽度则居中移动端竖屏视图，这种小版心布局在不同尺寸屏幕的设备上，展示效果很好。这样的适配方法舍弃了对设计稿的“完美”还原，相应的，代码没有了预处理，更轻量了，没有了“完美”的限制，开发的过程也变得灵活，对于一种布局，有很多方式实现适配，而且，这样适配也能很好地触发浏览器的缩放功能，满足了针对缩放的可访问性标准。

CHANGELOG

查看更新日志。

版本规则

查看语义化版本 2.0.0。

协议

查看 MIT License。

支持与赞助

请随意 Issue、PR 和 Star，您也可以支付该项目，支付金额由您从该项目中获得的收益自行决定。

展开查看用于微信支付和支付宝支付的二维码。

微信支付	支付宝支付

其它

与本项目有关或者可以配合使用的项目：

• postcss-px-to-viewport，postcss 插件，用于将指定单位转为视口单位。
• postcss-px-to-clamp，postcss 插件，用于转换 px，并且限制最大和最小值。
• postcss-extract-media-query，postcss 插件，用于分离媒体查询。
• media-query-plugin，webpack 插件，用于分离媒体查询，可以配合其它 webpack 插件使用，例如 html-webpack-plugin、mini-css-extract-plugin。
• scale-view，运行时转换伸缩尺寸，可用于框架中的行内样式，查看 #17。

相关链接：

• Media Queries Level 3，W3C Recommendation，05 April 2022；
• CSS syntax validator，遵守 W3C 标准的在线 CSS 语法检测器；
• “What are CSS percentages?”，罗列了百分比取包含块（Containing Block）宽度的属性；
• CSS 的简写属性，罗列了所有的简写属性；
• Definition of "containing block"，W3C Recommendation；
• postcss-bud，一款 PostCSS 插件，用于保持视图横竖居中于屏幕；
• CSS3 Media Queries overview，一个网站，展示本机当前应用的媒体查询；
• “Don't target specific devices or sizes!”，一条答案，解释为什么不应该通过设备类型适配界面；
• Media Queries for Standard Devices，罗列了各种屏幕的媒体查询；
• 增强 vw/rem 移动端适配，一篇介绍增强 vw 的科普博文；
• 响应式设计，MDN 的响应式设计教程。