安装

1. 准备光标的图片

   AnimeCursor 是一个能够根据用户的自定义设置，自动构建动画虚拟光标的 JavaScript 库。AnimeCursor 本身并不提供光标图片素材，所以使用 AnimeCursor 前，你需要先准备好光标的图片。

   AnimeCursor 支持两种动画光标的实现方法：精灵图动画 和 GIF 动图。
   当然，除了动画光标，AnimeCursor 也支持静态光标。

   • 精灵图动画

     精灵图动画是 AnimeCursor 推荐的方式，因为它与 GIF 图片相比有更好的视觉呈现以及更自由的发挥空间，并且可以更轻松的实现乒乓循环。AnimeCursor 未来的更新也会把重点放在精灵图动画光标的功能上。

     AnimeCursor 精灵图动画目前（v0.3.0）仅支持单行精灵图表，所以请确认你的精灵图表布局是否符合要求，如果不是单行精灵图表请将其编辑为单行。

     AnimeCursor 会自动根据你的设置来生成CSS帧动画，但是请注意，目前（v0.3.0）AnimeCursor 会自动根据设置的动画持续时间与动画帧数来平均分配帧持续时间，这就意味着每一帧都是关键帧而不存在补间帧，如果有比其他的帧持续时间更长的帧，则需要在精灵图表内存放多张重复的帧，这会导致图片的文件体积增加。所以如果有持续时间较长的帧，请斟酌是否要换为 GIF 动图以减少加载时间。

     我们将在未来的版本（由于将会有不向下兼容的API更新，版本预计为 v1.0.0）增加对多行精灵图表的支持以及自定义帧持续时间功能。

   • GIF 动图

     AnimeCursor 的工作原理使 GIF 动图也能作为动画光标的图片，如果你的动画光标有较长的静止状态，那么可以考虑使用 GIF 动图。

     对于 GIF 动图，AnimeCursor 没有什么特别的要求。但是请注意，GIF 动图和精灵图动画的呈现效果会有差别，所以可以根据需要来选择。

   • 像素风图片

     对于像素风格的光标，无论是精灵图动画还是 GIF 动图，AnimeCursor 都推荐使用原始尺寸的像素图（比如一个 16px × 16px 的像素图，不需要在图片编辑软件里缩放处理成 64px × 64px 的尺寸再给 AnimeCursor 加载）。AnimeCursor 支持缩放光标以及像素化渲染图片，结合这两个功能，你可以以很小的文件体积实现动画光标效果，大大节省页面的加载时间。

2. 部署 AnimeCursor

   • CDN

     通过 jsDeliver 的 npm CDN 直接获取最新版本的 AnimeCursor

     <script src="https://cdn.jsdelivr.net/npm/anime-cursor/dist/anime-cursor.umd.min.js"></script>

     或者通过 jsDeliver 的 github release CDN 获取指定版本的 AnimeCursor

     <script src="https://https://cdn.jsdelivr.net/gh/ShuninYu/anime-cursor@v0.3.1/dist/anime-cursor.umd.min.js"></script>

   • npm

     npm i anime-cursor

     import AnimeCursor from 'anime-cursor';
     new AnimeCursor({...});

   • 本地部署

     AnimeCursor 的体积很小，所以当 jsDeliver 的 CDN 在你的地区速度较慢时，你也可以选择本地部署 AnimeCursor

     <!-- 别忘了把 src 修改为你的文件路径 -->
     <script src="anime-cursor.umd.min.js"></script>

基本用法

初始化 AnimeCursor：

new AnimeCursor({
    // 配置区域
});

在 配置区域 通过 cursors 配置你的 AnimeCursor：

cursors: {
    // 光标种类声明区域
}

在 光标种类声明区域 通过 cursors 声明你的光标种类：

cursorTypeOne: {
    // 光标参数区域
},
/* 注意不要忘记在两个光标种类之间添加逗号 */
cursorTypeTwo: {
    // 光标参数区域
}

在对应光标种类的 光标参数区域 参考 配置：参数选项 来配置光标的参数：

一个包含两种光标的 AnimeCursor 的 配置结构 应该看起来像这样：

new AnimeCursor({
    cursors: {
        cursorTypeOne: {
            // settings
        },
        cursorTypeTwo: {
            // settings
        }
    }
});

示例

一个最小可运行示例：

new AnimeCursor({
    cursors: {
        pointer: {
            tags: ['a','button']
            size: [32,32],
            image: 'cursor_pointer.png',
            default: false
        }
    }
});

用通俗的话来说，在这段代码中我们设置了一种叫做 pointer 的光标。这个光标的尺寸为 32 × 32 像素，图片是 cursor_pointer.png，它会在光标移动到 a 元素和 button 元素上时显示。

请注意，假设 cursor_pointer.png 是一张精灵图表，在这个示例的情况下 pointer 仍然只会是静态光标，因为它缺少一些精灵图动画光标必须的参数设置，具体原因我们接下来就会提到。

下面是一个更丰富且更贴近实际应用的示例，包含了四种光标：

new AnimeCursor({
    cursors: {
        default: {
            size: [32,32],
            image: 'https://example.com/cursor_default.gif',
            pixel: true,
            default: true
        },
        pointer: {
            tags: ['a','button'],
            size: [32,36],
            image: 'https://example.com/cursor_pointer.png',
            frames: 3,
            duration: 0.3,
            pingpong: true,
            offset: [10,4],
            pixel: true
        },
        text: {
            tags: ['p','h1','h2','h3','h4','span','td','th','pre','code','footer'],
            size: [32,32],
            image: 'https://example.com/cursor_text.png',
            offset: [10,16],
            pixel: true
        },
        special: {
            size: [48,32],
            image: 'https://example.com/cursor_special.png',
            frames: 24,
            duration: 2,
            offset: [24,16],
            pixel: true
        }
    }
});

上面的代码中包含了 default pointer text special 四种光标。

在这四种光标中，只有 pointer 和 special 设置了 frames 和 duration。这是因为它们是 PNG 精灵图动画光标，而在 AnimeCursor 中，frames 和 duration 是精灵图动画光标必须设置的参数，当缺少二者其中任意一个参数时，该种光标都将以静态呈现。而 default 光标虽然没有设置 frames 和 duration，但是它的 image 指向的图片是一张 GIF 动图，所以 default 光标会以 GIF 的动画呈现（动画效果由 GIF 本身决定）。

不知道你是否注意到：除了被设置成默认光标的 default 以外，special 也同样没有设置 tags，因此它只能在被手动添加了 data-cursor="special" 的元素触发。

这里只是对 AnimeCursor 配置的简要说明，对于更详细的 AnimeCursor 初始化配置，请参考 配置 页面。