Card3D 3D 悬浮卡片

新粗野主义风格的 3D 交互卡片，通过捕捉指针相对卡片中心的坐标偏移，产生流畅的 3D 旋转偏转，阴影层朝反方向位移产生实体立体质感。

预览

Preview

3D 悬浮卡片

将鼠标移入卡片，体验 3D 物理偏转与反向阴影投影效果。

大阴影变体

shadow="lg" 提供更大的偏移阴影。

超大阴影变体

shadow="xl" 提供最大的偏移阴影。

最大旋转角度 (maxRotation=30)

更大的旋转幅度，偏转效果更夸张。

透视距离 (perspective=500)

更近的透视距离，3D 纵深感更强。

缩放比例 (scale=1.1)

悬停时放大至 1.1 倍，视觉冲击更强。

禁用状态 (disabled=true)

禁用 3D 效果，卡片不会响应鼠标移动。

颜色变体

主色 (primary)

强调 (accent)

静音 (muted)

可点击

点击我

clickable=true，点击触发 click 事件。已点击 0 次。

安装

pnpm dlx brutx-vue@latest add card-3d

用法

<script setup>
import { Card3D } from 'brutx-ui-vue'
</script>

<template>
    <Card3D class="w-full max-w-sm">
        <div class="p-6">
            <h3 class="text-lg font-black mb-2">3D 悬浮卡片</h3>
            <p class="text-sm">将鼠标移入卡片，体验 3D 物理偏转效果。</p>
        </div>
    </Card3D>
</template>

变体

阴影变体

变体	说明
default	标准阴影偏移
lg	大阴影偏移
xl	超大阴影偏移

颜色变体

通过 variant 属性控制卡片背景色与文字色。

变体	说明
default	背景色背景，深色文字
primary	主色（珊瑚红）背景
accent	强调色（黄色）背景
muted	静音色（灰）背景

<Card3D variant="primary" class="w-full max-w-sm">
    <div class="p-6">
        <h3 class="text-lg font-black mb-2">主色卡片</h3>
    </div>
</Card3D>

可点击

设置 clickable 为 true 后，卡片光标变为 pointer，添加 role="button"、tabindex="0" 并支持 Enter/Space 键触发 click 事件。Enter 按下或 Space 抬起各触发一次 click，长按不会重复触发；键盘激活产生的合成 click 不会重复发出，真实鼠标点击不受影响，程序化调用 el.click() 不再触发 click 事件。

<script setup>
import { Card3D } from 'brutx-ui-vue'

function handleClick(event) {
    console.log('卡片被点击', event)
}
</script>

<template>
    <Card3D clickable class="w-full max-w-sm" @click="handleClick">
        <div class="p-6">点击我</div>
    </Card3D>
</template>

API 参考

Card3D — 属性

名称	类型	默认值	说明
maxRotation	number | undefined	15	限制指针移动产生的最大 3D 偏转角度，单位为度。
详情 声明类型 number | undefined 默认值详情 声明 15 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 15 来源 Card3D.vue:14 packages/ui/src/components/card-3d/Card3D.vue
perspective	number | undefined	1000	设置 3D 透视深度，单位为像素；数值越小透视效果越强。
详情 声明类型 number | undefined 默认值详情 声明 CARD_3D_DEFAULT_PERSPECTIVE_PX 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 1000 来源 Card3D.vue:15 packages/ui/src/components/card-3d/Card3D.vue
scale	number | undefined	1.02	悬停时卡片的缩放比例。
详情 声明类型 number | undefined 默认值详情 声明 1.02 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 1.02 来源 Card3D.vue:16 packages/ui/src/components/card-3d/Card3D.vue
shadowOffset	number | undefined	10	控制随指针移动的投影最大偏移距离，单位为像素。
详情 声明类型 number | undefined 默认值详情 声明 10 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 10 来源 Card3D.vue:17 packages/ui/src/components/card-3d/Card3D.vue
shadow	"default" | "lg" | "xl" | undefined	"default"	设置默认、大或超大投影样式。
详情 声明类型 NonNullable<"default" | "lg" | "xl" | null | undefined> | undefined 字面量 "default" "lg" "xl" 默认值详情 声明 'default' 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 "default" 来源 Card3D.vue:18 packages/ui/src/components/card-3d/Card3D.vue
variant	"accent" | "default" | "muted" | "primary" | undefined	"default"	设置卡片背景的默认、主色、强调色或柔和色变体。
详情 声明类型 NonNullable<"default" | "primary" | "accent" | "muted" | null | undefined> | undefined 字面量 "accent" "default" "muted" "primary" 默认值详情 声明 'default' 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 "default" 来源 Card3D.vue:19 packages/ui/src/components/card-3d/Card3D.vue
disabled	boolean | undefined	false	禁用指针驱动的 3D 动效，使卡片保持静态。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 false 来源 Card3D.vue:20 packages/ui/src/components/card-3d/Card3D.vue
clickable	boolean | undefined	false	启用按钮式点击交互、键盘激活和 click 事件。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 false 来源 Card3D.vue:21 packages/ui/src/components/card-3d/Card3D.vue
ariaLabel	string | undefined	undefined	为可点击卡片指定无障碍名称；省略时由卡片插槽内容提供名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 undefined 来源 Card3D.vue:22 packages/ui/src/components/card-3d/Card3D.vue
class	string | undefined	undefined	追加到卡片根元素的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/card-3d/Card3D.vue 解析值 undefined 来源 Card3D.vue:23 packages/ui/src/components/card-3d/Card3D.vue

Card3D — 事件

名称	签名或类型	说明
@click	[event: MouseEvent | KeyboardEvent]	可点击且未禁用时，在指针点击或 Enter、Space 键激活后发出对应事件对象。
详情 声明类型 [event: MouseEvent | KeyboardEvent] 来源 Card3D.vue packages/ui/src/components/card-3d/Card3D.vue

Card3D — 插槽

名称	签名或类型	说明
#default	{}	渲染卡片主体内容，可组合任意自定义内容。
详情 声明类型 {} 来源 Card3D.vue packages/ui/src/components/card-3d/Card3D.vue

可访问性

• 组件设置了 role="group"，并通过 i18n 提供 aria-label（中文为 "3D 交互卡片"，英文为 "3D Interactive Card"）
• 可点击卡片（clickable）仅在显式传入 ariaLabel 时设置 aria-label，未传入时由 slot 内容充当可访问名称；空 slot 且未传 ariaLabel 的可点击卡片将无可访问名称，调用方应自行传入 ariaLabel
• 当用户偏好 prefers-reduced-motion: reduce 时，自动禁用 3D 偏转效果
• 可通过 disabled prop 完全禁用 3D 效果