page-mascot | 让网页角色追随光标的 React 吉祥物组件

page-mascot 是一个面向 React 项目的交互式网页吉祥物组件：角色会根据鼠标相对位置转动视线，点击后切换眨眼、爱心、惊喜等表情，并配合轻微的按压回弹动画。它适合放在作品集、个人主页、产品 Hero 区或空状态页面中，用很少的接入代码增加一个能回应用户的角色。

截至 2026 年 9 月 21 日核对，仓库默认分支为 main，package.json 中的 npm 包版本为 0.1.0，要求 React 18 或更新版本、Node.js 20 或更新版本。GitHub 暂无 Release 与 tag，因此 0.1.0 是包配置中的版本号，不应理解为仓库已经发布了同名 GitHub Release。根目录采用 MIT License。

page-mascot 如何让角色追随光标

每个角色由两张 3×3 精灵表组成：第一张保存左上、上、右上、左、中、右、左下、下、右下九个头部方向；第二张保存眨眼、爱心、闪光、惊讶、眨一只眼、害羞、困倦、眩晕和开心九种表情。组件始终渲染两个图层，通过改变 CSS background-position 选择单元格，而不是为每个方向加载单独图片。

鼠标移动时，组件根据角色中心到指针的角度选择八个方向之一；指针进入约 70 像素的中心死区后，角色回到正视状态。代码还加入方向迟滞，避免指针停在两个扇区边界附近时频繁抖动。点击角色会先眨眼，再按点击次数轮换爱心、闪光和开心；短时间内连续点击四次则显示眩晕表情。

page-mascot 狐狸角色的九个视线方向与九种点击表情精灵表 — 官方 README 展示的两张精灵表：左侧为九个视线方向，右侧为九种点击表情。来源：https://github.com/nilbuild/page-mascot/blob/main/.github/sheets.png

安装与最小接入方式

在现有 React 项目中安装 npm 包：

npm i page-mascot

然后准备同一角色的方向表与表情表，把它们放进项目可公开访问的目录，再将路径传给组件：

import { Mascot } from 'page-mascot'

<Mascot
  directions="/mascots/fox-directions.webp"
  reactions="/mascots/fox-reactions.webp"
  size={140}
  label="fox mascot"
/>

directions 与 reactions 是必填属性，可以是静态资源路径，也可以是构建工具导入后的图片地址；size 默认值为 140 像素，label 默认值为 mascot，还可通过 className 接入项目自己的定位与布局样式。组件内部使用行内样式，因此不依赖额外 CSS 框架。

现成角色、自定义角色与 Agent Skill

项目演示页提供 52 个已绘制角色。选中角色后，需要同时下载对应的 *-directions.webp 和 *-reactions.webp；两张图是一组，不能只替换其中一张。仓库还提供 page-mascot Agent Skill，可指导支持图片生成能力的编码代理绘制九方向和九表情源图、合成对齐后的精灵表，并把组件接入页面。

自定义绘制并不是生成一张头像就结束。两张源图需要保持相同角色、比例、中心点、肩部范围和边距，否则点击切换图层时会发生跳位。仓库技能支持 colour、ink、sketch、riso、paper 与 pixel 六种表现方式，但同一角色的方向表和表情表应使用同一种风格。

page-mascot 狐狸角色的彩色、墨线、素描、Riso、纸艺与像素六种风格 — 同一只狐狸在 colour、ink、sketch、riso、paper 与 pixel 六种风格中的正面和侧面效果。来源：https://github.com/nilbuild/page-mascot/blob/main/.github/styles.png

交互、可访问性与移动端边界

吉祥物本身使用 button 元素，并通过 aria-label 暴露可访问名称。点击时的缩放回弹由 Web Animations API 完成；系统开启 prefers-reduced-motion: reduce 后，组件仍显示表情变化，但不播放按压动画。表情精灵层一直挂载，可避免第一次点击时才临时请求图片。

光标追踪只在设备匹配 (hover: hover) and (pointer: fine) 时启用，所以触屏手机和平板通常不会运行视线跟随；点击或触摸反应仍由按钮事件负责。这是合理的降级策略，但也意味着项目的核心“看向鼠标”效果主要面向桌面浏览器。组件没有内置固定定位、拖拽、语音、复杂状态机或角色管理后台，页面中的位置与业务逻辑仍需由接入方实现。

技术组成与二次开发门槛

npm 交付物的核心是 TypeScript/React 组件，运行时只要求 React，不引入动画库。仓库统计把 Python 列为占比最高的语言，主要与角色生成、精灵表处理和验证脚本有关；这不代表把组件接入网页需要 Python。普通使用者只需 React 与两张 WebP 精灵表，只有绘制或重建自定义角色时才会进入 Python、Pillow、NumPy、SciPy 及图片生成工具相关流程。

从实现规模看，page-mascot 更像一个专注单一交互的小组件，而不是完整的虚拟角色框架。优点是依赖少、素材格式明确、组件可直接嵌入；限制是角色资源需要自己托管，自定义角色对两张精灵表的一致性要求较高，且当前仓库尚未建立 GitHub Release 版本线。用于生产项目时，建议锁定 npm 版本或具体提交，并把角色素材纳入自己的静态资源与缓存策略。

MIT 许可边界

仓库根目录的 MIT License 允许使用、修改、合并、发布、分发、再许可和销售软件副本，但复制或分发软件及其实质部分时需要保留版权与许可证声明。许可证同时明确软件按“原样”提供、不附带担保。若自行生成真人肖像、品牌角色或第三方 IP 吉祥物，还需要另外确认肖像权、商标与角色版权，不能只依赖代码仓库的 MIT 许可。