bry-screen-adapter：响应式屏幕适配解决方案

简介

bry-screen-adapter 是一个用于前端项目的屏幕适配工具，通过 PostCSS 插件和运行时脚本结合的方式，实现基于设计稿尺寸的响应式布局适配。该工具支持多种适配模式，可根据不同设备屏幕尺寸自动调整元素大小，保持设计稿的比例和布局效果。

功能特点

• 灵活的适配模式：支持居中等比模式和平铺模式，满足不同场景的适配需求。
• 基于设计稿的尺寸转换：自动将 px 单位转换为 vw/vh 单位，并结合运行时缩放变量。
• 智能属性处理：根据属性类型（宽度、高度、内外边距等）自动选择合适的基准尺寸。
• 丰富的配置选项：可自定义设计稿尺寸、转换单位、精度等参数。
• 自动 HTML/Body 配置：生成基础布局样式，简化初始化工作。
• 媒体查询支持：可自动转换媒体查询中的像素值为视口单位。

安装与使用

安装

npm install bry-screen-adapter postcss --save-dev
# 或使用 yarn
yarn add bry-screen-adapter postcss -D

Vite 项目配置

在 Vite 项目中使用该插件，需在 vite.config.js 中进行配置：

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
    })
  ]
});

手动使用 PostCSS 插件

如果不使用 Vite，也可以在 PostCSS 配置中直接使用该插件：

// postcss.config.js
module.exports = {
  plugins: [
    require('bry-screen-adapter').postcss({
      // 配置选项与 Vite 插件相同
      designWidth: 1920,
      designHeight: 1080
    })
  ]
};

适配模式说明

居中等比模式（center）

• 保持设计稿的宽高比例，根据视口尺寸等比缩放。
• 当视口宽高比与设计稿不一致时，会在宽度或高度方向留有空白。
• 适用于需要严格保持设计比例的场景，如展示类页面。

平铺模式（tile）

• 不进行缩放，元素尺寸完全基于视口单位计算。
• 可能会导致元素变形，但能填满整个视口。
• 适用于对比例要求不高，需要完全填充屏幕的场景，如某些游戏界面。

运行时 API

插件会在窗口对象上暴露 bryScreenAdapter 对象，提供以下方法：

// 设置适配模式
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 插件部分

在构建阶段，PostCSS 插件会遍历 CSS 规则，将像素值转换为视口单位（如 vw/vh），并根据属性类型（宽度、高度、边距等）选择不同的基准尺寸（设计稿宽度或高度）。转换后的单位可以结合运行时缩放变量，实现动态调整。

运行时脚本部分

运行时脚本会根据设计稿的宽高比和视口尺寸计算缩放比例，存储在 CSS 变量中。当窗口大小或方向改变时，会重新计算缩放比例并更新变量，从而实现响应式适配。

示例

假设设计稿宽度为 1920px，高度为 1080px，以下 CSS 代码：

.container {
  width: 1200px;
  height: 600px;
  margin: 20px;
  padding: 10px 20px;
}

经过插件转换后，会变成：

.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