React 大屏可视化适配方案：vfit-react 发布 🚀

大家好，我是 一颗烂土豆。

在做大屏可视化项目时，屏幕适配往往是一个绕不开的话题。之前我开发了 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

属性	类型	默认值	描述
target	`string	HTMLElement`	document.body
designHeight	number	1080	设计稿高度
designWidth	number	1920	设计稿宽度
scaleMode	`'height'	'width'	'auto'`

FitContainer Props

属性	类型	默认值	描述
top, bottom	number	-	纵向位置
left, right	number	-	横向位置
unit	`'px'	'%'`	'px'
z	number	300	层级 (z-index)

---

🔗 链接

目前 vfit-react 已经发布到 npm，欢迎大家试用！

• NPM : www.npmjs.com/package/vfi...
• Vue 版本 : github.com/v-plugin/vf...

如果有任何问题或建议，欢迎在评论区留言或提交 Issue。Happy Coding! 🎉