一行命令解锁Amicro：shadcn/ui Registry命名空间集成简单指南

一行命令解锁Amicro：shadcn/ui Registry命名空间集成简单指南

【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-

Amicro（Amicro--Micro-transitions）是一个基于 Motion 打造的 React 微交互与动画组件库，收录了 162 个入场过渡、悬停特效、文本动画与加载动画组件。本文将手把手教你通过shadcn/ui Registry 命名空间（@amicro）对接该组件库，只需在配置文件中加一行映射，之后任何组件都能用一行命令安装进项目。

为什么需要 shadcn/ui Registry 集成？

Amicro 采用的是copy-to-code（代码复制）模式：组件不是以 npm 包的形式被引用，而是把 TSX 源码直接写入你的项目，零运行时开销、可随意修改。要打通这条流水线，有两种方式：

命名空间方式的核心，是让 shadcn CLI 把@amicro/xxx这个短名字自动解析为 Amicro 仓库中对应的 registry.json 清单。

第一步：在 components.json 中声明 @amicro 命名空间

打开你项目根目录的components.json（shadcn 项目初始化时自带），在registries字段中加一行映射：

{ "registries": { "@amicro": "<Amicro 仓库 registry 原始地址>/registry/{name}.json" } }

要点说明：

• {name}是占位符，shadcn CLI 会自动把它替换成你实际要安装的组件名，例如fade-in；
• 地址前缀指向 Amicro 的 registry/ 目录，该目录下每个组件都有一份同名.json元数据（如 registry/ui/entrance/fade-in.json 对应的组件源码在 registry/ui/entrance/fade-in.tsx）；
• 完整的组件索引清单见 registry/registry.json，共 162 个条目，包含 155 个 UI 组件、5 个 Hooks 和 2 个工具库。

第二步：一行命令安装任意组件

配置完成后，直接按名字安装，CLI 会自动拉取源码、写入依赖、放置到约定目录：

# 入场过渡组件 npx shadcn add @amicro/fade-in npx shadcn add @amicro/zoom-in # 悬停与文本动效 npx shadcn add @amicro/tilt-card npx shadcn add @amicro/text-reveal # Hooks 与预设工具 npx shadcn add @amicro/use-scroll-progress npx shadcn add @amicro/presets

安装过程中，CLI 会根据元数据自动处理依赖（如framer-motion），无需手动npm install。

组件装到了哪里？

每个 registry 条目都声明了target字段，例如fade-in的安装目标是@components/amicro/fade-in.tsx。也就是说，所有 Amicro 组件会统一落在components/amicro/目录下，与项目原有组件清晰隔离，方便管理与二次修改。

162 个组件都包含哪些类别？

Hooks 源码可在 registry/hooks/ 目录中直接浏览，例如 use-scroll-progress.ts 实现了一个监听滚动进度的自定义 Hook。

前置条件与常见问题

环境要求（来自 README.md）：

• Node.jsv18.0.0+
• React18或19
• Tailwind CSSv3或v4
• 已安装motion或framer-motion

常见问题：

1. components.json不存在？先运行npx shadcn init初始化 shadcn，再添加命名空间映射；
2. 命名空间不生效？检查registries拼写和 URL 中的{name}占位符是否保留（不要手动替换掉）；
3. 想离线浏览全部组件？可以克隆仓库本地预览：

git clone https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-

仓库自带演示页面（入口见 src/components/CliPage.tsx），运行后即可在线预览全部动效，确认满意后再安装到生产项目。

小结

整套流程只有三步：

1. 在components.json的registries中注册@amicro命名空间；
2. 用npx shadcn add @amicro/组件名一行命令安装；
3. 组件落到components/amicro/目录，源码在手，随意定制。

从此，162 个经过精心调校的微交互组件都藏在一条命令背后，让 React 页面的每一次入场、悬停与加载都自带高级感。

【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-