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

把鼠标移到一旁，页面上的狐狸也转头看过去；点一下，它眨眼，再换一个表情。page-mascot 就是这样一个 React 吉祥物组件，用两张精灵表完成方向与表情切换，适合个人主页、作品集和产品介绍页里的小角色。它不需要额外动画库，页面位置和角色素材则由接入项目安排。

先接入一组现成角色

当前包配置为 0.1.0，要求 React 18+、Node.js 20+。在已有 React 项目中安装组件，再从演示页选一组角色，将两张 WebP 图片放进项目的静态资源目录：

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"
/>

示例假设应用能从 /mascots/ 提供文件。图片放进 public/mascots 后，浏览器地址通常不会再包含 public；具体仍以框架的静态资源规则为准。使用构建工具导入图片也可以，把导入后的地址传给属性即可。

directions 与 reactions 必填，分别指向方向表和表情表；两张必须是同一角色的一组素材。
size 控制正方形显示尺寸，默认 140 像素。
label 用于按钮的可访问名称，默认是 mascot；它不是显示在角色旁的字幕。
className 接入项目的布局样式。组件内部已有行内样式，外部仍可安排容器位置、留白和页面层级。

角色是否固定在角落、跟着页面滚动，或摆在 Hero 文案旁边，属于页面布局问题。组件没有内置拖拽和角色管理后台，不能只传一个图片地址就期待获得整套桌面宠物功能。

两张九宫格，是角色动作的基础

方向表的九个格子按行排列：左上、上、右上；左、中、右；左下、下、右下。组件根据角色中心与指针的角度选择其中一格，用 CSS 背景位置切换画面。指针进入中心附近的 70 像素区域时，角色回到正视；方向迟滞则减少扇区边界附近来回切换的抖动。

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

表情表另存眨眼、爱心、闪光、惊讶、眨一只眼、害羞、困倦、眩晕和开心。当前点击逻辑先眨眼，再随连续点击次数显示爱心、闪光或开心；短时间连续点击四次会进入眩晕反应。素材表里有九种表情，不等于默认交互会依次播放全部九种。想增加业务状态触发，应修改组件逻辑，不能只新增一格图片。

两个图层一直挂载，表情层不会等首次点击才临时建立。方向追踪和按压回弹是两种机制：前者选图片格子，后者用 Web Animations API 改变缩放。读源码时沿着 aim 与 boop 两段看，就能分清改方向判断和改点击反应的入口。

自定义角色，先对齐，再换风格

同一只角色需要方向表与表情表共同保持比例、中心点、肩部范围和留白。若方向图里头部偏左，表情图里偏右，点击时就会像整只角色跳了一下；即使两张都很漂亮，也不能解决对齐问题。

先确定角色外形、显示范围与九宫格顺序，保留两张图共有的尺寸与定位。
绘制九个方向和九种表情，检查切换时头部、身体和边距是否一致。
按同一网格合成两张表，放回组件中确认格子顺序与实际显示。

仓库提供 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

配套 page-mascot Skill 可以指导支持图片生成的代理制作并接入角色。绘制依赖图片工具，重建素材还可能进入 Python 图像处理流程；普通 npm 接入只需要 React 与现成素材，不必先准备这套生成环境。本文展示接入与源码关系，没有安装 Skill 或生成新角色。

桌面追踪、触屏点击与减少动画

视线追踪只在设备匹配 (hover: hover) and (pointer: fine) 时启用。触屏设备通常不满足这个条件，但仍可触发按钮点击反应；移动端设计应按这种降级来安排，不能让一个必须悬停才能理解的提示只交给角色。

组件使用 button，通过 aria-label 提供名称。用户开启 prefers-reduced-motion: reduce 后，按压回弹停止，表情切换仍保留。接入页面时还要保留键盘焦点可见性，别让角色遮住表单、导航或正文。

仓库采用 MIT 许可，分发软件的相应副本时保留版权与许可声明。自行绘制第三方 IP、品牌角色或真人形象时，素材权利另外确认。把配套素材纳入自己的静态资源和版本管理，后续换角色或更新组件才容易保持对应。

项目与组件说明：https://github.com/nilbuild/page-mascot
演示与角色选择：https://koboyo.com/page-mascot
组件实现：https://github.com/nilbuild/page-mascot/blob/main/src/mascot.tsx

1.本站所发布资源部分收集于网络，仅限用于学习和研究测试使用。2.本站资源售价仅为赞助网站，赞助收费仅用于网站维护运营更新，感谢您的支持。3.本站仅保证资源的正常下载和测试使用，售后不包含相关技术咨询服务，请知悉谅解。4.本站所发布资源为非实物商品，不接受退款，请考虑好再进行支付赞助获取下载。
赞助获取下载注意：
1.支付赞助成功后请勿关闭窗口或其他操作，等待系统自动确认，按钮变为获取下载按钮。2.游客操作请使用 Chrome、Edge 或 FireFox 浏览器，以免支付刷新失败(浏览器缓存7天有效)。3.如支付赞助成功后刷新无法显示下载按钮、链接失效等问题请到 【公告留言】 处理或参考下载说明文档。

THE END