适配面板

⚡WASM 驱动

💎高级组件

⭐明星组件

👑首创

TuiAdaptive 是本框架的核心组件之一，专为大屏数据可视化的自适应而设计。它基于 CSS3 transform: scale实现，能够让您的页面在任意分辨率的屏幕上保持设计稿比例，实现“一次开发，全屏适配”。

此外，它还解决了大屏开发中常见的GIS 坐标偏移、拼接屏比例修正及资源加载不同步等痛点。

TuiAdaptive 是目前7个高级组件中目前唯一免费，无限制的组件。

基础用法

将 TuiAdaptive 作为页面的根元素，包裹所有内容。

<template>
  <TuiAdaptive 
    :width="1920" 
    adaptiveType="extension"
  >
  ...
  </TuiAdaptive>
</template>

适配模式

TuiAdaptive 提供了四种核心适配模式，分别是延伸模式、弹性模式、固定模式以及拉伸模式。

通过 adaptiveType 属性进行配置。

延伸模式 (extension)

adaptiveType="extension"

场景：工作台 / 门户首页 / 移动端 / 长页面

这是基于流式布局的适配模式。

• 逻辑: 宽度等比缩放以适应屏幕，高度不做限制（允许延伸和滚动）。
• 适用性:
  • 适用于内容高度不确定的页面，如各类管理后台的工作台、公司门户首页或移动端 H5 页面。
  • 不建议用于追求“单屏展示所有数据”的可视化大屏。因为如果强制要求单屏高度自适应任何范围，各个模块内部的布局调整将面临极大挑战。
  • 例外: 如果您的大屏数据过多，设计上明确允许通过滚动条来展示更多数据模块，那么此模式是最佳选择。

弹性模式 (flexible) - 开发单屏数据展示应用推荐模式

adaptiveType="flexible"

场景：PC 端浏览器环境 / 演示汇报 / 兼容非全屏展示

这是最智能、最常用的适配模式（旧版本TechUI称为“高级模式”）。它在 16:9 (全屏) 到 约 2:1 (非全屏) 的比例之间进行智能适配。

• 核心痛点解决:
  • 完美解决了数据屏在 1080P 屏幕上非全屏展示的问题。
  • 在非全屏模式下，浏览器地址栏、标签页和系统任务栏会占用约 100~150px 的高度，导致实际可视区约为 1920x930 左右。
  • 此时使用 fixed 模式会出现黑边，而 flexible 模式能让内容自动调整，占满整个浏览器可视窗口。
• 逻辑:
  • 在安全适配范围内（如高度在 930px ~ 1080px 之间），内容自动撑满，无黑边。
  • 超出适配范围（如变得极扁或极高），则回退到黑边填充模式以保证内容不严重变形。
• 默认尺寸参数:
  • width: 无需传入，默认为 1920。如果数据屏为非 1080p，也可以传入，如适配 4K 屏幕可传入 3840。
  • height: 根据比例动态计算区间范围，无需传入值。

开发要求

使用此模式时，数据屏内的每个子模块（图表容器等）需要具备一定的垂直弹性（自适应），以适应高度上的细微拉伸或压缩。

固定模式 (fixed)

adaptiveType="fixed"

场景：拼接大屏 / 严格比例的单屏可视化

这是基于严格宽高比的适配模式。

• 逻辑: 严格锁定设计稿的宽高比进行缩放。
• 适用性:
  • 拼接屏: 专为特殊比例的拼接屏设计。例如 3x1 (5760x1080)、3x2 (5760x2160)、5x7 等非常规分辨率组合。
  • 标准大屏: 也常用于 1920x1080 的标准数据屏。

注意事项

在标准 16:9 屏幕（如 1080P/4K 显示器）上查看时，必须开启浏览器全屏 (F11)。 如果在非全屏模式下（存在浏览器地址栏、书签栏、系统任务栏），由于垂直可视区域不足 1080 像素，屏幕上下或左右会出现黑边。

拉伸模式 (stretch)

adaptiveType="stretch"

场景：老旧企业拼接屏硬件修正 / 强制铺满

这是一种强制性的物理变形修正模式。它会无视原始比例，强制将内容在 X 轴或 Y 轴方向拉伸以填满容器。

• 逻辑: 强制填充，会改变原始视图比例（物体会变扁或变瘦）。
• 一般用途:
  • 数据屏以 1080p 开发完毕后，需要在非全屏模式下占满页面不出现左右黑边，也可以用此模式进行强制拉伸修正。
  • 虽然理论上支持，但强烈不推荐用于常规展示！建议使用弹性模式。
• 特殊用途 - 老旧大屏修正:
  • 场景: 面对一些老旧的拼接大屏（如 4x2 或 2x1 拼接），其物理尺寸巨大，但受限于旧的矩阵处理器，实际信号输入分辨率仍被限制在 1920x1080。
  • 问题: 当标准的 1080P 信号投射到物理上是“两倍宽”的屏幕时，画面会被硬件横向拉伸两倍，导致圆变成椭圆。
  • 修正: 通过此模式，开发时设置 width=1920，组件会将原本应为宽屏的内容“预先压缩”到 1920 的宽度中（PC 上看是扁的）。当信号投射到大屏并被硬件拉伸后，正好抵消变形，从而模拟出高清宽屏的正常视觉效果。

核心特性

智能加载 (Smart Loading)

大屏通常包含大量独立的图表组件。TuiAdaptive 提供了基于计数器的整体加载机制，避免页面“东一块西一块”地陆续显示。

工作原理: 设定 portletCount 为预期的组件数量。当内部集成了 TuiLoaderPanel 的子组件（如 TuiEcharts）初始化完成后，会自动汇报状态。当就绪数量达标时，Loading 遮罩自动消失。

<TuiAdaptive :portletCount="5"> ... </TuiAdaptive>

在不传入 portletCount 参数的情况下，也可以通过 loading 参数 (Boolean) 直接手动控制加载状态。

穿透同步容器 (Penetration)

解决 GIS/地图交互痛点

在使用 Cesium, Leaflet 等地图组件时，父容器的 transform: scale 会导致鼠标点击坐标漂移。 TuiAdaptive 提供了一个特殊的 #penetration 插槽。该插槽内的 DOM 不进行缩放，但尺寸与位置与主容器完全同步，从而保证 GIS 组件的交互坐标准确无误。

<template #penetration>
  <div id="cesiumContainer"></div>
</template>

视图控制模式 (View Control)

会议演示利器

当 monitorRatio 为 true 时，组件会接管浏览器的缩放行为（Ctrl + 滚轮）。页面不再是浏览器原来的 DOM 元素放大，而是变成一个可拖拽 (Pan)、可无损缩放 (Zoom) 的画布，非常适合在会议中聚焦查看图表细节。

低分辨率提示 (Low Resolution Warning)

保障最佳视觉体验

TuiAdaptive 内置了环境感知功能。当用户设备的实际显示分辨率低于您在 TuiAdaptive 中设定的设计稿分辨率（width / height）时，适配面板组件底部会自动弹出一个黄色的提示条（可关闭）。

• 作用: 提醒用户或演示者，当前屏幕分辨率不足（例如在 1366x768 的笔记本上预览 1080P 大屏），可能会导致 UI 细节丢失或模糊，并非程序 Bug。
• 控制: 此提示为强制提示，不可关闭（当然，它是一个普通的Dom，可以通过CSS代码进行隐藏，不建议）。

全局背景集成 (Global Background)

智能背景层级管理

TechUI 支持通过全局配置初始化统一的矢量背景（tui-view-bg）。TuiAdaptive 会根据当前的配置状态，智能地将这个背景类应用到合适的 DOM 节点上：

• 默认情况: 背景类应用于自适应缩放容器上，随内容一起缩放。
• 开启穿透容器时: 如果您使用了 #penetration 插槽，背景类会自动转移到穿透同步容器上。
  • 优势: 这确保了全局背景（如星空、网格等）始终位于最底层，且不会因为主容器的缩放而产生意外的变形或层级遮挡，非常适合叠加 GIS 地图等复杂场景。

关于全局背景文档说明，请查看 基础支撑-全局背景 章节

全局状态联动

TuiAdaptive 组件不仅仅是一个单纯的布局容器，它会实时将自身的运行状态同步到全局服务 $tState.adaptiveConfig 中。您可以通过注入 $global 并在业务组件中监听这些状态，来实现更复杂的交互逻辑。

生命周期状态 ($adptReady / $adptInited)

• $adptReady: 表示自适应配置已加载。
• $adptInited: 表示 TuiAdaptive 组件已完成挂载，且 DOM 尺寸计算完毕。
  • 联动行为: 当 $adptInited 变为 true 时，意味着大屏容器的宽、高、缩放比例 (scale) 均已确定。依赖于父容器尺寸的子组件（如地图、Canvas）应监听此状态来执行初始化。

import { inject, watch } from 'vue';

const { $adptInited } = inject('$global');

watch($adptInited, (val) => {
  if (val) {
    initMap(); // 确保容器尺寸确立后再初始化地图
  }
});

加载计数器 ($gPortletCounter)

• 对应 Prop: portletCount
• 联动行为:
  • 目标设定: 当您在组件上设置 :portletCount="5" 时，此数值被设定为加载完成的目标阈值。
  • 自动递增: 每个位于 TuiAdaptive 内部的 TuiLoaderPanel (或封装了它的图表组件) 初始化完成后，会自动调用内部机制使全局状态 $gPortletCounter 加 1。
  • 完成状态: 当实时计数状态 $gPortletCounter 累加至等于 portletCount 传入的设定值时，TuiAdaptive 的 Loading 遮罩会自动关闭。
  • 重置计数: 若多个数据屏公用一个TuiAdaptive组件，数据屏之间做导航切换的时候，需重新触发整体加载流程，必须调用重置方法resetAdaptiveConfig()将计数器归零，否则因计数器已达标，Loading 遮罩将不会再次显示。
  • TuiAdaptive组件销毁的时候，计数器也会被重置。

尺寸变更通知 ($aResizeCounter)

• 联动行为:
  • 当浏览器窗口大小发生变化，或者 TuiAdaptive 的适配模式发生变更时，组件会重新计算缩放比例。
  • 计算完成后，$aResizeCounter 的值会自动自增 +1。
  • ECharts 联动: 系统内部的 TuiEcharts 组件会自动监听此状态，一旦变化，立即执行 echartsInstance.resize()，确保图表内容不模糊、不变形，无需开发者手动监听 window.onresize。

视图控制提示 (dragTip)

• 对应 Prop: monitorRatio
• 联动行为:
  • 当开启视图控制模式（monitorRatio=true）时，adaptiveConfig.dragTip 状态会被激活。
  • 这会控制界面上是否显示“按住 Ctrl 滚动缩放 / 拖拽移动”的操作提示。

API 参考

Props

属性名	类型	默认值	说明
width	Number	1900	设计稿宽度。
height	Number	1060	设计稿高度。
adaptiveType	String	'extension'	适配模式。可选：'extension', 'flexible', 'fixed', 'stretch', 'disabled'。
portletCount	Number	0	预期加载的子组件数量。设为 0 则需手动控制 loading。
loading	Boolean	true	(v-model) 加载状态。
monitorRatio	Boolean	true	是否开启视图控制模式（接管浏览器缩放）。
adaptiveInterval	Number	300	窗口变化检测防抖时间 (ms)。
shadow	Boolean	true	是否显示容器阴影。
userSelect	Boolean	false	是否允许选中文字。
tipMute	Boolean	false	是否静音（隐藏）低分辨率提示条。
spinnerConfig	Object	-	Loading 样式配置。

Slots

插槽名	说明
default	默认插槽。内容会随容器缩放。
penetration	穿透插槽。内容不缩放，专用于 GIS/Map 组件。

Events

事件名	说明
resizeStart	窗口尺寸变化开始调整时触发。
resizeEnd	窗口尺寸变化调整结束时触发。
update:loading	加载状态变更时触发。