贡献者必读：如何为Its Hover图标库提交新的动画图标

贡献者必读：如何为Its Hover图标库提交新的动画图标

【免费下载链接】itshoverIcons that move with intent项目地址: https://gitcode.com/gh_mirrors/it/itshover

Its Hover是一个专注于动画图标的开源项目，通过生动的交互效果为用户界面增添活力。本指南将帮助你轻松贡献新的动画图标，即使你是开源新手也能快速上手。

准备工作：开发环境搭建

在开始贡献前，请确保你的开发环境满足以下要求：

• Node.js 18+ 和 npm
• Git 版本控制工具
• 代码编辑器（推荐VS Code）
• 基本的Next.js、TypeScript和shadcn/ui知识

首先，克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/it/itshover cd itshover

安装依赖并启动开发服务器：

npm install npm run dev

打开浏览器访问 http://localhost:3000，你应该能看到Its Hover的主页面。

图1：Its Hover项目主页展示了丰富的动画图标库

核心步骤：创建你的第一个动画图标

步骤1：创建图标组件文件

在icons/目录下创建新的TypeScript JSX文件，文件名需使用kebab-case格式，例如heart-beat-icon.tsx。

图标组件需要遵循固定模板，包含动画逻辑和SVG路径：

import { forwardRef, useImperativeHandle } from "react"; import type { AnimatedIconHandle, AnimatedIconProps } from "./types"; import { motion, useAnimate } from "motion/react"; const HeartBeatIcon = forwardRef<AnimatedIconHandle, AnimatedIconProps>( ( { size = 24, color = "currentColor", strokeWidth = 2, className = "" }, ref, ) => { const [scope, animate] = useAnimate(); const start = async () => { // 这里添加你的动画逻辑 await animate(".icon-group", { scale: [1, 1.2, 1] }, { duration: 0.8 }); }; const stop = () => { // 停止动画的逻辑 animate(".icon-group", { scale: 1 }, { duration: 0.2 }); }; useImperativeHandle(ref, () => ({ startAnimation: start, stopAnimation: stop, })); return ( <motion.svg ref={scope} onHoverStart={start} onHoverEnd={stop} xmlns="http://www.w3.org/2000/svg" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke={color} strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" className={`inline-flex cursor-pointer items-center justify-center ${className}`} style={{ overflow: "visible" }} > <motion.g className="icon-group" style={{ transformOrigin: "center" }}> {/* 这里添加你的SVG路径 */} <path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z" /> </motion.g> </motion.svg> ); }, ); HeartBeatIcon.displayName = "HeartBeatIcon"; export default HeartBeatIcon;

关键要求：

• 使用forwardRef和AnimatedIconHandle类型
• 实现startAnimation和stopAnimation方法
• 使用motion库创建动画效果
• 保持与现有图标一致的代码风格

步骤2：注册新图标

新图标需要在三个地方进行注册：

1. 在icons/index.ts中添加导入和ICON_LIST条目：

// 添加导入 import HeartBeatIcon from "./heart-beat-icon"; // 在ICON_LIST数组中添加 { name: "heart-beat-icon", icon: HeartBeatIcon, keywords: ["heart", "beat", "pulse", "love", "health"], }

2. 在lib/icons.ts中添加路由信息：

{ name: "heart beat icon", path: "/icons/heart-beat-icon", }

3. 运行命令生成注册表：

npm run registry:build

这个命令会自动更新registry.json并在public/r/目录下生成相应的JSON文件。

图2：图标注册流程确保新图标能被正确索引和展示

步骤3：测试你的图标

启动开发服务器后，访问 http://localhost:3000/icons 查看你的新图标是否正确显示：

npm run dev

验证以下内容：

• 图标在画廊中可见
• 悬停动画正常工作
• 点击图标能进入详情页
• 控制台没有错误信息

你还可以创建测试项目验证图标作为库的使用情况：

npx create-next-app@latest test-consumer --typescript --tailwind --app cd test-consumer npm install motion npx shadcn@latest init --defaults npx shadcn@latest add "http://localhost:3000/r/heart-beat-icon.json"

代码质量与提交规范

代码检查

提交前务必运行以下命令确保代码质量：

# 代码格式化 npm run format # 代码检查 npm run lint # 类型检查 npm run typecheck # 构建测试 npm run build # 一键运行所有检查 npm run check

提交规范

使用约定式提交格式：

<type>: <subject>

类型包括：

• feat: 新功能（新图标）
• fix: 错误修复
• docs: 文档更新
• style: 代码风格修改
• refactor: 代码重构
• perf: 性能优化
• chore: 维护任务

示例：

feat: add heart-beat-icon with pulse animation

提交PR

1. 创建特性分支：

git checkout -b feature/heart-beat-icon

2. 提交更改并推送到远程：

git add . git commit -m "feat: add heart-beat-icon with pulse animation" git push origin feature/heart-beat-icon

3. 在GitCode上创建Pull Request，使用提供的PR模板填写必要信息。

图3：PR提交前请确保所有检查项都已完成

常见问题与解决方案

图标不显示在画廊中

• 检查icons/index.ts中的ICON_LIST是否正确添加
• 确保运行了npm run registry:build
• 检查图标组件是否有语法错误

动画不工作

• 确保正确导入了motion库
• 检查动画逻辑是否正确实现
• 验证startAnimation和stopAnimation方法是否通过useImperativeHandle暴露

类型错误

• 确保所有接口和类型定义正确
• 运行npm run typecheck检查类型问题
• 参考现有图标组件调整类型定义

总结

通过以上步骤，你已经掌握了为Its Hover图标库贡献新动画图标的完整流程。从环境搭建到代码提交，每一步都至关重要。记住，好的动画图标应该不仅视觉上吸引人，而且交互体验流畅自然。

如果你在贡献过程中遇到任何问题，可以查看项目的CONTRIBUTING.md或在Issue中提问。我们期待看到你的创意贡献，让Its Hover图标库更加丰富多样！

图4：丰富的动画图标为用户界面带来生动体验

【免费下载链接】itshoverIcons that move with intent项目地址: https://gitcode.com/gh_mirrors/it/itshover