vue-auto-scale/README.md

vue大屏缩放组件

# vue-auto-scale

## 介绍

基于 Vue 3 的大屏适配缩放组件，按设计稿尺寸将内容整体缩放以适配不同视口。

## 环境与版本

| 说明 | 版本 |
|------|------|
| 当前包 | **Vue 3**（与仓库中 `vue` 版本一致） |
| TypeScript 类型 | 请使用 **1.x** |
| 仅 JavaScript、旧项目 | 可使用 **0.2.x** |

若仍在使用 **Vue 2.7 以下**，需自行安装 `@vue/composition-api`；**Vue 2.7+** 已内置组合式 API。

## 安装

```bash
npm i vue-auto-scale -S
```

```bash
yarn add vue-auto-scale
```

```bash
pnpm add vue-auto-scale
```

## 使用说明

**请将页面布局单位统一为 `px`（百分比等不受影响）。**

### 按需引入（推荐）

```vue
<template>
  <VueAutoScale
    :width="1920"
    :height="1080"
    :delay="100"
    :scale-type="scaleType"
    :reverse-scaling-ids="['#div2']"
    @change="scaleChange"
  >
    <div class="my-demo">
      <!-- 不需要随整体缩放的区域（如地图），也可用选择器指向内部节点 -->
      <div id="div2"></div>
    </div>
  </VueAutoScale>
</template>

<script setup lang="ts">
import { VueAutoScale } from 'vue-auto-scale'

const scaleType = 1

const scaleChange = (scale: number | string, scale1: number | string) => {
  console.log('当前缩放比例', scale)
  console.log('反向缩放比例（用于抵消子元素）', scale1)
}
</script>
```

### 全局注册

```ts
import { createApp } from 'vue'
import VueAutoScalePlugin from 'vue-auto-scale'
import App from './App.vue'

const app = createApp(App)
app.use(VueAutoScalePlugin)
app.mount('#app')
```

注册后可在任意模板中使用 `<vue-auto-scale>`（与按需引入时标签名一致，以构建结果为准）。

## 属性（Props）

以上参数均支持响应式更新。

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `width` | `number` | `1920` | 设计稿宽度（px） |
| `height` | `number` | `1080` | 设计稿高度（px） |
| `delay` | `number` | `100` | 窗口尺寸变化时防抖延迟（ms） |
| `scaleType` | `number` | `1` | 缩放策略，见下表 |
| `reverseScalingIds` | `string \| string[] \| null` | `null` | 不参与整体缩放的子节点，见下方说明 |
| `parent` | `boolean` | `false` | 为 `true` 时，按**父元素**尺寸计算缩放，而非整窗；并会监听父元素尺寸变化 |

### scaleType 取值

| 值 | 含义 |
|----|------|
| `1` | 强制铺满（宽、高分别缩放，可能拉伸） |
| `2` | 按比例缩放（取较小比例，内容不变形，可能留边） |
| `3` | 适应宽度 |
| `4` | 适应高度 |

### reverseScalingIds

内部通过 `document.querySelector` 查找节点，请传入 **合法的 CSS 选择器**（例如 `#id`、`.class`），不限于 id。可为单个字符串或字符串数组。

用于地图等需要保持「视觉像素」或需单独抵消 `scale` 的区域时，组件会对匹配元素设置宽高与 `transform`，以与外层缩放配合。

## 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `change` | `(scale, scale1)` | `scale` 为当前应用的缩放（类型 1 时可能为逗号分隔的 `x,y` 字符串）；`scale1` 为用于子元素反向补偿的缩放比例 |

## 仓库与反馈

- 主页：<https://gitee.com/strivelei/vue-auto-scale>  
若有其他需求或问题，欢迎在 Gitee 上提 Issue，后续会持续新增与优化。