3d Image Ring

環形／半球投影的 3D 影像畫廊，可拖曳旋轉、自動輪轉並保留慣性。

把一組影像等角排成一圈立體滾筒，可用指標拖曳旋轉、放開後保留慣性，並支援自動輪轉與背面景深壓暗。純 CSS 3D transform 實作，不依賴 WebGL。

載入預覽⋯

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

透視距離perspective

1600

俯視傾角tilt

自動旋轉autoRotate

旋轉速度（度/秒）autoRotateSpeed

背面壓暗程度backDim

0.72

<3dImageRing />

安裝

npx shadcn@latest add https://webberui.com/r/3d-image-ring.json

或在 components.json 設定 registries 後，改用 @webberui/3d-image-ring 安裝。

安裝依賴後，從 registry JSON（/r/3d-image-ring.json 的 files[0].content）複製 3d-image-ring.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion clsx tailwind-merge

使用

items 每一項的 content 可以是任意節點——圖片、卡片或漸層皆可。下例用漸層當作示範影像：

import { ThreeDImageRing } from "@/components/ui/3d-image-ring";

const items = Array.from({ length: 8 }, (_, i) => ({
  id: i,
  label: `Slide ${i + 1}`,
  content: (
    <div
      className="h-full w-full"
      style={{ background: "linear-gradient(150deg, #6366f1, #22d3ee)" }}
    />
  ),
}));

<ThreeDImageRing items={items} itemWidth={180} itemHeight={240} />;

Props

Prop	型別	預設值	說明
`items`	`ThreeDImageRingItem[]`	—	環上的面板，含 `id`、`content`、`label`
`itemWidth`	`number`	`200`	面板寬度（px）
`itemHeight`	`number`	`260`	面板高度（px）
`radius`	`number`	自動	環半徑（px）；省略時依面板寬與數量自動計算
`perspective`	`number`	`1600`	CSS 透視距離（px），越小透視越誇張
`tilt`	`number`	`8`	舞台仰視傾角（deg），呈半球俯視感
`autoRotate`	`boolean`	`true`	是否自動旋轉
`autoRotateSpeed`	`number`	`10`	自動旋轉速度（度/秒）
`dragSensitivity`	`number`	`0.3`	拖曳靈敏度（度/px）
`inertia`	`boolean`	`true`	甩動放開後是否保留慣性
`pauseOnHover`	`boolean`	`true`	指標懸停時暫停自動旋轉
`backDim`	`number`	`0.72`	背面面板的最大壓暗程度（`0`–`1`）
`itemClassName`	`string`	—	每個面板容器的額外 class（如圓角）
`ariaLabel`	`string`	`"3D 影像環"`	整個環的無障礙標籤

可及性

使用者系統開啟「減少動態效果」時，改以可水平捲動的靜態影像列呈現，不套用 3D 與拖曳
支援鍵盤：聚焦後以左右方向鍵逐格旋轉
每個面板可透過 label 提供無障礙描述

Playground

安裝

使用

Props

可及性

On this page