Amicro开发者手册本地开发、新增组件与loadersCode自动生成脚本完整指南【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-Amicrosubhanhq/amicro是一个基于 Motion 的 React 微交互与过渡动效组件库提供 130 加载动画、卡片布局、入场过渡等「复制即用」组件并附带零配置 CLI 工具和 shadcn/ui 注册表。本手册带你完成 Amicro 本地开发环境搭建、学会新增一个微交互组件并讲透 loadersCode 自动生成脚本的工作原理。一、项目结构快速上手开始本地开发前先了解仓库的核心目录划分目录职责registry/组件注册表每个组件对应一个.tsx源码 一个.json元数据供 shadcn CLI 安装src/components/展示站组件卡片、指标卡、Dither 图表等演示页面src/data/各组件目录的注册数据如 loaders.ts 定义了全部加载动画清单src/utils/工具函数其中 loadersCode.ts 是脚本自动生成的产物scripts/Node 脚本拆分加载器、生成 loadersCode 映射表注册表的总入口是 registry/registry.json它以 shadcn 官方 schema 声明了每个条目的name、type、files.path与安装目标路径target用户执行npx shadcn add amicro/fade-in时就是靠它把源码拷贝到你的项目中。二、一键安装步骤本地开发环境搭建环境要求Node.js ≥ 18见 README.md 的 Prerequisites 一节React 18 / 19、Tailwind CSS v3 或 v4、motion或 framer-motion三步跑起来# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions- cd Amicro--Micro-transitions- # 2. 安装依赖 npm install # 3. 启动开发服务器默认 3000 端口 npm run dev打开http://localhost:3000即可预览全部动效组件。其他常用命令npm run build构建生产包提交前务必验证编译通过npm run lint执行tsc --noEmit做类型检查npm run clean清理构建产物 提示vite.config.ts 中路径别名指向仓库根目录且 HMR 行为受DISABLE_HMR环境变量控制本地调试时无需改动。三、如何新增一个 Amicro 微交互组件新增组件的核心原则源码放 registry、清单放 registry.json、演示放 src/data。以添加一个spin-circle加载动画为例1. 编写组件源码在 registry/ui/loading/ 下新建spin-circle.tsx遵循项目既有风格可参考 pulse-dots.tsx使用motion/react的motion组件做动画样式仅使用纯 Tailwind 类兼容明暗双主题导出方式统一为export const SpinCircle () {...}2. 注册到注册表在 registry/registry.json 的items数组中追加一条记录{ name: spin-circle, type: registry:ui, title: Spin Circle, description: Rotating circle loading animation., dependencies: [framer-motion], files: [ { path: registry/ui/loading/spin-circle.tsx, type: registry:ui, target: components/amicro/spin-circle.tsx } ] }3. 补充独立 JSON可选但推荐在 registry/ui/ 根目录创建spin-circle.json参照 pulse-dots.json它内联了组件content支持通过 raw URL 直接安装。4. 加入展示站清单在 src/data/loaders.ts 中引入新组件并加入loaderGroups分组展示站即可自动渲染你的新动效。提交前检查清单运行npm run lint确认无类型错误运行npm run build确认构建成功若组件属于 loader重新运行 loadersCode 生成脚本见下节按 CONTRIBUTING.md 的规范建分支、写清晰的 commit message 后提交 PR四、loadersCode 自动生成脚本完全解析它解决什么问题展示站内每个加载动画卡片都带「复制代码」按钮——点击后需要拿到该组件的完整 TSX 源码。如果把 130 个文件都动态 import打包体积会失控。因此项目采用构建期把源码内联成一张字符串映射表的方案最终产出就是 src/utils/loadersCode.ts// Automatically generated loader code maps export const loadersCode: Recordstring, string { ... };脚本工作流程核心脚本是 scripts/generate-loaders-code.js逻辑只有四步扫描源码读取registry/ui/loading/下所有.tsx文件多键索引为每个文件建立三重映射——kebab-case 文件名pulse-dots、导出符号名PulseDots、以及 loaders.ts 中声明的loader.name缺失告警若某个 loader 找不到对应源码脚本会打印WARNING: Missing loader code for:提示便于及时发现漏登记写出生成文件序列化为 JSON 写入src/utils/loadersCode.ts展示站消费入口在 src/App.tsx 中按loader、loader.kebabName、loader.component.name等顺序逐级兜底查询保证任一命名方式都能命中。历史脚本split-loaders.js 的来龙去脉仓库还保留了一个一次性迁移脚本 scripts/split-loaders.js它记录了组件库的演进历史早期所有加载动画挤在一个巨大的Loaders.tsx单文件中该脚本将其逐个export const拆分成独立的 kebab-case 文件如PulseDots→pulse-dots.tsx并统一补充了 React 与 framer-motion 的标准 import 头同时顺带生成了第一版loadersCode.ts。⚠️ 注意该脚本内含 Windows 绝对路径c:/Users/...仅用于历史迁移日常只需使用跨平台的 generate-loaders-code.js。什么时候必须重新生成新增 / 删除 / 重命名 loader 组件后修改了 loader 源码内容复制按钮需要同步最新代码重新生成后 diff 检查loadersCode.ts确认条目数量与预期一致即可。五、常见问题速查FAQQ本地启动后 3000 端口被占用npm run dev底层是vite --port3000 --host0.0.0.0可临时修改 package.json 中 scripts 的端口号。Q新增组件后用户无法通过 CLI 安装检查 registry/registry.json 中files.path是否与实际文件路径完全一致区分大小写。Q复制按钮拿到的代码是旧的说明忘了重新运行 scripts/generate-loaders-code.jsloadersCode 映射表尚未更新。Q样式不符合设计规范项目约定动画一律走motion包样式一律纯 Tailwind 类颜色 token 遵循现有明暗双主题体系详见 CONTRIBUTING.md 的 Code Guidelines。结语掌握了「registry 三件套」.tsx.jsonregistry.json条目和 loadersCode 生成链路你就具备了完整贡献 Amicro 的能力。建议先挑一个简单的 loader 仿写练手跑通npm run lint与npm run build后再发起 PR。祝你在 React 微交互的世界里玩得开心 【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Amicro开发者手册：本地开发、新增组件与loadersCode自动生成脚本完整指南
Amicro开发者手册本地开发、新增组件与loadersCode自动生成脚本完整指南【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-Amicrosubhanhq/amicro是一个基于 Motion 的 React 微交互与过渡动效组件库提供 130 加载动画、卡片布局、入场过渡等「复制即用」组件并附带零配置 CLI 工具和 shadcn/ui 注册表。本手册带你完成 Amicro 本地开发环境搭建、学会新增一个微交互组件并讲透 loadersCode 自动生成脚本的工作原理。一、项目结构快速上手开始本地开发前先了解仓库的核心目录划分目录职责registry/组件注册表每个组件对应一个.tsx源码 一个.json元数据供 shadcn CLI 安装src/components/展示站组件卡片、指标卡、Dither 图表等演示页面src/data/各组件目录的注册数据如 loaders.ts 定义了全部加载动画清单src/utils/工具函数其中 loadersCode.ts 是脚本自动生成的产物scripts/Node 脚本拆分加载器、生成 loadersCode 映射表注册表的总入口是 registry/registry.json它以 shadcn 官方 schema 声明了每个条目的name、type、files.path与安装目标路径target用户执行npx shadcn add amicro/fade-in时就是靠它把源码拷贝到你的项目中。二、一键安装步骤本地开发环境搭建环境要求Node.js ≥ 18见 README.md 的 Prerequisites 一节React 18 / 19、Tailwind CSS v3 或 v4、motion或 framer-motion三步跑起来# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions- cd Amicro--Micro-transitions- # 2. 安装依赖 npm install # 3. 启动开发服务器默认 3000 端口 npm run dev打开http://localhost:3000即可预览全部动效组件。其他常用命令npm run build构建生产包提交前务必验证编译通过npm run lint执行tsc --noEmit做类型检查npm run clean清理构建产物 提示vite.config.ts 中路径别名指向仓库根目录且 HMR 行为受DISABLE_HMR环境变量控制本地调试时无需改动。三、如何新增一个 Amicro 微交互组件新增组件的核心原则源码放 registry、清单放 registry.json、演示放 src/data。以添加一个spin-circle加载动画为例1. 编写组件源码在 registry/ui/loading/ 下新建spin-circle.tsx遵循项目既有风格可参考 pulse-dots.tsx使用motion/react的motion组件做动画样式仅使用纯 Tailwind 类兼容明暗双主题导出方式统一为export const SpinCircle () {...}2. 注册到注册表在 registry/registry.json 的items数组中追加一条记录{ name: spin-circle, type: registry:ui, title: Spin Circle, description: Rotating circle loading animation., dependencies: [framer-motion], files: [ { path: registry/ui/loading/spin-circle.tsx, type: registry:ui, target: components/amicro/spin-circle.tsx } ] }3. 补充独立 JSON可选但推荐在 registry/ui/ 根目录创建spin-circle.json参照 pulse-dots.json它内联了组件content支持通过 raw URL 直接安装。4. 加入展示站清单在 src/data/loaders.ts 中引入新组件并加入loaderGroups分组展示站即可自动渲染你的新动效。提交前检查清单运行npm run lint确认无类型错误运行npm run build确认构建成功若组件属于 loader重新运行 loadersCode 生成脚本见下节按 CONTRIBUTING.md 的规范建分支、写清晰的 commit message 后提交 PR四、loadersCode 自动生成脚本完全解析它解决什么问题展示站内每个加载动画卡片都带「复制代码」按钮——点击后需要拿到该组件的完整 TSX 源码。如果把 130 个文件都动态 import打包体积会失控。因此项目采用构建期把源码内联成一张字符串映射表的方案最终产出就是 src/utils/loadersCode.ts// Automatically generated loader code maps export const loadersCode: Recordstring, string { ... };脚本工作流程核心脚本是 scripts/generate-loaders-code.js逻辑只有四步扫描源码读取registry/ui/loading/下所有.tsx文件多键索引为每个文件建立三重映射——kebab-case 文件名pulse-dots、导出符号名PulseDots、以及 loaders.ts 中声明的loader.name缺失告警若某个 loader 找不到对应源码脚本会打印WARNING: Missing loader code for:提示便于及时发现漏登记写出生成文件序列化为 JSON 写入src/utils/loadersCode.ts展示站消费入口在 src/App.tsx 中按loader、loader.kebabName、loader.component.name等顺序逐级兜底查询保证任一命名方式都能命中。历史脚本split-loaders.js 的来龙去脉仓库还保留了一个一次性迁移脚本 scripts/split-loaders.js它记录了组件库的演进历史早期所有加载动画挤在一个巨大的Loaders.tsx单文件中该脚本将其逐个export const拆分成独立的 kebab-case 文件如PulseDots→pulse-dots.tsx并统一补充了 React 与 framer-motion 的标准 import 头同时顺带生成了第一版loadersCode.ts。⚠️ 注意该脚本内含 Windows 绝对路径c:/Users/...仅用于历史迁移日常只需使用跨平台的 generate-loaders-code.js。什么时候必须重新生成新增 / 删除 / 重命名 loader 组件后修改了 loader 源码内容复制按钮需要同步最新代码重新生成后 diff 检查loadersCode.ts确认条目数量与预期一致即可。五、常见问题速查FAQQ本地启动后 3000 端口被占用npm run dev底层是vite --port3000 --host0.0.0.0可临时修改 package.json 中 scripts 的端口号。Q新增组件后用户无法通过 CLI 安装检查 registry/registry.json 中files.path是否与实际文件路径完全一致区分大小写。Q复制按钮拿到的代码是旧的说明忘了重新运行 scripts/generate-loaders-code.jsloadersCode 映射表尚未更新。Q样式不符合设计规范项目约定动画一律走motion包样式一律纯 Tailwind 类颜色 token 遵循现有明暗双主题体系详见 CONTRIBUTING.md 的 Code Guidelines。结语掌握了「registry 三件套」.tsx.jsonregistry.json条目和 loadersCode 生成链路你就具备了完整贡献 Amicro 的能力。建议先挑一个简单的 loader 仿写练手跑通npm run lint与npm run build后再发起 PR。祝你在 React 微交互的世界里玩得开心 【免费下载链接】Amicro--Micro-transitions-项目地址: https://gitcode.com/gh_mirrors/am/Amicro--Micro-transitions-创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考