在做大屏可视化项目时，屏幕适配往往是一个绕不开的话题。之前我开发了 Vue 版本的 vfit，收到了不少反馈。为了满足 React 社区的需求，官方的 React 版本 vfit-react 现已正式发布！

它是一个轻量级的缩放与定位解决方案，旨在用最简单的方式解决大屏适配问题。

🌟 核心特性

1. 全局自动缩放：通过 FitScaleProvider，它可以自动监听窗口或指定容器的变化，计算出全局的缩放比例。
2. 智能定位容器：内置的 FitContainer 组件不仅能继承全局缩放，还支持“像素级”和“百分比”两种定位模式。
3. 灵活的适配模式：支持按宽度适配、按高度适配，或者全自动模式（Auto），满足不同比例大屏的需求。

📦 安装

非常简单，一行命令搞定：

npm install vfit-react

🛠 使用指南

第一步：注入全局配置

在你的应用根节点（或大屏页面的根节点）使用 FitScaleProvider 包裹。你需要提供设计稿的尺寸，这样库才能算出正确的比例。

// App.tsx import React from 'react' import { FitScaleProvider } from 'vfit-react' const App = () => { return ( // 假设设计稿是 1920 x 1080 <FitScaleProvider options={{ designHeight: 1080, designWidth: 1920, scaleMode: 'auto' }}> <MyDashboard /> </FitScaleProvider> ) } export default App

第二步：使用智能容器布局

抛弃繁琐的 calc() 或手动计算 transform，直接使用 FitContainer。

它有两种核心模式：

1. 百分比单位 (unit="%")

• 适用于居中布局或相对位置。
• 特点：位置不会随缩放改变（始终在屏幕的相对位置），但内容会进行缩放。

2. 像素单位 (unit="px")

• 适用于精确布局。
• 特点：位置和大小都会乘以缩放比例。比如设置 left={100}，当屏幕放大 1.5 倍时，实际左边距就是 150px。

import React from 'react' import { FitContainer } from 'vfit-react' const MyDashboard = () => { return ( <div style={{ position: 'relative', width: '100vw', height: '100vh', overflow: 'hidden' }}> {/* 场景 A：绝对居中 (使用百分比) */} <FitContainer top={50} left={50} unit="%"> <div style={{ transform: 'translate(-50%, -50%)', border: '1px solid #ccc' }}> 我是居中的标题，无论屏幕多大我都居中 </div> </FitContainer> {/* 场景 B：左上角 Logo (使用像素) */} {/* 无论屏幕如何缩放，我距离左上角的视觉距离比例保持一致 */} <FitContainer top={20} left={20} unit="px"> <div style={{ width: 200, height: 60, background: 'blue' }}> Logo 区域 </div> </FitContainer> </div> ) }

第三步：进阶用法 (Hook)

如果你需要手动获取当前的缩放比例来做一些 canvas 绘图（如 ECharts 的 resize）或其他逻辑，可以使用 useFitScale。

import { useFitScale } from 'vfit-react' import { useEffect } from 'react' const ScaleDisplay = () => { const scale = useFitScale() useEffect(() => { console.log('当前屏幕缩放比例:', scale) }, [scale]) return <div>Current Scale: {scale}</div> }

📚 API 速查

FitScaleProvider Options

FitContainer Props