名称: aceternity-ui 描述: 100+个动画React组件(Aceternity UI)用于Next.js与Tailwind。适用于英雄部分、视差、3D效果，或遇到动画、shadcn CLI集成错误时使用。许可证: MIT 元数据: 版本: 1.1.0 作者: Claude Skills Maintainers 最后更新: 2025-12-08 最后验证: 2025-12-08 motion版本: “12.23.25” clsx版本: “2.1.1” tailwind_merge版本: “3.4.0” 包含参考: 2 关键词: - aceternity - aceternity-ui - react - nextjs - next.js - tailwind - tailwindcss - tailwind-css - framer-motion - motion - animations - animated-components - ui-components - component-library - shadcn - shadcn-ui - 3d-effects - background-effects - hero-sections - landing-pages - parallax - card-components - animated-cards - interactive-ui - modern-ui - visual-effects - typescript - bun - npm - pnpm

Aceternity UI 技能

概述

Aceternity UI 是一个优质、生产就绪的React组件库，专为Next.js应用设计。它提供100多个精美动画和交互式组件，使用Tailwind CSS和Framer Motion构建。组件通过shadcn CLI安装，并可以在您的代码库中直接自定义。

主要特点:

100+个动画、生产就绪的组件
为Next.js 13+构建，支持App Router
完整的TypeScript支持
Tailwind CSS v3+样式
Framer Motion动画
深色模式支持
复制粘贴友好（不是npm包）
完整的源代码访问，用于自定义

前提条件:

Next.js 13+（推荐App Router）
React 16.8+
Tailwind CSS v3+
TypeScript（推荐）
Node.js 18+ with bun, npm, or pnpm

安装

初始设置

对于新项目:

# 创建Next.js项目（首选bun）
bunx create-next-app@latest my-app
# 或: npx create-next-app@latest my-app
# 或: pnpm create next-app@latest my-app

cd my-app

# 选择这些选项:
# - TypeScript: 是
# - ESLint: 是
# - Tailwind CSS: 是
# - src/ 目录: 可选
# - App Router: 是（推荐）
# - 导入别名: @/*（默认）

通过shadcn CLI初始化Aceternity UI:

# 使用bun（首选）
bunx --bun shadcn@latest init

# 使用npm
npx shadcn@latest init

# 使用pnpm
pnpm dlx shadcn@latest init

# 在设置期间:
# - 样式: New York（推荐）
# - 颜色: Zinc（或您的偏好）
# - CSS变量: 是（推荐）

配置注册表:

初始化后，更新components.json以添加Aceternity注册表:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

安装组件

使用shadcn CLI 3.0+（命名空间注册表）:

# 安装特定组件
bunx shadcn@latest add @aceternity/background-beams
# 或: npx shadcn@latest add @aceternity/background-beams
# 或: pnpm dlx shadcn@latest add @aceternity/background-beams

# 组件将添加到: components/ui/background-beams.tsx

手动安装:

如果注册表方法不起作用，手动安装:

安装所需依赖:

bun add motion clsx tailwind-merge
# 或: npm install motion clsx tailwind-merge

添加实用函数到lib/utils.ts:

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

从ui.aceternity.com复制组件代码到您的项目

组件类别

1. 背景和效果（28个组件）

为英雄部分和全页布局创建令人惊叹的动画背景和视觉效果。

关键组件:

背景光束 - 跟随SVG路径的动画发光光束
背景渐变 - 平滑渐变背景，带有过渡
波浪背景 - 动画波浪图案
极光背景 - 受北极光启发的动画渐变
火花 - 粒子火花效果
流星 - 下落流星动画
聚光灯 - 动态聚光灯效果
网格和点背景 - 微妙的网格/点图案
漩涡 - 旋转漩涡动画
画布揭示效果 - 使用画布动画揭示内容

使用示例:

"use client";
import { BackgroundBeams } from "@/components/ui/background-beams";

export default function HeroSection() {
  return (
    <div className="h-screen w-full relative">
      <div className="max-w-4xl mx-auto z-10 relative p-8">
        <h1 className="text-5xl font-bold">欢迎</h1>
        <p className="text-xl mt-4">美丽的动画背景</p>
      </div>
      <BackgroundBeams />
    </div>
  );
}

何时使用:

需要视觉影响的英雄部分
带有动画背景的登录页面
需要深度的全屏部分
作品集或代理网站
带有行动呼吁的营销页面

2. 卡片组件（15个组件）

具有悬停效果、动画和3D变换的交互式卡片。

关键组件:

3D卡片效果 - 带有CSS透视和3D变换的卡片
卡片悬停效果 - 平滑悬停动画和过渡
可扩展卡片 - 扩展以显示更多内容的卡片
焦点卡片 - 在悬停时聚焦/高亮的卡片
卡片聚光灯 - 跟随鼠标的聚光灯效果
眩光卡片 - 全息眩光效果
摇晃卡片 - 有趣的摇晃动画
无限移动卡片 - 自动滚动卡片旋转木马
方向感知悬停 - 基于光标方向的悬停效果

使用示例:

"use client";
import { CardBody, CardContainer, CardItem } from "@/components/ui/3d-card";

export function ProductCard() {
  return (
    <CardContainer>
      <CardBody className="bg-gray-50 rounded-xl p-6">
        <CardItem translateZ="50" className="text-2xl font-bold">
          产品标题
        </CardItem>
        <CardItem translateZ="60" as="p" className="text-sm mt-2">
          产品描述在这里
        </CardItem>
        <CardItem translateZ="100" className="w-full mt-4">
          <img src="/product.jpg" className="rounded-xl" alt="产品" />
        </CardItem>
      </CardBody>
    </CardContainer>
  );
}

何时使用:

产品展示
功能亮点
作品集项目
团队成员资料
定价层级
博客文章预览

3. 滚动和视差（5个组件）

创建引人入胜的基于滚动的动画和视差效果。

关键组件:

视差滚动 - 带有视差滚动的图像
粘性滚动揭示 - 滚动时揭示内容
容器滚动动画 - 动画滚动容器
英雄视差 - 视差英雄部分
MacBook滚动 - MacBook风格的滚动交互

使用示例:

import { StickyScroll } from "@/components/ui/sticky-scroll-reveal";

const content = [
  {
    title: "功能一",
    description: "功能一的描述...",
    content: <div>视觉内容在这里</div>
  },
  // 更多项目...
];

export function Features() {
  return <StickyScroll content={content} />;
}

何时使用:

带有滚动交互的功能展示
叙事布局
产品导览
长内容，带有视觉中断
交互式时间线

4. 文本组件（10个组件）

用于标题、题目和交互式排版的动画文本效果。

关键组件:

文本生成效果 - 字符逐个出现的文本
打字机效果 - 打字动画
翻转单词 - 单词旋转动画
文本悬停效果 - 悬停时交互式文本
英雄高亮 - 渐变文本高亮
加密文本 - 矩阵风格加密文本效果
多彩文本 - 渐变动画文本

使用示例:

import { TypewriterEffect } from "@/components/ui/typewriter-effect";

const words = [
  { text: "构建" },
  { text: "令人惊叹的" },
  { text: "网站", className: "text-blue-500" }
];

export function Hero() {
  return <TypewriterEffect words={words} />;
}

何时使用:

英雄标题
引人注目的标题
动态内容显示
交互式登录页面
动画CTA

5. 按钮（4个组件）

具有动画和效果的增强按钮组件。

关键组件:

Tailwind CSS按钮 - 样式按钮集合
悬停边框渐变 - 动画渐变边框
移动边框 - 动画边框移动
状态按钮 - 带有过渡的多状态按钮

使用示例:

import { MovingBorder } from "@/components/ui/moving-border";

export function CTAButton() {
  return (
    <MovingBorder duration={2000} className="p-4">
      <span>开始使用</span>
    </MovingBorder>
  );
}

6. 导航（5个组件）

现代导航菜单和标签系统。

关键组件:

浮动导航栏 - 浮动导航栏
导航栏菜单 - 全功能导航菜单
标签 - 动画标签组件
可调整导航栏 - 响应式导航
粘性横幅 - 粘性公告横幅

7. 输入和表单（3个组件）

增强表单输入和文件上传组件。

关键组件:

注册表单 - 动画注册表单
占位符和消失输入 - 带有动画占位符的输入
文件上传 - 拖放文件上传

使用示例:

import { PlaceholdersAndVanishInput } from "@/components/ui/placeholders-and-vanish-input";

export function SearchBar() {
  const placeholders = [
    "搜索任何内容...",
    "您要找什么？",
    "输入以搜索..."
  ];

  return (
    <PlaceholdersAndVanishInput
      placeholders={placeholders}
      onChange={(e) => console.log(e.target.value)}
      onSubmit={(e) => {
        e.preventDefault();
        console.log("已提交");
      }}
    />
  );
}

8. 覆盖和弹出框（3个组件）

具有动画的模态对话框和工具提示。

关键组件:

动画模态 - 带有平滑动画的模态
动画工具提示 - 带有进入/退出动画的工具提示
链接预览 - 悬停时链接预览弹出框

使用示例:

import { Modal, ModalBody, ModalContent, ModalTrigger } from "@/components/ui/animated-modal";

export function BookingModal() {
  return (
    <Modal>
      <ModalTrigger className="bg-black text-white px-4 py-2 rounded-md">
        立即预订
      </ModalTrigger>
      <ModalBody>
        <ModalContent>
          <h2>预订详情</h2>
          {/* 模态内容 */}
        </ModalContent>
      </ModalBody>
    </Modal>
  );
}

9. 旋转木马和滑块（4个组件）

图像滑块和旋转木马组件。

关键组件:

图像滑块 - 全屏图像滑块
旋转木马 - 标准旋转木马组件
苹果卡片旋转木马 - 苹果风格卡片旋转木马
动画推荐语 - 推荐语滑块

10. 布局和网格（3个组件）

网格布局和容器组件。

关键组件:

布局网格 - 动画网格布局
便当网格 - 便当盒风格网格
容器覆盖 - 全屏容器

11. 数据与可视化（2个组件）

用于显示数据和比较的组件。

关键组件:

时间线 - 动画时间线组件
比较 - 前后比较滑块

12. 光标和指针（3个组件）

光标跟随效果和交互。

关键组件:

跟随指针 - 跟随光标的元素
指针高亮 - 光标高亮效果
镜头 - 放大镜效果

13. 3D组件（2个组件）

使用CSS变换的3D视觉效果。

关键组件:

3D针 - Pinterest风格3D卡片
3D走马灯 - 3D旋转走马灯

14. 加载器（2个组件）

加载动画和进度指示器。

关键组件:

多步骤加载器 - 多步骤加载动画
加载器 - 各种加载旋转器

15. 部分和块（3个组件）

预构建部分模板。

关键组件:

功能部分 - 功能展示模板
卡片 - 预设计卡片布局
英雄部分 - 英雄部分模板

常见模式

深色模式支持

所有Aceternity组件通过Tailwind的深色模式类支持深色模式:

<div className="bg-white dark:bg-black text-black dark:text-white">
  {/* 内容 */}
</div>

响应式设计

组件默认响应式。使用Tailwind的响应式前缀:

<h1 className="text-2xl md:text-4xl lg:text-6xl">
  响应式标题
</h1>

组合组件

组件可以组合用于复杂布局:

import { BackgroundBeams } from "@/components/ui/background-beams";
import { TypewriterEffect } from "@/components/ui/typewriter-effect";
import { MovingBorder } from "@/components/ui/moving-border";

export default function Hero() {
  return (
    <div className="h-screen relative">
      <div className="z-10 relative flex flex-col items-center justify-center h-full">
        <TypewriterEffect words={words} />
        <MovingBorder>
          <button>开始使用</button>
        </MovingBorder>
      </div>
      <BackgroundBeams />
    </div>
  );
}

最佳实践

1. 性能优化

使用“use client”指令 - Aceternity组件使用Framer Motion，需要客户端渲染:

"use client";
import { Component } from "@/components/ui/component";

懒加载重组件:

import dynamic from 'next/dynamic';

const HeavyBackground = dynamic(
  () => import('@/components/ui/background-beams'),
  { ssr: false }
);

2. 可访问性

添加ARIA标签:

<button aria-label="打开菜单">
  <MenuIcon />
</button>

确保键盘导航:

<div role="button" tabIndex={0} onKeyDown={handleKeyDown}>
  交互元素
</div>

3. 自定义

使用className覆盖样式:

<BackgroundBeams className="opacity-50" />

直接修改组件源代码 - 由于组件复制到您的项目，您可以编辑它们:

// components/ui/background-beams.tsx
export function BackgroundBeams({ className, myCustomProp }: Props) {
  // 根据需要自定义
}

4. 类型安全

使用TypeScript获取道具类型:

interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function Card({ title, description, image }: CardProps) {
  // 组件实现
}

故障排除

常见问题

1. “模块未找到: motion”

bun add motion
# 或: npm install motion

2. “cn未定义” 确保lib/utils.ts存在，带有cn辅助函数。

3. 组件不动画 验证“use client”指令在文件顶部。

4. Tailwind类不工作 确保Tailwind已配置，并且globals.css导入Tailwind指令:

@tailwind base;
@tailwind components;
@tailwind utilities;

5. 深色模式不工作 检查tailwind.config.ts配置了darkMode: "class"。

令牌效率

此技能通过以下方式提供显著的令牌节省:

预先审查的组件选择 - 节省约3k令牌探索组件选项
安装说明 - 节省约2k令牌调试设置问题
组件分类 - 节省约2k令牌找到正确组件
使用示例 - 节省约2k令牌编写样板代码
故障排除指南 - 节省约1k令牌调试常见问题

估计节省: 每个实现约10k令牌（减少65-70%）

防止的错误:

缺少motion依赖
不正确的shadcn CLI初始化
缺少cn实用函数
缺少“use client”指令
不正确的注册表配置
错误的Next.js配置（页面路由器 vs 应用路由器）

何时加载参考

基于任务上下文加载参考文件:

如果用户询问…	加载此参考
新项目设置、安装、入门	`references/quick-start.md`（465行）
查找特定组件、组件类别、CLI命令	`references/component-catalog.md`（635行）
使用示例、模式、故障排除	主SKILL.md（此文件）

参考摘要:

quick-start.md - 5分钟设置指南，第一个组件示例，故障排除，项目结构
component-catalog.md - 100+个组件的完整列表，包含安装命令和使用案例

附加资源

官方文档: https://ui.aceternity.com/docs
组件画廊: https://ui.aceternity.com/components
Shadcn UI: https://ui.shadcn.com
Framer Motion: https://www.framer.com/motion
Tailwind CSS: https://tailwindcss.com

许可证

此技能文档在MIT许可证下提供。Aceternity UI组件有自己的许可证 - 查看https://ui.aceternity.com获取详情。

最后更新: 2025-12-08 版本: 1.1.0 维护者: Claude Skills Maintainers

AceternityUI技能 aceternity-ui