A powerful screen adaptation plugin for Vite and PostCSS
npm install bry-screen-adapterbry-screen-adapter 是一个用于前端项目的屏幕适配工具，通过 PostCSS 插件和运行时脚本结合的方式，实现基于设计稿尺寸的响应式布局适配。该工具支持多种适配模式，可根据不同设备屏幕尺寸自动调整元素大小，保持设计稿的比例和布局效果。
- 灵活的适配模式：支持居中等比模式和平铺模式，满足不同场景的适配需求。
- 基于设计稿的尺寸转换：自动将 px 单位转换为 vw/vh 单位，并结合运行时缩放变量。
- 智能属性处理：根据属性类型（宽度、高度、内外边距等）自动选择合适的基准尺寸。
- 丰富的配置选项：可自定义设计稿尺寸、转换单位、精度等参数。
- 自动 HTML/Body 配置：生成基础布局样式，简化初始化工作。
- 媒体查询支持：可自动转换媒体查询中的像素值为视口单位。
``bash`
npm install bry-screen-adapter postcss --save-dev或使用 yarn
yarn add bry-screen-adapter postcss -D
在 Vite 项目中使用该插件，需在 vite.config.js 中进行配置：
`javascript
import { defineConfig } from 'vite';
import bryScreenAdapter from 'bry-screen-adapter';
export default defineConfig({
plugins: [
bryScreenAdapter({
designWidth: 1920, // 设计稿宽度，默认 1920
designHeight: 1080, // 设计稿高度，默认 1080
defaultMode: 'center', // 默认适配模式，'center' 或 'tile'
unit: 'vw', // 转换后的单位，默认 'vw'
precision: 6, // 转换精度，默认 6
exclude: null, // 排除文件路径
include: null, // 包含文件路径
selectorBlackList: [], // 选择器黑名单
propertiesBlackList: [], // 属性黑名单
mediaQuery: false, // 是否转换媒体查询，默认 false
minPixelValue: 0, // 最小像素值，小于该值不转换
useRuntimeScaling: true, // 是否使用运行时缩放，默认 true
htmlBackgroundColor: '#0078fd', // HTML 背景色，默认 '#0078fd'
autoSetBodySize: true, // 自动设置 Body 尺寸，默认 true
enableHtmlFlex: true // 启用 HTML Flex 布局，默认 true
})
]
});
`
如果不使用 Vite，也可以在 PostCSS 配置中直接使用该插件：
`javascript`
// postcss.config.js
module.exports = {
plugins: [
require('bry-screen-adapter').postcss({
// 配置选项与 Vite 插件相同
designWidth: 1920,
designHeight: 1080
})
]
};
- 保持设计稿的宽高比例，根据视口尺寸等比缩放。
- 当视口宽高比与设计稿不一致时，会在宽度或高度方向留有空白。
- 适用于需要严格保持设计比例的场景，如展示类页面。
- 不进行缩放，元素尺寸完全基于视口单位计算。
- 可能会导致元素变形，但能填满整个视口。
- 适用于对比例要求不高，需要完全填充屏幕的场景，如某些游戏界面。
插件会在窗口对象上暴露 bryScreenAdapter 对象，提供以下方法：
`javascript
// 设置适配模式
window.bryScreenAdapter.setMode('center'); // 返回布尔值，表示设置是否成功
// 获取当前适配模式
const currentMode = window.bryScreenAdapter.getMode();
// 获取当前缩放比例
const scale = window.bryScreenAdapter.getScale();
/* 返回对象：
{
width: 缩放比例（宽度方向）,
height: 缩放比例（高度方向）
}
*/
`
| 选项名称 | 类型 | 默认值 | 说明 |
|---------------------|----------------------|-------------|--------------------------------------------------------------|
| designWidth | number | 1920 | 设计稿宽度 |
| designHeight | number | 1080 | 设计稿高度 |
| unit | string | 'vw' | 转换后的目标单位，支持 'vw'、'vh' 等视口单位 |
| precision | number | 6 | 转换精度，保留的小数位数 |
| exclude | string/array/regex | null | 排除转换的文件路径 |
| include | string/array/regex | null | 仅转换包含的文件路径 |
| selectorBlackList | array | [] | 选择器黑名单，包含这些选择器的规则不会被转换 |
| propertiesBlackList | array | [] | 属性黑名单，这些属性不会被转换 |
| mediaQuery | boolean | false | 是否转换媒体查询中的像素值 |
| minPixelValue | number | 0 | 小于该值的像素不会被转换 |
| useRuntimeScaling | boolean | true | 是否使用运行时缩放变量 |
| htmlBackgroundColor | string | '#0078fd' | HTML 元素的背景色 |
| autoSetBodySize | boolean | true | 是否自动设置 Body 尺寸 |
| enableHtmlFlex | boolean | true | 是否启用 HTML 的 Flex 布局 |
| defaultMode | string | 'center' | 默认适配模式，'center' 或 'tile' |
该工具的实现原理主要分为两部分：
在构建阶段，PostCSS 插件会遍历 CSS 规则，将像素值转换为视口单位（如 vw/vh），并根据属性类型（宽度、高度、边距等）选择不同的基准尺寸（设计稿宽度或高度）。转换后的单位可以结合运行时缩放变量，实现动态调整。
运行时脚本会根据设计稿的宽高比和视口尺寸计算缩放比例，存储在 CSS 变量中。当窗口大小或方向改变时，会重新计算缩放比例并更新变量，从而实现响应式适配。
假设设计稿宽度为 1920px，高度为 1080px，以下 CSS 代码：
`css`
.container {
width: 1200px;
height: 600px;
margin: 20px;
padding: 10px 20px;
}
经过插件转换后，会变成：
`css`
.container {
width: calc(62.5vw * var(--bry-width-scale));
height: calc(55.555556vh * var(--bry-height-scale));
margin: calc(1.851852vh * var(--bry-height-scale));
padding: calc(0.925926vh var(--bry-height-scale)) calc(1.041667vw var(--bry-width-scale));
}
当视口尺寸变化时，运行时脚本会更新 --bry-width-scale 和 --bry-height-scale 变量，从而实现元素尺寸的动态调整。
- 该插件适用于前端项目的开发阶段，生产环境中可以根据需要决定是否保留运行时脚本。
- 对于使用动态生成的样式（如 JavaScript 中设置的样式），需要手动调用 bryScreenAdapter.getScale() 获取缩放比例并应用。selectorBlackList
- 若遇到某些元素不需要适配的情况，可以将其选择器添加到 中。propertiesBlackList` 中。
- 对于不希望转换的属性，可添加到
- 媒体查询转换功能可能会影响部分响应式设计，使用时需谨慎测试。
MIT