Px To Scale 响应式布局插件

English | 中文

按屏幕宽度等比缩放的响应式布局方案：按设计稿用 px 写 CSS，指定范围内的元素随屏幕宽度整体缩放——就像以不同缩放级别查看设计稿。

提供两种协作方式，按项目（或按页面）选用：

• 浏览器运行时 —— 计算当前宽度比例，并在窗口尺寸变化时自动更新
• 构建期 PostCSS 插件 —— 在构建时把 px 值改写为缩放表达式

安装

npm install px-to-scale

CDN 快速体验（仅浏览器运行时）：

<script src="px-to-scale/lib/px-to-scale.umd.js"></script>
<script>
  PxToScale.initBasis(1920, 'c3')
</script>

快速开始（3 步）

1. 在入口文件初始化

import { initBasis } from 'px-to-scale'

// basis：设计稿宽度，如 1920
// name：自选的前缀名，如 'c3'
initBasis(1920, 'c3')

2. 在构建配置中添加 PostCSS 插件

// vite.config.js
import { pxToScalePlugin } from 'px-to-scale'

export default defineConfig({
  css: {
    postcss: {
      plugins: [pxToScalePlugin('c3')]
    }
  }
})

插件可用于任何接受 PostCSS 插件的构建链（Vite、webpack postcss-loader、Rollup 等）。

3. 在结构和样式里使用前缀类名

<!-- 带前缀类名的元素会缩放 -->
<div class="c3-container">
  <div class="c3-box">这个盒子随屏幕宽度缩放</div>
</div>

<!-- 其他元素不受影响 -->
<div class="normal-box">这个盒子保持原尺寸</div>

/* 按设计稿直接写 px */
.c3-box {
  width: 200px;    /* 1920px 宽屏显示 200px，960px 显示 100px，3840px 显示 400px */
  height: 100px;
  font-size: 16px; /* 文字也等比缩放 */
}

哪些内容会缩放

一条 CSS 规则处于范围内，当且仅当它的选择器之一带有前缀类名——.c3、.c3-任意、.c3_任意：

.c3-box { width: 200px }        /* 范围内 */
.c3-box .inner { width: 40px }  /* 范围内：选择器带有前缀类名 */
.other-box { width: 200px }     /* 范围外：保持固定 */

范围内规则里的每个 px 值都会变成缩放表达式，范围内的元素随屏幕宽度一起缩放。运行时缺席时，每个缩放表达式回退为原始 px 尺寸，页面不会因此坏掉。

列在 excludePxValues 里的值保持原尺寸。默认为 1px，因此发丝边框在任何屏宽下都保持清晰：

.c3-box {
  border: 1px solid #ccc;  /* 任何屏宽下都是 1px（默认排除） */
  width: 200px;            /* 会缩放 */
}

让 CSS 变量参与缩放

变量默认持有固定的 px。要让某个变量也缩放，把它列入 cssVarPxMap——在 :root / html 规则（或范围内规则）中以 px 声明它，它的所有使用处就会一起缩放：

:root {
  --card-width: 400px;
  --card-height: 300px;
}

.c3-card {
  width: var(--card-width);   /* --card-width 被映射后即随缩放 */
  height: var(--card-height);
}

pxToScalePlugin('c3', {
  cssVarPxMap: ['--card-width', '--card-height']
})

与普通值不同：被映射的变量不做 px 排除——映射本身就是明确的选入。

API 参考

Px To Scale —— 按屏幕宽度等比缩放的响应式布局插件。按设计稿写 px，指定范围内的元素随屏幕宽度缩放；浏览器运行时 + 构建期 PostCSS 插件；零依赖。npm 包随附 TypeScript 类型声明。

| API | 说明 | | --- | --- | | initBasis | 启动某个前缀名的浏览器运行时（推荐入口） | | computeBasis | 手动重新计算一次缩放比例 | | pxToScalePlugin | 构建期 PostCSS 插件 |

initBasis

const handle = initBasis(basis, name)

启动某个前缀名的浏览器运行时：计算当前宽度比例、窗口尺寸变化时自动更新，并把缩放变量级联到所有带前缀类名的元素（及其后代）。在应用启动、渲染之前调用一次即可。

同名重复调用共享同一运行时；每次调用最终都应调用 handle.destroy() 注销（最后一个注销时真正移除）。在非浏览器环境中调用会抛错。

| 参数 | 类型 | 说明 | | --- | --- | --- | | basis | number | 设计稿宽度（px），如 1920、375 | | name | string | 前缀名；必须与 pxToScalePlugin 传入的一致 | | 返回值 | object | 带 destroy() 方法的句柄 |

computeBasis

computeBasis(basis, name)

重新计算一次宽度比例并发布。通常无需调用——initBasis 已在窗口变化时自动更新。仅在需要手动控制重算时机时使用。

| 参数 | 类型 | 说明 | | --- | --- | --- | | basis | number | 设计稿宽度（px） | | name | string | 前缀名 |

pxToScalePlugin

pxToScalePlugin(name, options)

构建期 PostCSS 插件。把范围内规则中的 px 值改写为缩放表达式；配置了 cssVarPxMap 时改写被映射变量的定义。name 缺失或为空时在配置阶段即抛错。

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | name | string | — | 前缀名；必须与 initBasis 传入的一致 | | options.cssVarPxMap | string[] | [] | 需要随缩放的 CSS 变量（其 px 定义） | | options.excludePxValues | string[] | ['1px'] | 保持原尺寸的 px 值 | | options.excludeClasses | string[] | [] | 永不算作前缀类的类名 |

excludePxValues 的条目是 px 字符串（如 '1px'、'0.5px'）；按绝对数值匹配，因此 -1px 也被 '1px' 覆盖。

错误

错误用法会抛出指明问题的错误——不会静默失败：

| 情形 | 行为 | | --- | --- | | name 缺失或为空（插件或运行时） | 抛错 | | basis 不是正数（运行时） | 抛错 | | 在非浏览器环境调用浏览器运行时 | 抛错 |

注意事项与边界

• 一个名字，两端一致：传给 initBasis 与 pxToScalePlugin 的前缀名必须相同。
• 只看宽度：缩放跟随视口宽度，忽略高度比例。
• 按选择器文本划范围：后代元素缩放取决于其 CSS 规则的选择器是否带前缀类名——并不是「DOM 上嵌在带前缀元素里」就缩放。
• 精度：宽度比例以 3 位小数发布，尺寸与设计稿的差异至多 0.1%。
• 构建期插件覆盖所有规则：@media / @supports / @layer 块内选择器带前缀类名的规则同样会被改写。

文档

• 离线文档包：文档站首页的 "Download doc bundle" 按钮下载 px-to-scale-apis.zip（中英双语 README，含完整 API 参考）；npm 包随附两份 README

许可证

MIT