ModelViewer

model-viewer

交互式 3D 模型查看舞台 · 拖拽旋转(惯性) + 鼠标视差 + 悬停倾斜 + 自动旋转 + 接触阴影(零依赖 CSS 3D · RAF · reduced-motion)

用法

基础用法

把任意 children 当「模型」放进舞台——拖拽旋转、鼠标视差、悬停倾斜默认全开。

瑚

tsx

<ModelViewer height={320}>
  {/* 任意节点都可作为「模型」 */}
  <YourModel />
</ModelViewer>

自动旋转

autoRotate 让模型绕 Y 轴匀速自转，autoRotateSpeed 控制角速度。

瑚

tsx

<ModelViewer height={320} autoRotate autoRotateSpeed={28}>
  <YourModel />
</ModelViewer>

极简交互

关掉视差/悬停/接触阴影/重置按钮，只保留纯拖拽旋转。

tsx

<ModelViewer
  height={300}
  enableMouseParallax={false}
  enableHoverRotation={false}
  showContactShadow={false}
  showResetButton={false}
>
  <div
    className="grid size-32 place-items-center rounded-2xl text-4xl font-bold text-white"
    style={{
      background: "linear-gradient(135deg, var(--color-chart-2), var(--color-chart-5))",
      transform: "translateZ(40px)",
    }}
  >
    UI
  </div>
</ModelViewer>

何时用

需要把任意 React 节点（产品图/卡片/SVG/emoji）放进一个可拖拽旋转、带惯性/视差/悬停倾斜/接触阴影的 3D 舞台时用——瑚琏化用纯 CSS 3D 替代了 three.js，不加载真实 GLTF/FBX 模型。要做局部放大镜用 Lens；要做眩光悬停用 GlareHover。ModelViewer 是「给 children 施加 3D 交互的舞台」。

导入

import { ModelViewer } from "@hulianui/ui"

Props

名称	类型	默认	说明
width	`number ｜ string`	`"100%"`	舞台宽度，由外层容器约束
height	`number ｜ string`	`360`	舞台高度
defaultRotationY	`number`	`-20`	初始偏航角（绕 Y，°），拖拽时累加
defaultRotationX	`number`	`12`	初始俯仰角（绕 X，°），拖拽时累加
perspective	`number`	`1000`	透视景深 px，越小透视越夸张
enableManualRotation	`boolean`	`true`	允许鼠标拖拽旋转，松手带惯性缓停
enableMouseParallax	`boolean`	`true`	鼠标视差（指针移动时模型轻微位移）
enableHoverRotation	`boolean`	`true`	悬停倾斜（模型朝指针方向倾斜）
autoRotate	`boolean`	`false`	自动绕 Y 轴匀速旋转，与手动拖拽叠加
autoRotateSpeed	`number`	`24`	自转角速度（°/s），仅 `autoRotate` 时生效
showResetButton	`boolean`	`true`	右上角「重置视角」工具按钮
showContactShadow	`boolean`	`true`	底部柔和接触阴影
className	`string`	—	透传根容器 className
style	`CSSProperties`	—	透传根容器内联样式

Slots

插槽	类型	说明
children	`ReactNode`	放进 3D 舞台中央的「模型」，由组件统一施加旋转/视差/倾斜

禁忌 / 坑

这是 CSS 3D 舞台，不渲染真实 GLTF/FBX/OBJ；children 应是平面/伪 3D 内容，深度感来自外层 preserve-3d 子层自行用 translateZ。
客户端组件（拖拽 + RAF 惯性循环），SSR 下静止；reduced-motion 下关惯性/自转等动画。
多层立方面等需 transform-style: preserve-3d 的内容须自己在 children 里设置，组件只负责整体旋转/视差容器。

Playground

自动旋转自转速度 °/s鼠标视差悬停倾斜接触阴影

瑚

<div className="overflow-hidden rounded-xl"
     style={{ background: "oklch(0.16 0.02 255)" }}>
  <ModelViewer
    height={320}
    autoRotate={false}
    autoRotateSpeed={24}
    enableMouseParallax={true}
    enableHoverRotation={true}
    showContactShadow={true}
  >
    {/* 任意 children 作为「模型」 */}
    <YourModel />
  </ModelViewer>
</div>

用法

基础用法

把任意 children 当「模型」放进舞台——拖拽旋转、鼠标视差、悬停倾斜默认全开。

瑚

tsx

<ModelViewer height={320}>
  {/* 任意节点都可作为「模型」 */}
  <YourModel />
</ModelViewer>

自动旋转

autoRotate 让模型绕 Y 轴匀速自转，autoRotateSpeed 控制角速度。

瑚

tsx

<ModelViewer height={320} autoRotate autoRotateSpeed={28}>
  <YourModel />
</ModelViewer>

极简交互

关掉视差/悬停/接触阴影/重置按钮，只保留纯拖拽旋转。

tsx

<ModelViewer
  height={300}
  enableMouseParallax={false}
  enableHoverRotation={false}
  showContactShadow={false}
  showResetButton={false}
>
  <div
    className="grid size-32 place-items-center rounded-2xl text-4xl font-bold text-white"
    style={{
      background: "linear-gradient(135deg, var(--color-chart-2), var(--color-chart-5))",
      transform: "translateZ(40px)",
    }}
  >
    UI
  </div>
</ModelViewer>

何时用

Props

名称	类型	默认	说明
width	`number ｜ string`	`"100%"`	舞台宽度，由外层容器约束
height	`number ｜ string`	`360`	舞台高度
defaultRotationY	`number`	`-20`	初始偏航角（绕 Y，°），拖拽时累加
defaultRotationX	`number`	`12`	初始俯仰角（绕 X，°），拖拽时累加
perspective	`number`	`1000`	透视景深 px，越小透视越夸张
enableManualRotation	`boolean`	`true`	允许鼠标拖拽旋转，松手带惯性缓停
enableMouseParallax	`boolean`	`true`	鼠标视差（指针移动时模型轻微位移）
enableHoverRotation	`boolean`	`true`	悬停倾斜（模型朝指针方向倾斜）
autoRotate	`boolean`	`false`	自动绕 Y 轴匀速旋转，与手动拖拽叠加
autoRotateSpeed	`number`	`24`	自转角速度（°/s），仅 `autoRotate` 时生效
showResetButton	`boolean`	`true`	右上角「重置视角」工具按钮
showContactShadow	`boolean`	`true`	底部柔和接触阴影
className	`string`	—	透传根容器 className
style	`CSSProperties`	—	透传根容器内联样式

插槽

类型

说明

children

ReactNode

放进 3D 舞台中央的「模型」，由组件统一施加旋转/视差/倾斜

禁忌 / 坑

这是 CSS 3D 舞台，不渲染真实 GLTF/FBX/OBJ；children 应是平面/伪 3D 内容，深度感来自外层 preserve-3d 子层自行用 translateZ。

客户端组件（拖拽 + RAF 惯性循环），SSR 下静止；reduced-motion 下关惯性/自转等动画。

多层立方面等需 transform-style: preserve-3d 的内容须自己在 children 里设置，组件只负责整体旋转/视差容器。

Playground

自动旋转自转速度 °/s鼠标视差悬停倾斜接触阴影

瑚

<div className="overflow-hidden rounded-xl"
     style={{ background: "oklch(0.16 0.02 255)" }}>
  <ModelViewer
    height={320}
    autoRotate={false}
    autoRotateSpeed={24}
    enableMouseParallax={true}
    enableHoverRotation={true}
    showContactShadow={true}
  >
    {/* 任意 children 作为「模型」 */}
    <YourModel />
  </ModelViewer>
</div>

ModelViewer

用法

基础用法

自动旋转

极简交互

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground

ModelViewer

用法

基础用法

自动旋转

极简交互

何时用

导入

Props

Slots

禁忌 / 坑

相关

Playground