一款 PostCSS 插件,用于将基于特定宽度的固定尺寸的视图转为可跟随宽度变化而等比例伸缩的视图,这种伸缩视图常见于移动端页面。postcss-mobile-forever 可以配合 scale-view 使用,前者用于编译阶段,后者用于运行阶段。postcss-mobile-forever 具备以下特性:
转换用于伸缩视图的视口单位(px->vw);
提供两种方法限制伸缩视图的最大宽度,
生成适应桌面端和横屏的媒体查询(@media),
或是利用 CSS 函数限制视口单位最大值(min(vw, px));
矫正 fixed 定位的元素,支持逻辑属性的转换。
使用媒体查询限制最大宽度的方法,能够为桌面端与横屏各自设置最大宽度。
如果您在使用 postcss-px-to-viewport 实现伸缩界面的时候,不希望界面在大屏设备上撑满整个屏幕而难以浏览,希望界面在达到某一个合适的宽度后停止伸缩(限制最大宽度),您可以使用本插件。
安装
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 文档,目前兼容版本不支持逻辑属性的处理。
安装之后在 postcss.config.js 配置文件中引入,或者其它框架配置文件中引入。
配置参数
一大波配置参数正在靠近,不必焦虑,尽在掌握,在这之前可以先尝试最基础的配置参数。下方是一个基础配置,表示了应用正在基于 750px 的宽度开发,经过 mobile-forever 转换后,浏览器中,应用视图将被限制在 600px 宽度以内进行等比例伸缩,当宽度大于 600px,视图将不改变:
{
"viewportWidth": 750,
"appSelector": "#app",
"maxDisplayWidth": 600
}
下面的每一项都是可选的。
Name Type Default Desc
viewportWidth number|(file: string, selector: string) => number 750 应用基于该宽度进行开发,转换后的伸缩视图将会以该宽度的视图作为标准进行比例伸缩;可以传递函数动态生成宽度,例如 file => file.includes("vant") ? 375 : 750 表示在名称包含“vant”的文件内使用 375px 的宽度,而其他文件使用 750px 的宽度
mobileUnit string "vw" 移动端竖屏视口视图,转换成什么视口单位?
maxDisplayWidth number / 限制视口单位的最大宽度
enableMediaQuery boolean false 打开媒体查询模式,打开后将自动关闭 maxDisplayWidth
desktopWidth number 600 适配到桌面端时,展示的视图宽度
landscapeWidth number 425 适配到移动端横屏时,展示的视图宽度
appSelector string / 页面最外层选择器,例如“#app”,用于设置在桌面端和移动端横屏时的居中样式
appContainingBlock "calc"|"manual"|"auto" "calc" 该属性和矫正 fixed 定位元素有关,manual 将不矫正;calc 将通过插件主动计算的方式矫正元素尺寸;auto 将通过 transform: translateZ(0) 强制设置根包含块为 appSelector,从而自动矫正元素,并且此时需要设置属性 necessarySelectorWhenAuto
necessarySelectorWhenAuto string / 当 appContainingBlock 设为 auto 时,需要指定该属性,该属性指定了 appSelector 往内一层的元素选择器,查看一个关于指定元素作为包含块的实验以了解如何使用该属性
border boolean|string false 在页面外层展示边框吗,用于分辨居中的小版心布局和背景,可以设置颜色字符串
disableDesktop boolean false 打开则不做桌面端适配,使用该参数前需要打开 enableMediaQuery
disableLandscape boolean false 打开则不做移动端横屏适配,使用该参数前需要打开 enableMediaQuery
disableMobile boolean false 打开则不做移动端竖屏适配,把 px 转换为视口单位,如 vw
exclude RegExp|RegExp[] / 排除文件或文件夹
include RegExp|RegExp[] / 包括文件或文件夹
unitPrecision number 3 单位精确到小数点后几位?
propList string[] [''] 哪些属性要替换,哪些属性忽略?用法参考 postcss-px-to-viewport 文档
selectorBlackList (string|RegExp)[] [] 选择器黑名单,名单上的不转换
propertyBlackList propertyBlackList [] 属性黑名单,名单上的不转换,如果要指定选择器内的属性,用对象的键表示选择器名称,具体用法见 vant 的范例代码
valueBlackList (string|RegExp)[] [] 属性值黑名单,名单上的值不转换
rootContainingBlockSelectorList (string|RegExp)[] [] 包含块是根元素的选择器列表,效果和标注注释 / root-containing-block / 相同
verticalWritingSelectorList (string|RegExp)[] [] 纵向书写模式的选择器列表,效果和在选择器顶部标注注释 / vertical-writing-mode */ 相同
minDesktopDisplayWidth number / 宽度断点,如果不提供这个值,默认使用 desktopWidth 的值,视图大于这个宽度,则页面宽度是桌面端宽度 desktopWidth,“原理和输入输出范例”一节具体介绍了该值的触发情况
maxLandscapeDisplayHeight number 640 高度断点,视图小于这个高度,并满足一定条件,则页面使用移动端横屏宽度,“原理和输入输出范例”一节具体介绍了该值的触发情况
side any / 侧边配置,在桌面端媒体查询中生效,用于利用宽屏的空间,后文将介绍它的若干子属性
comment any / 自定义注释,改变注释的名称,后文将介绍它的若干子属性
customLengthProperty any / 用于指定需要添加到桌面端或横屏的自定义变量(css 变量,var(...)),如果不指定,默认所有和长度有关的属性,如果使用了自定义变量,都会被添加入桌面端和横屏,后文将介绍它的若干子属性
experimental.extract boolean false 提取桌面端与横屏样式代码,用于生产环境,用于代码分割优化产包,具体查看“注意事项”一节
experimental.minDisplayWidth number / 限制最小宽度,和 maxDisplayWidth 搭配使用
下面是属性 customLengthProperty 的子属性,用于自定义变量,并且每一个属性都是可选的。customLengthProperty 有两个作用,一个是指定转换方式,例如基于根包含块的 left 和 right,则需要 customLengthProperty.rootContainingBlockList_LR 进行指定,来得到正确的转换结果,另一个作用是,在媒体查询模式下,避免所有和长度有关的使用 CSS 变量的属性,都被添加到媒体查询中,用于指定真正需要添加到桌面端或横屏的自定义变量:
Name Type Default Desc
rootContainingBlockList_LR string[] [] 用于根包含块的,left、right 的自定义属性,例如设置 ["--len-a", "--len-b"] 后,--len-a 和 --len-b 的值会转换为用于 left 和 right 属性,并且包含块是根包含块的值,并添加到桌面端和横屏中
rootContainingBlockList_NOT_LR string[] [] 用于根包含块的,非 left、right 的自定义属性
ancestorContainingBlockList string[] [] 用于非根包含块的自定义属性,这些属性值不会被转换,但是会添加到桌面端和横屏,用于避免优先级问题
disableAutoApply boolean false 关闭自定义属性自动添加到桌面端和横屏,设置上面的三个选项后,这个选项自动为 true
还有一些属性可以把页面上某个部分在宽屏设备上转移到侧边,例如可以把在移动端底部的二维码转移到桌面端的侧边栏区域以利用空白区域,这些属性不常用,您可以展开查看具体属性情况。
也可以通过在样式文件中添加注释,来标记局部的尺寸该如何转换,下面是一些标记注释:
/ apply-without-convert /,标记在一行属性之后,表示属性不经过转换,将直接添加到桌面端和横屏(可用于属性覆盖的情况);
/ root-containing-block /,标记在选择器上面,用于表示当前选择器的包含块是根元素,是浏览器窗口(如果选择器中已有“position: fixed;”,则无需标注该注释);
/ not-root-containing-block /,标记在选择器上面,用于表示当前选择器所属元素的包含块不是根元素;
/ mobile-ignore-next /,标记在一行属性的上面,表示下一行属性不需要进行转换;
/ mobile-ignore /,标记在一行属性后面,表示当前行属性不需要进行转换;
/ vertical-writing-mode /,标记在选择器上面,表示当前选择器是纵向书写模式,内部的逻辑属性需要被转换。
标记注释的名称可以通过属性自定义,这些属性不常用,您可以展开查看属性的具体说明。
虽然配置选项的数量看起来很多,但是只需要指定选项 viewportWidth 后,就可以输出伸缩视图的结果,通常我们还需要让伸缩视图具有最大宽度,只要再添加 appSelector 和 maxDisplayWidth,即可完成。开发中,如果在浏览器看到了宽屏的视图有和在移动端视图不一样的地方,再考虑配置其它选项也不迟。
展开查看默认的配置参数。
具体使用
1.npm install --save-dev postcss postcss-mobile-forever
2.vite.config文件中添加
import viewport from 'postcss-mobile-forever'
import autoprefixer from 'autoprefixer'
//defineConfig 中添加以下配置
css: {
postcss: {
plugins: [
autoprefixer(),
viewport({
rootSelector: '.H5-view', //你需要的页面
viewportWidth: 750, // ui开发尺寸
maxDisplayWidth: undefined,
border: false,
disableMobile: false,
disableDesktop: false,
disableLandscape: false,
// desktopWidth: 1200,
// exclude: [/pc/],
}),
],
},
},
3.page.json中添加
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"postcss"
]
}
},