3D柱图

⚡WASM 驱动

💎高级组件

⭐明星组件

👑首创

TuiBar3D 是一个具备高逼真材质感的 3D 可视化图表组件，它使用动态SVG技术构建。

不同于普通的伪 3D 图表，Bar3D 模拟了半透明玻璃外壳与内部液体填充的物理效果。它利用 CSS3 高级特性构建，无需引入沉重的 WebGL 引擎，即可实现带有透视景深、光影折射和动态液位的可视化效果。

TuiBar3D 是组件库中7个高级组件之一，需要取得授权后使用。

核心特性

• 双重形态: 支持 圆柱体 (Cylinder) 和 方柱体 (Cube) 两种几何形态。
• 液位模拟: 柱体内部呈现液体填充效果，液面高度随数据变化，并伴随光影浮动。
• 智能阈值: 支持配置多级阈值（Thresholds），根据数值自动切换柱体颜色状态（如：危险、警告、正常、成功）。
• 场景组件: 可选配置 底座 (Base) 和 背部轨道 (Track)，增强空间定位感。
• 队列动画: 配合 TuiBar3DGroup 可实现多组数据的延时序列播放。

基础用法

Bar3D 是一个高度自适应的组件，它的高度完全由父容器决定。

<template>
  <div style="height: 300px; width: 100px;">
    <TuiBar3D 
      label="今日访问"
      :value="75"
      :maxValue="100"
      unit="人次"
      shape="cylinder" 
    />
  </div>
</template>

进阶功能

阈值与状态 (Thresholds & Status)

组件支持根据数值自动变更颜色状态。

• 手动状态: 通过 status 属性强制指定 (normal, success, warning, danger, critical, emphasis)。
• 自动阈值: 通过 thresholds 对象配置。当 value 达到设定值时，自动应用对应的状态颜色。

const myThresholds = {
  danger: 0,    // 0-59 显示红色 (danger)
  warning: 60,  // 60-79 显示橙色 (warning)
  success: 80   // >=80 显示绿色 (success)
}

<TuiBar3D :value="85" :thresholds="myThresholds" />

3D 场景配置

通过调整视距和辅助组件来增强立体感。

• viewDeep: 视距深度。值越大，透视角度越夸张（俯视感越强）；值越小越接近平面。
• showBase: 显示底部基座。
• showTrack: 显示背部半透明轨道。
• gap: 柱体与其背部轨道的间距，增加此值可增强悬浮感。

队列展示 (Group)

使用辅助组件 TuiBar3DGroup 可以快速渲染一组柱图，并自动处理交错入场动画（延时播放）。

<template>
  <div style="height: 300px; display: flex;">
    <TuiBar3DGroup 
      :items="[
        { label: 'A区', value: 45 },
        { label: 'B区', value: 80 },
        { label: 'C区', value: 30 }
      ]"
      :progress3DBarConfig="{
         shape: 'cube',
         showBase: true,
         aniDelay: 500 // 统一配置动画延迟
      }" 
    />
  </div>
</template>

API 参考

Props

数据配置

属性名	类型	默认值	说明
label	String	Required	底部显示的标题标签。
value	Number	0	当前数值。
maxValue	Number	null	最大值（用于计算液位高度百分比）。若不填则默认为 100。
unit	String	''	数值单位。
precision	Number	0	数值显示精度（保留小数位数）。
displayValue	String	'auto'	数值显示模式：'auto'(自动), 'none'(不显示), 'all'(显示值/最大值), 'allReverse'(显示值/最大值并换行)。
mainValuePosition	String	'auto'	主数值显示位置。'auto'(液面跟随), 'top'(顶部固定)。

外观形态

属性名	类型	默认值	说明
shape	String	'cylinder'	柱体形状。可选：'cylinder' (圆柱), 'cube' (方柱)。
status	String	null	强制状态颜色：'normal','success', 'danger', 'warning', 'emphasis', 'critical'。
thresholds	Object	null	阈值配置对象。键名为状态名，键值为触发阈值。
barColor	String	null	自定义柱体颜色（接受 CSS 颜色值）。
barColorRatio	Number	15	柱体渐变差值系数（控制立体光影强弱）。
barBlur	Number	0.7	柱体模糊度（磨砂玻璃感）。
barOpacity	Number	0.9	柱体透明度。

3D 场景与辅助

属性名	类型	默认值	说明
viewDeep	Number	15	3D 视距深度 (0-50)。
showTrack	Boolean	true	是否显示背部轨道。
trackOpacity	Number	0.5	轨道透明度。
gap	Number	30	柱体与轨道的间距。
showBase	Boolean	false	是否显示底座。
baseSpacing	Number	20	底座边距尺寸。
baseColorWeakened	Boolean	false	是否弱化底座颜色。

动画与控制

属性名	类型	默认值	说明
duration	Number	1000	动画持续时间 (ms)。
aniDelay	Number	2000	入场动画延迟 (ms)。
resizeObserver	String	'global'	尺寸监听策略：'self', 'global', 'none'。
initHold	Boolean	false	初始化是否保持静止（不播放动画）。

Events

事件名	说明
inited	组件初始化且入场动画完成时触发。

Expose

属性名	类型	说明
inited	Boolean	当前组件是否已完成初始化。

视觉定制

Bar3D 的视觉效果由一组精细的 SVG 渐变变量控制。组件内部将柱体、底座、轨道拆分为多个受光面，并分别为其分配了不同的 CSS 变量，以模拟真实的光照关系。

您可以覆盖以下变量来调整各个部分的颜色：

柱体 (Bar)

柱体是视觉主体，其颜色由状态 (status) 或阈值 (thresholds) 自动决定，但其光影层次由以下变量控制：

• --tui-bar3d-bargrad-A: 高光面颜色。通常用于柱体受光最强的一侧或顶面。
• --tui-bar3d-bargrad-B: 中间色/过渡色。用于柱体的主体过渡区域或立方体的侧面 A。
• --tui-bar3d-bargrad-C: 背光面颜色。用于柱体的阴影侧或立方体的侧面 B。
• --tui-bar3d-shinegrad-A / B: 玻璃高光色。用于模拟外壳的高光反射（通常为半透明白色）。

底座 (Base)

当 showBase 开启时，底座的颜色由以下变量控制。

• 正常状态:
  • --tui-bar3d-basgrad-A: 底座受光面。
  • --tui-bar3d-basgrad-B: 底座背光/过渡面。
• 弱化状态 (is-weakened):
  • 当开启 baseColorWeakened 时，底座会强制使用轨道 (Track) 的颜色变量，从而在视觉上退居次要地位，突出数据柱体。

轨道 (Track)

当 showTrack 开启时，背部半透明轨道的颜色。

• --tui-bar3d-trkgrad-A: 轨道受光面。
• --tui-bar3d-trkgrad-B: 轨道背光面。

渐变映射逻辑 (以 Cube 为例)

为了让方柱体具有立体感，组件使用了“双面着色”策略：

• 侧面 A (cubeSA): 映射到 bargrad-B -> bargrad-A 的渐变（明暗过渡）。
• 侧面 B (cubeSB): 映射到 bargrad-B -> bargrad-C 的渐变（中性到暗部）。

这种差异化的映射确保了即使是单色数据，也能呈现出清晰的棱角分明感。