迁移指南

English · 简体中文

从任何一种「px 换算成视口单位」的方案迁移，步骤都一样：先让输出对齐，再逐步启用新能力。按概念对照，不必逐个配置项去找同名替代。

第一步：只换等价物

先不引入任何新特性，让新旧产物尽可能接近：

adaptiveMatrix({
  profiles: {
    app: {
      designWidth: 375,     // 原来的视口基准宽度
      query: false,         // 不生成媒体查询外壳
    },
  },
  precision: 5,             // 原来的小数位数
  strategy: 'viewport',     // 输出纯 vw，与旧方案同形
  libraries: false,         // 组件库适配也先关掉
})

strategy: 'viewport' 输出不带边界的 vw，此模式不需要填写流体边界。只有一个 profile 时也会自动选为默认。这个配置是迁移起点，不保证与旧插件逐字节一致：需要对照原产物核对属性过滤、忽略值、细线处理和舍入。例如默认 hairline: 1 会保留 1px 边框；只有旧构建确实需要缩放细线时，才设置 hairline: 0。

第二步：概念对照

你原来配置的东西	这里的位置
设计稿宽度 / 视口基准宽度	profile 的 `designWidth`
小数位数	`precision`
输出单位	`unit`，或某个 profile 的 `unit`
属性白/黑名单	`propList`（支持 `*` 与 `!`）
选择器黑名单	`selectorExclude`
属性值黑名单	`valueExclude`
最小转换像素值	`minPixelValue`
文件包含/排除	`include` / `exclude`，额外支持函数
保留原声明作为回退	`preserveOriginal: true`
根容器选择器	`root.selector`
桌面端最大展示宽度	`fluid.maxWidth` + `rootMaxWidth`
忽略注释	`adaptive-ignore` / `adaptive-ignore-next` / `adaptive-ignore-rule`

迁移期间，已有的 /* px-to-viewport-ignore(-next) */ 与 /* mobile-ignore(-next) */ 指令会继续生效，并与原生注释一样保留在产物里以保证二次编译，无需增加任何兼容配置。旧 postcss-pxtorem 依赖大写单位跳过的写法（如 1PX）不会在这里被当作忽略信号，因为 CSS 单位本就不区分大小写；请改用明确注释。

检查已有数学表达式

转换结果并不与所有旧插件逐字节兼容。在使用 375px 画布和纯视口输出的本地对比中，postcss-px-to-viewport@1.1.1 会把 min(24px, 50vw) 转成 min(6.4vw, 50vw)，本项目则保留原值。Adaptive Matrix 会保护已包含视口/容器单位的边界表达式，避免预编译产物再次转换。迁移时应检查已有的 min() / max() / clamp()：如果其中的像素项必须缩放，请明确写出预期的流体表达式。大写输入单位在这里也会转换，不要依赖 PX 作为忽略标记。

区分布局决策

横屏不是全局开关。 新建一个 landscape profile 并给它明确的媒体查询，横屏就拥有自己的设计宽度和缩放区间，而不是从竖屏推算出来的比例。

桌面宽度不是设计宽度。 如果 PC 只是把移动版居中展示，那它没有自己的设计稿，用 app profile 加 rootMaxWidth 即可。如果 PC 有独立设计稿，就给它独立的 designWidth，把差异写进 @adaptive pc。这两件事以前常被同一个配置项表达，在这里是两种不同的结构。

第三步：逐项启用

确认视觉一致后，按顺序打开：

移除 strategy: 'viewport' 恢复默认策略。只有设计需要时才添加 fluid 边界：{ maxWidth: 480 } 限制上界，{ minWidth: 320 } 限制下界，同时提供两者才输出 clamp()。不设边界仍然无界缩放，切换策略本身不会自动补出范围；文字也会恢复默认的 rem/视口混合公式；
移除 query: false，或改用 appPcPreset 引入 PC profile；
删掉 libraries: false，组件库按各自画布适配（详见组件库适配）。这一步通常可以顺带删掉原方案里为组件库写的整段忽略名单；
需要居中列时配置 root，fixedContainingBlock 会一并处理固定定位元素。

验收

保存旧产物作为视觉基线；
覆盖 320、375、480、768、1024、1440、1920；
检查 fixed/sticky、弹窗、第三方组件和输入法；
执行 200% 浏览器缩放与键盘导航测试——文字混合公式的收益正是在这里体现，也只有真实测试能验证。

迁移指南 ​

第一步：只换等价物 ​

第二步：概念对照 ​

检查已有数学表达式 ​

区分布局决策 ​

第三步：逐项启用 ​

验收 ​