Adaptive Panel

⚡WASM Powered

💎Advanced

⭐Star

👑Pioneer

TuiAdaptive is one of the framework's core components, designed specifically for adaptive large-screen data visualization. Based on CSS3 transform: scale, it allows your page to maintain the design aspect ratio on any screen resolution, achieving "Develop once, adapt to full screen".

Furthermore, it addresses common pain points in large-screen development, such as GIS coordinate offsets, video wall ratio corrections, and asynchronous resource loading.

TuiAdaptive is currently the only free and unlimited component among the 7 advanced components.

Basic Usage

Use TuiAdaptive as the root element of the page to wrap all content.

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

Adaptive Modes

TuiAdaptive provides four core adaptive modes: Extension, Flexible, Fixed, and Stretch.

Configure via the adaptiveType prop.

Extension Mode

adaptiveType="extension"

Scenario: Workbench / Portal Homepage / Mobile / Long Pages

This is an adaptive mode based on fluid layout.

• Logic: Width scales proportionally to fit the screen, height is unrestricted (allows extension and scrolling).
• Applicability:
• Suitable for pages with uncertain content height, such as workbenches in management backends, corporate portal homepages, or mobile H5 pages.
• Not recommended for visualization dashboards that aim to "display all data on a single screen". Forcing a single screen's height to adapt to any range poses significant challenges for internal module layout adjustments.
• Exception: If your dashboard has too much data and the design explicitly allows using a scrollbar to show more data modules, this mode is the best choice.

Flexible Mode (Recommended for Single-Screen Data Apps)

adaptiveType="flexible"

Scenario: PC Browser Environment / Presentations / Compatible with Non-Fullscreen Display

This is the smartest and most commonly used adaptive mode (formerly called "Advanced Mode" in TechUI). It adapts intelligently between 16:9 (Fullscreen) and approx. 2:1 (Non-fullscreen) ratios.

• Solving Core Pain Points:

  • Perfectly solves the issue of displaying data screens on 1080P screens in non-fullscreen mode.
  • In non-fullscreen mode, the browser address bar, tabs, and system taskbar occupy about 100~150px of height, reducing the actual visible area to around 1920x930.
  • Using fixed mode in this case would result in black bars, whereas flexible mode allows the content to automatically adjust and fill the entire visible browser window.

• Logic:

  • Within the safe adaptation range (e.g., height between 930px ~ 1080px), content automatically fills the space without black bars.
  • Beyond the adaptation range (e.g., becoming extremely flat or tall), it falls back to the black-bar padding mode to ensure content is not severely distorted.

• Default Size Parameters:

  • width: No need to pass, defaults to 1920. Can be passed if the data screen is not 1080p, e.g., pass 3840 for 4K screens.
  • height: Dynamically calculated based on the ratio range, no need to pass value.

Development Requirement

When using this mode, each sub-module (chart container, etc.) within the data screen needs to have some vertical flexibility (responsiveness) to adapt to slight stretching or compression in height.

Fixed Mode

adaptiveType="fixed"

Scenario: Video Wall (Splicing Screen) / Strict Ratio Single-Screen Visualization

This is an adaptive mode based on a strict aspect ratio.

• Logic: Strictly locks the aspect ratio of the design draft for scaling.
• Applicability:
  • Video Walls: Designed for splicing screens with special ratios. For example, unconventional resolution combinations like 3x1 (5760x1080), 3x2 (5760x2160), 5x7, etc.
  • Standard Dashboards: Also commonly used for standard 1920x1080 data screens.

Note

When viewing on a standard 16:9 screen (e.g., 1080P/4K monitor), browser fullscreen (F11) must be enabled. If in non-fullscreen mode (with browser address bars, bookmark bars, system taskbars), black bars will appear on the top/bottom or left/right due to insufficient vertical visible area (less than 1080 pixels).

Stretch Mode

adaptiveType="stretch"

Scenario: Old Enterprise Video Wall Hardware Correction / Force Fill

This is a mandatory physical deformation correction mode. It ignores the original ratio and forces the content to stretch along the X or Y axis to fill the container.

• Logic: Forced filling, which changes the original view ratio (objects will appear flatter or thinner).

• General Use:

  • After a data screen is developed at 1080p, if it needs to fill the page in non-fullscreen mode without left/right black bars, this mode can be used for forced stretch correction.
  • Although theoretically supported, it is strongly discouraged for regular displays! Use Flexible mode instead.

• Special Use - Old Video Wall Correction:

  • Scenario: Facing some old splicing screens (e.g., 4x2 or 2x1), where the physical size is huge, but due to old matrix processors, the actual signal input resolution is still limited to 1920x1080.
  • Problem: When a standard 1080P signal is projected onto a screen that is physically "twice as wide", the image is horizontally stretched by the hardware by a factor of two, causing circles to become ellipses.
  • Correction: With this mode, set width=1920 during development. The component "pre-compresses" content that should be widescreen into a width of 1920 (looking squeezed on a PC). When the signal is projected onto the large screen and stretched by the hardware, it counteracts the deformation, simulating a normal high-definition widescreen visual effect.

Core Features

Smart Loading

Data screens often contain a large number of independent chart components. TuiAdaptive provides a counter-based overall loading mechanism to prevent the page from displaying components "piece by piece".

Working Principle: Set portletCount to the expected number of components. When sub-components integrated with TuiLoaderPanel (such as TuiEcharts) finish initializing, they automatically report their status. When the ready count meets the target, the Loading mask disappears automatically.

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

Without passing the portletCount parameter, you can also manually control the loading state via the loading parameter (Boolean).

Penetration Sync Container

Solving GIS/Map Interaction Pain Points

When using map components like Cesium or Leaflet, the parent container's transform: scale causes mouse click coordinates to drift. TuiAdaptive provides a special #penetration slot. The DOM inside this slot does not scale, but its size and position are completely synchronized with the main container, ensuring accurate interaction coordinates for GIS components.

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

View Control Mode

Great for Meeting Presentations

When monitorRatio is true, the component takes over the browser's zoom behavior (Ctrl + Scroll Wheel). The page is no longer just enlarged browser DOM elements, but becomes a canvas that can be Dragged (Pan) and Losslessly Zoomed, making it ideal for focusing on chart details during meetings.

Low Resolution Warning

Ensuring Optimal Visual Experience

TuiAdaptive has a built-in environment awareness feature. When the actual display resolution of the user's device is lower than the design resolution set in TuiAdaptive (width / height), a yellow warning bar (closable) automatically pops up at the bottom of the component.

• Function: Reminds the user or presenter that the current screen resolution is insufficient (e.g., previewing a 1080P dashboard on a 1366x768 laptop), which may lead to loss of UI details or blurriness, and is not a program bug.
• Control: This warning is mandatory and cannot be disabled via props (although it is a normal DOM element and can be hidden via CSS, this is not recommended).

Global Background Integration

Smart Background Layer Management

TechUI supports initializing a unified vector background (tui-view-bg) via global configuration. TuiAdaptive intelligently applies this background class to the appropriate DOM node based on the current configuration state:

• Default: The background class is applied to the adaptive scaling container, scaling with the content.
• When Penetration Container is Enabled: If you use the #penetration slot, the background class is automatically transferred to the penetration sync container.
• Advantage: This ensures that the global background (such as starry sky, grid, etc.) is always at the bottom layer and does not suffer from accidental deformation or layer occlusion due to the scaling of the main container, making it very suitable for complex scenes overlaying GIS maps.

For documentation on global backgrounds, please see the Infrastructure - Global Background chapter.

Global State Linkage

The TuiAdaptive component is not just a simple layout container; it synchronizes its running state to the global service $tState.adaptiveConfig in real-time. You can implement complex interaction logic by injecting $global and listening to these states in business components.

Lifecycle States ($adptReady / $adptInited)

• $adptReady: Indicates that the adaptive configuration has loaded.
• $adptInited: Indicates that the TuiAdaptive component has finished mounting and DOM size calculation is complete.
• Linkage Behavior: When $adptInited becomes true, it means the width, height, and scale ratio of the dashboard container are determined. Sub-components dependent on parent container size (such as Maps, Canvas) should listen to this state to execute initialization.

import { inject, watch } from 'vue';

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

watch($adptInited, (val) => {
  if (val) {
    initMap(); // Initialize map only after container dimensions are established
  }
});

Loading Counter ($gPortletCounter)

• Corresponding Prop: portletCount
• Linkage Behavior:
  • Target Setting: When you set :portletCount="5" on the component, this value is set as the target threshold for completion.
  • Auto Increment: Each TuiLoaderPanel (or chart component wrapping it) located inside TuiAdaptive will automatically call an internal mechanism to increment the global state $gPortletCounter by 1 upon initialization completion.
  • Completion State: When the real-time counter state $gPortletCounter accumulates to equal the portletCount setting, TuiAdaptive's Loading mask automatically closes.
  • Reset Counter: If multiple data screens share one TuiAdaptive component, when navigating between data screens, the overall loading process needs to be re-triggered. You must call the reset method resetAdaptiveConfig() to zero the counter; otherwise, the Loading mask will not show again because the counter has already met the target.
  • When the TuiAdaptive component is destroyed, the counter is also reset.

Resize Notification ($aResizeCounter)

• Linkage Behavior:
  • When the browser window size changes, or TuiAdaptive's adaptive mode changes, the component recalculates the scale ratio.
  • Upon completion, the value of $aResizeCounter automatically increments by +1.
  • ECharts Linkage: The system's internal TuiEcharts component automatically watches this state. Once changed, it immediately executes echartsInstance.resize(), ensuring chart content is not blurred or distorted, without the need for developers to manually listen to window.onresize.

View Control Tip (dragTip)

• Corresponding Prop: monitorRatio
• Linkage Behavior:
  • When View Control Mode is enabled (monitorRatio=true), the adaptiveConfig.dragTip state is activated.
  • This controls whether the "Hold Ctrl to scroll/zoom / Drag to move" operation tip is displayed on the interface.

API Reference

Props

Property Name	Type	Default	Description
width	Number	1900	Design draft width.
height	Number	1060	Design draft height.
adaptiveType	String	'extension'	Adaptive mode. Options: 'extension', 'flexible', 'fixed', 'stretch', 'disabled'.
portletCount	Number	0	Expected number of sub-components to load. Set to 0 to manually control loading.
loading	Boolean	true	(v-model) Loading state.
monitorRatio	Boolean	true	Whether to enable View Control Mode (take over browser zooming).
adaptiveInterval	Number	300	Debounce time for window change detection (ms).
shadow	Boolean	true	Whether to show container shadow.
userSelect	Boolean	false	Whether to allow text selection.
tipMute	Boolean	false	Whether to mute (hide) the low resolution warning bar.
spinnerConfig	Object	-	Loading style configuration.

Slots

Slot Name	Description
default	Default slot. Content scales with the container.
penetration	Penetration slot. Content does not scale, dedicated for GIS/Map components.

Events

Event Name	Description
resizeStart	Triggered when window size adjustment starts.
resizeEnd	Triggered when window size adjustment ends.
update:loading	Triggered when loading state changes.