TechUI Docs

简中

EN

简中

EN

主题

3D面板 ​

⚡WASM 驱动
💎高级组件
⭐明星组件
👑首创

T3DPanel 是一个极具视觉冲击力的容器组件，它利用 CSS3 perspective 和 transform 属性，为内部内容赋予真实的 3D 景深、厚度和动态透视效果。

它内置了多种交互模型，能够根据光标位置、设备倾角或预设动画自动计算 3D 变换，非常适合构建 Sci-Fi 风格的大屏卡片、炫酷的导航入口或数据看板。

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

基础用法 ​

最简单的用法是将其作为容器包裹业务内容。默认情况下（mode="auto"），它会在 PC 端启用矩阵模式，在移动端启用陀螺仪模式。

html
<template>
  <Tui3DPanel>
    <div class="card-content">
      我是具有厚度和光影的 3D 卡片
    </div>
  </Tui3DPanel>
</template>

全局开关 ​

您可以通过全局配置项 t3D 快速开启或关闭所有 3D 面板的变形效果。 当设置为 false 时，组件将退化为普通的平面容器，不再消耗计算资源，这在性能受限的设备上非常有用。

javascript
// 全局配置 (通常在 main.js 或 setup 中)
const globalConfig = {
  // ...其他配置
  t3D: true // 开启/关闭全局 3D 变形
}

模式详解 ​

mode 属性是组件的核心，决定了 3D 交互的行为逻辑。

矩阵模式 (matrix) ​

PC端默认模式。 所有面板作为一个整体矩阵，根据光标相对于屏幕中心的位置进行统一变形。

  • 特点: 屏幕上所有 T3DPanel 的倾斜角度完全一致。光标在屏幕左上角时，所有面板统一向左上倾斜。
  • 适用: 规则排列的卡片墙、数据列表。

蜂巢模式 (hive) ​

独立注视交互。 每个面板独立计算光标与自身的相对位置，呈现出“向日葵”般的注视效果。

  • 特点: 距离光标越远的面板，透视变形越明显；面板始终朝向光标。
  • 适用: 散列布局、强调个体交互的场景。

联合模式 (unity) ​

整体容器变形。 将 <Tui3DPanel> 视为一个巨大的 3D 容器，内部的所有子元素（通过 Slot 传入）共享同一个透视平面，但子元素的阴影会根据各自位置实时独立计算，以保证真实感。

  • 特点: 适合包裹整个大屏区块或复杂的组合组件。

悬停模式 (hover) ​

鼠标交互触发。 仅在鼠标悬停（Hover）时触发 3D 变形。支持从 initialRotate（初始角度）平滑过渡到 hoverRotate（目标角度）。

  • 适用: 导航按钮、关键数据卡片。

动画模式 ​

自动循环播放。 根据传入的 animationRotate 关键帧数组，自动循环播放 3D 摇摆动画。

  • 配置: 需配合 duration (周期) 和 aniDelay (延迟) 使用。

陀螺仪模式 (gyro) ​

移动端专属。 调用移动设备的陀螺仪（重力感应）数据，根据手机的物理倾斜角度实时控制面板的 3D 姿态。

  • 要求: 必须在 HTTPS 环境下才能调用设备传感器 API。

静态模式 (static) ​

固定展示。 不响应任何交互，始终保持 initialRotate 设定的固定角度。

自适应模式 (auto) ​

智能切换 (默认)。

  • PC 端: 自动切换为 matrix 模式。
  • 移动端: 自动切换为 gyro 模式。

视觉与物理配置 ​

阴影系统 (Shadow) ​

组件会自动计算模拟真实光源的阴影。

  • showShadow: 是否显示阴影。
  • shadowCoeff: 阴影位移系数。值越大，阴影偏离主体越远，浮空感越强。
  • shadowBlur: 阴影模糊半径。

厚度系统 (Thickness) ​

组件通过层叠算法模拟物体的物理厚度。

  • showThickness: 是否显示厚度。
  • thicknessLength: 厚度的物理像素长度。
  • thicknessColor: 厚度层的颜色。默认自动获取主题色。
  • thicknessFixGap: 是否开启厚度缝隙修正（用于解决某些浏览器渲染时的微小裂缝）。

插槽作用域 ​

T3DPanel 通过作用域插槽向内部默认暴露了一组特殊的动态阴影类名。

这些类名并非静态样式，而是会根据当前的 3D 变形角度、光源方向实时计算偏移量和模糊度。将它们绑定到内部的业务元素上，可以实现阴影与 3D 姿态的实时联动，从而极大地增强立体感和真实感。

属性名默认值说明
boxShadowName'box-shadow-item'盒阴影联动。用于容器的 box-shadow，随面板倾斜改变阴影投射方向。
textShadowName'text-shadow-item'文字阴影联动。用于内部文本的 text-shadow，增强文字浮空感。
t3dShadowName't3d-shadow-item'3D 专用阴影。用于配合厚度系统或更复杂的 3D 场景模拟。
dropShadowName'drop-shadow-item'滤镜投影联动。用于透明 PNG 图片或 SVG 图标的 filter: drop-shadow，确保投影形状准确。

使用示例 ​

html
<Tui3DPanel>
  <template #default="{ boxShadowName, textShadowName, dropShadowName }">
    
    <div class="my-card" :class="boxShadowName">
      
      <h3 :class="textShadowName">3D Data Visualization</h3>
      
      <img src="icon.png" :class="dropShadowName" />
      
    </div>
    
  </template>
</Tui3DPanel>

API 参考 ​

Props ​

核心配置 ​

属性名类型默认值说明
modeString'auto'核心。可选值：'auto', 'matrix', 'hive', 'unity', 'hover', 'animation', 'gyro', 'static'。
coeffNumbernull全局变形系数。控制 3D 旋转的敏感度，值越大旋转幅度越大。
perspectiveNumber-CSS 视距。决定 3D 透视的强弱。
transformOriginStringnull变形原点。如 'left top', 'center'。支持标准 CSS 语法。
view3dBooleantrue当前组件是否参与 3D 渲染。

交互与动画 ​

属性名类型默认值说明
initialRotateObject{x:0,y:0,z:0}初始旋转角度 (Static/Hover 模式起始态)。
hoverRotateObject{x:0,y:0,z:0}悬停目标旋转角度 (Hover 模式)。
rotateMaxNumber50最大旋转角度限制 (Matrix/Hive 模式)。
rotateMinNumber-50最小旋转角度限制 (Matrix/Hive 模式)。
animationRotateArray[]动画关键帧数组 [{x,y}, {x,y}...] (Animation 模式)。
durationNumbernull动画单次循环时长 (ms)。
aniDelayNumber1000动画启动延迟 (ms)。
hoverDelayNumber0悬停触发延迟 (ms)。
hoverMaskBooleanfalse悬停时是否显示高亮遮罩。

移动端陀螺仪 ​

属性名类型默认值说明
uesAlphaBooleanfalse是否使用 Alpha (罗盘方向) 数据参与旋转。
fixAlphaNumber0Alpha 角度修正值。

视觉效果 (阴影/厚度) ​

属性名类型默认值说明
showShadowBooleantrue是否显示动态阴影。
shadowCoeffNumber-阴影位移系数。
shadowBlurNumber-阴影模糊度。
shadowTransparentNumber-阴影透明度。
showThicknessBooleantrue是否显示 3D 厚度。
thicknessLengthNumber-厚度深度 (px)。
thicknessCoeffNumber-厚度层叠系数。
thicknessColorStringnull厚度侧边颜色。
thicknessFixGapBooleanfalse开启厚度渲染缝隙修正。

其他 ​

属性名类型默认值说明
eventBusBooleanfalse是否开启事件总线。用于 Unity/Gyro 模式下的多组件状态同步。
indexNumber0列表渲染时的索引 (用于计算交错动画)。
groupString't3dcom'组件分组名称。