@TechUI/Adaptive

English | 中文

English

Standalone Edition

@techui/adaptive is the standalone edition of TuiAdaptive.

It keeps the core adaptive capability only:

• four adaptive modes: extension, flexible, fixed, stretch
• headless DOM API via createAdaptive(...)
• Vue wrapper component via vue.js
• optional base stylesheet via dist/style.css
• WASM-powered calculation core

This package is intentionally lightweight and framework-agnostic.
It can be integrated into almost any component system or frontend stack, including Vue, React, Angular, native HTML pages, and custom internal frameworks.

Because it does not depend on the full TechUI runtime, it does not include:

• dependency injection / global state linkage
• sync-container and penetration container capabilities
• view-control mode
• loading coordination and richer adaptive experience helpers
• the broader ecosystem-level interaction support available in TechUI

If this standalone package feels useful, you will likely get a much better experience from the full TechUI component libraries.
All four TechUI component libraries include the full-featured TuiAdaptive with richer interaction, better supporting utilities, and many additional production-oriented components:

• @techui/base
• @techui/admin
• @techui/scifi
• @techui/prime

The full TechUI version is more complete, more integrated, and better suited for real dashboard and application delivery.

Features

• Headless Core: works in native HTML and framework projects
• Shared Entry: createAdaptive(...) is the common runtime entry
• Vue Wrapper: a thin Vue 3 wrapper built on the same core
• WASM Core: adaptive calculation is handled by the bundled WASM module
• Minimal CSS: only a small optional stylesheet is provided
• Low Coupling: no dependency on TechUI runtime utilities

Modes

• extension
  • Description: Width always follows the design width as the base. Scale is calculated from width, while height extends downward with the viewport. In one sentence: horizontal scaling stays uniform, while height remains adaptive. This is the most flow-layout-oriented mode in the package. It does not try to force everything into a single screen, but instead keeps horizontal proportion stable and lets the page continue growing vertically when needed.
  • Use Cases: Best for mobile pages, workbenches, portals, websites, and waterfall-like layouts where content height is uncertain and the page may naturally continue growing downward. It is also the best fit when scrolling is an expected part of the final experience.
• flexible
  • Description: Width stays fixed, while height and scale adjust dynamically inside the built-in flexible ratio range. In the current standalone edition, this mode adapts within an approximate ratio range of 1.7 - 2.0. That means width remains unchanged, while height adapts within that safe range. Modules inside the stage should also be able to adapt vertically to get the best result. This mode was designed to handle a practical desktop-browser problem: fullscreen windows and default windowed browser states usually do not share the exact same ratio, but they often fall inside a manageable range.
  • Use Cases: Best for data visualization dashboards, cockpits, and enterprise large-screen projects that are frequently viewed in a browser rather than on a fixed display controller. It is especially useful when you want both maximized mode and normal desktop window mode to look natural. It is not recommended for splicing-wall scenarios.
• fixed
  • Description: Width and height both remain locked to the design size, and only uniform scaling changes. For example, if the design size is 1920 x 1080, the stage will always keep that ratio when adapting. This mode is simple, predictable, and strict. It is the closest to “render the design draft as-is, then scale the whole thing proportionally.” The tradeoff is that it only matches a single target ratio well. In a standard 1080p scenario, it usually needs fullscreen browser display to perfectly fill the screen.
  • Use Cases: Suitable for data visualization, cockpit, and enterprise large-screen projects when the target display ratio is stable and known in advance. For splicing-wall scenarios, this mode is usually the recommended choice.
• stretch
  • Description: Based on fixed, this mode directly stretches the stage through independent scaleX and scaleY. Outside the original design ratio, the content will deform. In a small correction range, it can fix the issue of the content not fully filling the screen, but when the real ratio differs greatly from the design ratio, deformation becomes obvious and often severe. This is not a “smart” adaptive mode. It is a deliberate physical correction mode.
  • Use Cases: Generally not recommended except when you deliberately want to correct small “not fully filled” cases. However, it becomes very useful for some legacy large-screen systems. For example, some older 4 x 2 splicing walls still expose only 1920 x 1080 after being merged into a larger physical display. In that situation, the whole interface may be stretched horizontally to nearly double width, causing severe deformation: circles become obvious ellipses, while buttons, charts, and panels lose their intended proportions. In such cases, stretch can be used to actively correct the horizontal and vertical scaling relationship, making the final result visually closer to a 2K-like display effect.
• disabled
  • Description: Turns off adaptive scaling and renders the container in normal flow.
  • Use Cases: Useful for debugging, fallback rendering, or pages where adaptive behavior needs to be temporarily disabled.

Why The Full TechUI Edition Is Better

This standalone package focuses on the adaptive core itself. It is ideal when you want to reuse the scaling container in your own stack, but it intentionally stops at the infrastructure boundary.

The full TechUI edition of TuiAdaptive goes much further:

• Smart Loading Coordination: integrates with chart and portlet-style components, allowing the entire screen to enter and leave loading state in a coordinated way instead of revealing modules one by one.
• Penetration / Sync Container: provides a synchronized non-scaled container for GIS, map, and special rendering layers, solving pointer-offset issues caused by transform: scale.
• View Control Mode: supports browser-zoom takeover, drag, and lossless zooming for meeting demos and screen-detail presentations.
• Low Resolution Warning: detects when the current device resolution is lower than the design target and gives a clear runtime warning.
• Global Background Integration: can automatically cooperate with TechUI global background layers and place them on the correct adaptive container.

If you are building real dashboards, enterprise cockpits, GIS systems, or richer application shells, the full TechUI component libraries are the recommended choice.

Global State Linkage In The Full TechUI Edition

One of the biggest differences between this standalone package and the full TechUI version is global state linkage.

In TechUI, TuiAdaptive is not just a scaling container. It synchronizes its runtime state back into the global service layer, allowing other components to react automatically:

• Lifecycle State: child modules can wait for adaptive initialization before mounting maps, canvases, and size-sensitive charts.
• Loading Counters: components such as loader panels and charts can participate in a shared loading-completion workflow.
• Resize Notifications: adaptive recalculation can automatically trigger downstream resize reactions in other TechUI components.

This standalone package intentionally does not include those integrations, which keeps it lightweight and portable. But if you need ecosystem-level coordination, the full TechUI edition is where TuiAdaptive becomes much more powerful.

DOM API

import { createAdaptive } from '@techui/adaptive'
import '@techui/adaptive/style.css'

const adaptive = createAdaptive({
  target: '#app',
  width: 1920,
  height: 1080,
  mode: 'fixed',
})

Vue API

import TuiAdaptive from '@techui/adaptive/vue'
import '@techui/adaptive/style.css'

<TuiAdaptive :width="1920" :height="1080" mode="fixed">
  <div style="width:1920px; min-height:1080px;">...</div>
</TuiAdaptive>

Options

createAdaptive(...)

| Name | Type | Default | Description | | --- | --- | --- | --- | | target | String \| HTMLElement | null | Mount target | | width | Number | 1920 | Design width | | height | Number | 1080 | Design height | | mode | String | 'fixed' | Adaptive mode | | disabled | Boolean | false | Disable adaptive scaling | | observeResize | Boolean | true | Listen to resize changes | | debounce | Number | 0 | Debounce time in ms | | onChange | Function | null | Callback after recalculation |

Vue Wrapper Props

| Name | Type | Default | Description | | --- | --- | --- | --- | | width | Number | 1920 | Design width | | height | Number | 1080 | Design height | | mode | String | '' | Preferred mode | | disabled | Boolean | false | Disable adaptive scaling | | observeResize | Boolean | true | Listen to resize changes | | debounce | Number | 0 | Debounce time in ms | | className | String | '' | Extra class for the host element |

Package Files

• dist/index.js: standalone DOM/headless build entry
• dist/vue.js: Vue wrapper entry
• dist/style.css: optional base stylesheet
• core/core.js: runtime WASM loader
• core/core_bg.wasm: WASM calculation module
• test/index.html: standalone HTML test page
• test/vue: minimal Vue test project

Author

• aYin
• Email: [email protected]
• China Site: https://techui.cn/
• Global Site: https://techui.net/

中文

独立版说明

@techui/adaptive 是 TuiAdaptive 的独立版。

它只保留了核心自适应能力：

• 四种适配模式：extension、flexible、fixed、stretch
• 基于 createAdaptive(...) 的无头 DOM API
• 基于 vue.js 的 Vue 包装组件
• 可选引入的基础样式表 dist/style.css
• 基于 WASM 的自适应计算核心

这个包刻意保持轻量和低耦合。
它可以接入几乎任意组件库或前端框架体系，包括 Vue、React、Angular、原生 HTML 页面，以及各类内部定制框架。

由于它没有依赖完整的 TechUI 运行时体系，因此没有内置下面这些能力：

• 注入与全局状态联动
• 同步容器、穿透容器等高级容器机制
• 视图控制模式
• 整体加载协调与更友好的适配体验支持
• TechUI 生态中更完整的交互能力与辅助组件

如果您觉得这个独立版已经很好用，那么更推荐您进一步了解 TechUI 完整组件库。
TechUI 的四个组件库都内置了完整功能版 TuiAdaptive，不仅没有这些独立版的能力限制，还额外提供了大量围绕大屏、后台、GIS、数据可视化场景打磨过的体验型组件：

• @techui/base
• @techui/admin
• @techui/scifi
• @techui/prime

完整版本在体验、生态联动、工程落地能力上都会更强，更适合真实项目交付。

特性

• 无头核心：可用于原生 HTML，也可用于各类前端工程
• 统一入口：createAdaptive(...) 是共享运行时入口
• Vue 包装层：提供一层很薄的 Vue 3 包装组件
• WASM 核心：自适应计算由内置 WASM 模块完成
• 最小样式：仅提供一份可选基础样式
• 低耦合设计：不依赖 TechUI 运行时工具体系

模式说明

• extension
  • 说明：宽度始终按设计稿宽度作为基准，缩放比按宽度计算，高度向下延伸以充满视口。一句话概括就是：横向等比缩放，高度自适应延伸。它不会去压缩设计稿宽度，而是优先保证横向比例稳定，再让页面内容沿纵向自然增长。这是整个独立版里最偏向“流式页面”的模式，不追求把所有内容强行压进单屏，而是让纵向内容按照页面节奏自然展开。
  • 适用场景：适用于移动端、工作台、门户首页、网站页面，以及各种偏瀑布流、长页面、纵向内容持续增长的场景。如果滚动本来就是最终体验的一部分，这个模式通常是最自然的选择。
• flexible
  • 说明：宽度保持不变，在内置的弹性宽高比范围内动态调整高度与缩放。当前独立版中，这个模式会在大约 1.7 - 2.0 的比例范围内进行动态适配。也就是说，宽度保持不变，高度在安全范围内自适应，因此内部模块在这个高度区间内也应具备一定的自适应能力。它的核心目标，就是同时兼顾桌面浏览器的最大化模式与默认窗口模式，因为这两种状态下的实际比例通常并不完全一致，但又常常落在一个可控区间内。
  • 适用场景：适合数据可视化、驾驶舱、企业大屏等开发场景，尤其适合“主要运行在 PC 浏览器里”的单屏应用。它可以很好地兼容最大化与普通窗口两种常见桌面浏览状态。拼接屏场景通常不建议使用此模式。
• fixed
  • 说明：这个模式简单直接。比如设定了 1920 宽度、1080 高度，那么它会始终保持这个设计比例进行等比缩放自适应。也就是说，宽高都不变，只做整体等比缩放。它的优点是行为稳定、容易预期，也是最接近“设计稿长什么样，运行时就整体缩放成什么样”的模式；缺点是只适用于单一比例，因此在 1080p 这样的标准场景下，通常需要浏览器全屏展示，才能真正充满屏幕。
  • 适用场景：适合数据可视化、驾驶舱、企业大屏等开发场景。当目标显示设备比例明确、稳定，或者项目本身就是严格围绕某一设计比例开发时，这个模式通常最稳。对于拼接屏场景，通常建议优先使用此模式。
• stretch
  • 说明：这个模式是在 fixed 的基础上，直接通过 scaleX 与 scaleY 进行拉伸。也就是说，宽高仍然保持设计稿尺寸，但横向和纵向分别独立缩放。在非设计比例下，它会产生比例形变。若真实比例与设计比例差异较小，它可以修正内容未充满屏幕的问题；但若比例差异过大，就会产生明显甚至严重的形变，因此通常不建议作为常规模式长期使用。它不是“智能适配”模式，而是一个带有明确目的的“物理修正模式”。
  • 适用场景：通常仅用于修正内容无法充满屏幕的情况，一般不建议默认使用。但它有一个非常重要的特殊场景：某些老旧大屏，例如 4 x 2 的拼接屏，在合并展示后对外依然只暴露 1920 x 1080 的分辨率。此时整套内容往往会在物理屏幕上被横向拉伸到约 2 倍比例，导致画面严重变形，例如圆形会被横向拉伸成明显的椭圆，按钮、图表、面板也会失去原本的设计比例。此时可以借助 stretch 模式主动修正横纵向缩放关系，从而在视觉上模拟接近 2K 屏的显示效果。
• disabled
  • 说明：关闭自适应缩放，按普通流式容器渲染。
  • 适用场景：适合调试、回退渲染，或某些页面需要临时关闭适配能力的情况。

为什么更推荐 TechUI 完整版

这个独立包聚焦的是“自适应容器核心”本身，适合您在自己的技术体系里复用缩放容器能力，但它刻意停在了基础设施边界。

而 TechUI 完整版 TuiAdaptive 在此基础上继续向上扩展了很多真实项目里非常有价值的能力：

• 智能加载协调：可以与图表、面板类组件形成整体加载联动，避免页面一块一块地零散出现。
• 穿透 / 同步容器：为 GIS、地图、特殊渲染层提供不缩放但与主容器同步的位置和尺寸，解决 transform: scale 导致的点击坐标漂移问题。
• 视图控制模式：支持浏览器缩放接管、拖拽、无损缩放，非常适合会议演示与细节聚焦。
• 低分辨率提示：当当前设备分辨率低于设计稿目标时，能够给出明确提示，避免把环境问题误判成程序问题。
• 全局背景集成：能与 TechUI 的全局背景体系协同工作，把背景自动放到正确的自适应层级上。

如果您面对的是实际的大屏项目、企业驾驶舱、GIS 应用、数据可视化项目或者更完整的后台工作台，那么更推荐直接使用 TechUI 的完整组件库。

TechUI 完整版中的全局状态联动

这个独立包与 TechUI 完整版之间，最大的差异之一就是全局状态联动能力。

在 TechUI 中，TuiAdaptive 不只是一个缩放容器，它还会把运行时状态同步回全局服务层，供其他组件自动联动：

• 生命周期状态：子模块可以等待自适应初始化完成后，再去挂载地图、Canvas、图表等强依赖尺寸的模块。
• 加载计数器：TuiLoaderPanel、图表组件等可以共同参与统一的加载完成流程。
• 尺寸变更通知：当自适应重新计算后，其他 TechUI 组件可以自动收到尺寸变化联动，从而完成同步 resize。

这些能力在独立版中都被刻意拿掉了，因此它更轻、更通用，也更容易接入任意框架；但如果您需要的是生态级联动和完整体验，那么真正强大的形态仍然在 TechUI 完整版 TuiAdaptive 中。

DOM 用法

import { createAdaptive } from '@techui/adaptive'
import '@techui/adaptive/style.css'

const adaptive = createAdaptive({
  target: '#app',
  width: 1920,
  height: 1080,
  mode: 'fixed',
})

Vue 用法

import TuiAdaptive from '@techui/adaptive/vue'
import '@techui/adaptive/style.css'

<TuiAdaptive :width="1920" :height="1080" mode="fixed">
  <div style="width:1920px; min-height:1080px;">...</div>
</TuiAdaptive>

参数

createAdaptive(...)

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | target | String \| HTMLElement | null | 挂载目标 | | width | Number | 1920 | 设计稿宽度 | | height | Number | 1080 | 设计稿高度 | | mode | String | 'fixed' | 适配模式 | | disabled | Boolean | false | 是否关闭自适应 | | observeResize | Boolean | true | 是否监听尺寸变化 | | debounce | Number | 0 | 防抖时间，单位 ms | | onChange | Function | null | 每次重新计算后的回调 |

Vue 包装组件 Props

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | width | Number | 1920 | 设计稿宽度 | | height | Number | 1080 | 设计稿高度 | | mode | String | '' | 优先使用的模式参数 | | disabled | Boolean | false | 是否关闭自适应 | | observeResize | Boolean | true | 是否监听尺寸变化 | | debounce | Number | 0 | 防抖时间，单位 ms | | className | String | '' | 宿主额外类名 |

包内文件

• dist/index.js：独立版 DOM / 无头入口
• dist/vue.js：Vue 包装组件入口
• dist/style.css：可选基础样式
• core/core.js：运行时 WASM 加载器
• core/core_bg.wasm：WASM 计算模块
• test/index.html：独立版 HTML 测试页
• test/vue：最小 Vue 测试工程

作者

• aYin
• 邮箱：[email protected]
• 中国站：https://techui.cn/
• 全球站：https://techui.net/