bry-auto-adapt/README.md

智能屏幕适配插件，自动将CSS中的px单位转换为vw/vh

# bry-auto-adapt：响应式屏幕适配解决方案

## 简介

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

## 功能特点

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

## 安装与使用

### 安装

```bash
npm install bry-auto-adapt postcss --save-dev
# 或使用 yarn
yarn add bry-auto-adapt postcss -D
```

### Vite 项目配置

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

```javascript
import { defineConfig } from 'vite';
import bryScreenAdapter from 'bry-auto-adapt';

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 配置中直接使用该插件：

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

## 适配模式说明

### 居中等比模式（center）

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

### 平铺模式（tile）

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

## 运行时 API

插件会在窗口对象上暴露 `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 插件部分

在构建阶段，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