@screen-fit/screen-fit-core

screen-fit 的框架无关核心：大屏可视化分辨率适配引擎。

零依赖，只用 DOM 标准 API，可在任何前端环境（原生 / Vue / React / Svelte / Solid / Angular）使用。

安装

pnpm add @screen-fit/screen-fit-core

快速开始

import { ScreenAdapter } from '@screen-fit/screen-fit-core';

const adapter = new ScreenAdapter({
  container: '#screen',
  designWidth: 1920,
  designHeight: 1080,
  mode: 'contain',
  onResize(info) {
    document.documentElement.dataset.layout =
      info.isUltraWide ? 'ultra' : info.isNarrow ? 'narrow' : 'normal';
  },
});

HTML：

<div class="screen-bg"></div>
<div id="screen"></div>

核心概念

分层适配

┌─────────────────────────────────────┐
│ ① 背景层 (fixed, inset:0, cover)     │ ← 铺满视口
├─────────────────────────────────────┤
│ ② 内容层 (1920×1080, transform scale)│ ← 等比缩放，居中
├─────────────────────────────────────┤
│ ③ 装饰层 (fixed, 贴边元素)            │ ← 跟随视口
└─────────────────────────────────────┘

transform: scale 原理

scale   = min(vw / 1920, vh / 1080)
offsetX = (vw - 1920 * scale) / 2
offsetY = (vh - 1080 * scale) / 2

优势：业务按设计稿写 px 零换算；ECharts 不变形；只改 transform 不触发 reflow。

API

new ScreenAdapter(options)

| 选项 | 类型 | 默认 | 说明 | |---|---|---|---| | container | HTMLElement \| string | 必填 | 目标容器 | | designWidth | number | 1920 | 设计稿宽 | | designHeight | number | 1080 | 设计稿高 | | mode | AdaptMode | 'contain' | 缩放模式 | | minScale | number | 0 | 缩放下限 | | maxScale | number | Infinity | 缩放上限 | | autoResize | boolean | true | 自动监听 | | rotateOnPortrait | boolean | false | 竖屏旋转 | | observeTarget | HTMLElement | documentElement | ResizeObserver 目标 | | onResize | (info) => void | - | 变化回调 |

AdaptMode

| mode | 效果 | |---|---| | contain | 完整显示，可能留边（默认） | | cover | 铺满视口，可能裁切 | | fill | 铺满但可能变形 | | width | 按宽度撑满 | | height | 按高度撑满 |

实例方法

| 方法 | 说明 | |---|---| | on(fn) | 订阅变化，立即回调一次，返回取消函数 | | refresh() | 强制重新计算 | | getInfo() | 获取当前适配信息 | | clientToDesign(x, y) | 视口坐标 → 设计稿坐标 | | designToClient(x, y) | 设计稿坐标 → 视口坐标 | | destroy() | 销毁 |

设计约束

1. 不引入任何框架依赖
2. 不使用 will-change / translate3d / backface-visibility
3. 新增监听必须在 destroy() 中清理
4. update() 必须处理零尺寸
5. on() 注册时必须立即同步回调一次
6. 零运行时依赖

License

MIT