鼠标美化（mouse）使用文档

作者：kuakeba.cn | 版本：1.0.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

为网站提供个性鼠标箭头样式：通过 renderAssets 钩子向全站前台注入光标样式与特效，零侵入不修改任何宿主模板。

• 6 套内置预设：经典蓝 / 霓虹发光 / 樱花粉 / 暗夜紫 / 极简白 / 活力橙，箭头与「可点击指针」成套配色
• 自定义鼠标图片：支持填写自己的 PNG / SVG / CUR 图片 URL（箭头与指针可分别设置）
• 5 种点击特效：波纹扩散 / 星星迸发 / 烟花绽放 / 爱心飘散 / 气泡上升，粒子引擎驱动，颜色可配
• 智能区分：普通区域显示箭头，链接/按钮/可点击元素显示指针，文本输入框保留系统文本光标
• 纯 CSS/JS 实现，无数据表、无后台菜单，安装即用

二、快速开始

1. 将 mouse 目录放入 plugins/，后台 应用中心 → 鼠标美化 → 安装
2. 到 应用中心 → 鼠标美化 → 配置 选择喜欢的样式（默认「经典蓝」），保存
3. 刷新前台任意页面即可看到个性鼠标箭头

三、配置项说明

四、实现说明（零侵入机制）

• 通过 renderAssets 钩子向全站前台输出 <style id="zs-mouse-style"> 与可选的 <script id="zs-mouse-fx">，不修改任何模板文件
• 内置预设为 SVG data URI 光标（cursor: url("data:image/svg+xml,...") x y），无需托管图片文件，任意分辨率下清晰
• 光标选择器覆盖：html,body 箭头 → a,button,[role="button"],.btn,select,label,summary,input[type=submit/button/checkbox/radio] 指针 → input,textarea 保留系统文本光标
• 点击特效基于 Web Animations API 粒子引擎：星星 8 颗环绕迸发（多彩 + 辉光）、烟花 16 粒径向绽放、爱心 3 颗上浮飘散、气泡 6 枚上升消散、波纹单环扩散；所有粒子 pointer-events:none，动画结束自动移除节点，不影响页面交互

五、常见问题

Q：Safari 里鼠标没变化？

Safari 不支持 SVG 光标。如需全浏览器兼容，请使用「自定义箭头图片」填写 PNG/CUR 格式的图片 URL（PNG 光标全浏览器支持；SVG 光标仅 Chrome/Edge/Firefox 支持）。

Q：自定义图片不显示？

确认 URL 可公网访问、图片尺寸建议 ≤ 32×32（部分浏览器对超大光标有 128px 上限限制），SVG 需在根元素写明 width/height。

Q：会管理员后台也生效吗？

不会。样式仅注入前台（renderAssets 钩子），后台管理界面保持系统默认鼠标，不影响操作体验。

Q：之前配置过「点击波纹特效」开关，升级后开关去哪了？

波纹开关已升级为「点击特效」下拉选择；重新到配置页选择特效并保存即可（旧开关配置自动失效，无需处理）。