配置

光标类型

cursors 是 AnimeCursor 的核心配置项。每一个 key 表示一种光标类型，对应一个 CSS class
（cursor-${type}，由 AnimeCursor 自动生成）。光标类型的名称完全由你来决定，只要符合 JavaScript 的标准，任何名称都不会影响效果。

cursors: {
    default: { ... },
    pointer: { ... },
    text: { ... },
    cursorForFun: { ... }
}

要让这些光标真正起效，你还需要对它们进行基础的参数配置，以告诉 AnimeCursor 你希望这些光标以什么样的效果呈现。

参数选项

所有光标参数

下面的表格列出了 AnimeCursor 为光标预留的所有参数选项，可以用来快速参考，对于每个参数更详细的介绍请见下文。

选项	类型	必填项	选项介绍	留空时的行为
size	[number, number]	✅	光标尺寸[宽,高]（像素）	报错
image	string	✅	光标图片路径	报错
tags	string[ ]		生效的 HTML 标签	AnimeCursor 只会在被手动设置了 data-cursor 的元素上时才会切换到该光标
default	boolean	⚠️	光标是否是默认光标 ⚠️最多只能设置一个默认光标	与设置该项为 false 相同
frames	number		精灵图动画帧数	光标不会生成精灵图动画
duration	number		精灵图动画循环时长	光标不会生成精灵图动画
pingpong	boolean		精灵图动画是否乒乓循环	精灵图动画将以默认方式循环
offset	[number, number]		光标偏移[向右,向下]（像素）	光标指针位置默认左上角
scale	[number, number]		光标缩放倍数[横向,纵向]	光标保持 size 设定尺寸
pixel	boolean		是否启用像素渲染（pixelated）	原尺寸像素图平滑边缘
zindex	number		为光标单独设置层级（<body>层面）	默认设置为最大层级-1

参数介绍

size

size 是光标参数中的一个必填项，它表示此参数所属光标的尺寸(单位像素)。

格式：
```
size: [sizeX , sizeY]
```
示例：
```
size: [32 , 32]
```
上面的示例表示：该参数所属的光标的尺寸为 32px × 32px，且如果该光标为精灵图动画光标，则精灵图的帧尺寸为 32px × 32px。
image

image 是光标参数中的一个必填项，它表示此参数所属光标的图片路径。

格式：
```
image: 'path-to-your-image';
```
示例：
```
// 可以是相对路径
image: '/image/cursor/cursor-image.png';
```
```
// 或者是绝对路径
image: 'https://example.com/image/cursor/cursor-image.png';
```
上面的两个示例表示：该参数所属的光标的图片路径为 /image/cursor/cursor-image.png（第一个示例）、https://example.com/image/cursor/cursor-image.png（第二个示例）。

如果是精灵图动画光标，请确保 image 的图片是精灵图表，而不是精灵图的某一帧或者一个文件夹。

AnimeCursor 推荐使用绝对路径来设置光标图片。如果网站有多层的页面结构，使用相对路径可能导致 AnimeCursor 的图片路径不匹配，这个问题是可以通过使用绝对路径来避免的。
tags

tags 是光标参数中的一个非必填项，它表示鼠标指针指在哪些 DOM 元素上时，AnimeCursor 会把光标切换为此参数所属光标。它的工作原理是：初始化或刷新 AnimeCursor 时，AnimeCursor 会为 tags 中设置的元素自动添加该种光标的 data-cursor（除非元素已经有 data-cursor），当光标移动到含有 data-cursor 的元素上时，AnimeCursor 会自动识别该元素所属的光标种类，并切换到该光标。

当未设置 tags 时，AnimeCursor 将不会为 HTML 中的任何元素添加该种光标的 data-cursor，如果需要触发此光标，请为触发元素手动添加 data-cursor。

格式：
```
tags['tag-1' , 'tag-2' , 'tag-3']
```
示例：
```
// AnimeCursor 将在鼠标指针指向 a元素 button元素 和 span元素 时将光标切换到该参数所属光标
tags['a' , 'button' , 'span']
```
上面的示例表示：AnimeCursor 将在鼠标指针指向 a元素 button元素和 span元素时将光切换到该参数所属光标。

假设该 tags 参数属于 pointer 光标，那么当鼠标指针指向下面任何一个元素之一时：
```
<a href="/">A element</a>
<button type="button">BUTTON element</button>
<span>SPAN element</span>


<div data-cursor="pointer"></div>
```
AnimeCursor 会自动切换到 pointer 光标。

default 参数设置为 true 的光标会自动被 AnimeCursor 应用到所有没有被声明过的情况中。

tags 中设置的元素标签是全局不可重复的。
如果某种元素标签已经在某个光标中被声明过，那么在其他光标中就不可以被再次声明，即不同的光标不能有相同的目标元素标签。
default

default 是光标参数中的一个非必填项，当该参数设置为 true 时，它表示此参数所属光标是默认光标。

未设置该参数时，表现与设置该项为 false 相同，AnimeCursor 不会把此参数所属光标当做默认光标。

AnimeCursor 最多只能将一个光标设置为默认光标，如果有一个以上的光标被设置为默认光标，AnimeCursor 将会报错。

格式：
```
default: true-or-false;
```
示例：
```
default: true;
```
上面的示例表示：该参数所属的光标为默认光标。

默认光标不需要设置 tags 参数。AnimeCursor 推荐默认光标不要设置 tags 参数，因为 tags 参数不会影响默认光标的切换逻辑，但是给默认光标设置此参数可能导致与其他光标产生目标冲突。
frames

frames 是光标参数中的一个非必填项，但是精灵图动画光标必须配置该项，它表示此参数所属光标的精灵图动画所包含的帧数量（一个循环内）。

格式：
```
frames: frames-count;
```
示例：
```
frames: 6;
```
上面的示例表示：该参数所属的光标的精灵图动画一个循环有6帧。
duration

duration 是光标参数中的一个非必填项，但是精灵图动画光标必须配置该项，它表示此参数所属光标的精灵图动画的时长（一个循环内，单位秒）。

格式：
```
duration: loop-length;
```
示例：
```
duration: 2;
```
上面的示例表示：该参数所属的光标的精灵图动画一个循环的时长为2秒钟。

只有 frames 和 duration 两个参数都被合法的配置的时候，AnimeCursor 才会将光标视为精灵图动画光标处理。缺少任何一个参数，或者有参数被不合法的设置的时候，AnimeCursor都会报错。

pingpong

pingpong 是光标参数中的一个非必填项，它表示此参数所属光标是否启用了乒乓循环。

未设置该参数时，表现与设置该项为 false 相同，该参数所属光标如果是精灵图动画光标，动画结束后会从头开始循环。

GIF 动图的播放由图片本身控制，AnimeCursor 不会改变 GIF 动图，所以给 GIF 动图设置该项是无效的。

格式：
```
pingpong: true-or-false;
```
示例：
```
pingpong: true;
```
上面的示例表示：该参数所属的光标如果是精灵图动画光标，则启用乒乓循环。
offset

offset 是光标参数中的一个非必填项，它表示此参数所属光标的指针偏移（单位像素）。

格式：
```
offset: [offsetX , offsetY]
```
示例：
```
offset: [5 , 10]
```
上面的示例表示：该参数所属的光标的指针偏移为横向 5px，纵向 10px。且如果该光标为精灵图动画光标，则精灵图的帧尺寸为 32px × 32px。
scale

scale 是光标参数中的一个非必填项，它表示此参数所属光标的缩放倍数。

格式：
```
scale: [scaleX , scaleY]
```
示例：
```
scale: [2 , 0.5]
```
上面的示例表示：该参数所属的光标的缩放为横向 2倍，纵向 0.5倍。
pixel

pixel 是光标参数中的一个非必填项，它表示此参数所属光标是否启用了像素化渲染。

未设置该参数时，表现与设置该项为 false 相同，该参数所属光标会使用浏览器默认的渲染方式。

对于像素风光标，使用原尺寸像素图，将 pixel 启用并设置缩放，可以节省文件体积以缩短加载时间。

格式：
```
pixel: true-or-false;
```
示例：
```
pixel: true;
```
上面的示例表示：该参数所属的光标的图像将启用像素化渲染。
zindex

zindex 是光标参数中的一个非必填项，它表示为此参数所属光标单独设置层级。

格式：
```
zindex: number;
```
示例：
```
zindex: 10;
```
上面的示例表示：该参数所属的光标的 z-index 被单独设置为10。

对于需要光标被部分元素遮挡的情况，设置该项的时候需要注意：z-index 的值只有在同一个堆叠上下文（stacking context）中才有意义，而 AnimeCursor 的光标元素是 <body> 的直接子元素。

为 AnimeCursor 增加一个可以决定光标元素注入位置的配置项和API也许可行，但是这可能并不是我开发 AnimeCursor 的方向，所以注入定位功能极有可能不会被添加。

全局选项

除了光标本身之外，AnimeCursor 还提供了少量与 cursors 同级的全局选项：

什么是全局选项

选项	类型	默认值	选项介绍
debug	boolean	false	启用debug覆盖
displayOnLoad	boolean	false	控制光标在检测到鼠标移动前是否显示
enableTouch	boolean	false	是否在触屏设备启用

全局选项介绍

debug

非常重要的一个选项，设置为 true 启用debug模式。

debug模式会显示鼠标指针的真实位置以及当前光标类型，以帮助纠正对齐偏移量或排除其他错误。
displayOnLoad

设置光标在检测到鼠标移动前是否显示，如果启用此项，在检测到鼠标（在视窗内）移动前将保持在页面左上角。

光标 DOM 在初始化时被插入后位置在左上角，鼠标在视窗中移动时才会修正到鼠标位置，这在视觉上是不舒服的。鼠标在视窗内移动再开始显示是一种比较好的处理方法，所以一般不需要设置 displayOnLoad。
enableTouch

用于启用移动触屏设备上的动画光标。

AnimeCursor 会自动识别移动触屏设备（比如手机、平板电脑）并默认屏蔽这些设备上的动画光标。如果你想在这些设备上显示动画光标，可以添加 enableTouch: true。

如何设置全局选项

由于全局选项与光标类型同级，所以设置全局参数时需要注意代码格式：

✅合法的格式：

new AnimeCursor({
    debug: true, // 与cursors同级，格式正确
    enableTouch: false, // 与cursors同级，格式正确
    cursors: {
        default: {
            size: [32,32],
            image: 'i/cursor/cursor_default.gif',
            pixel: true,
            default: true
        },
    }
});

一个设置了全局选项的 AnimeCursor 初始化应该看起来像上面的例子。

❌非法的格式：

new AnimeCursor({
    cursors: {
        debug: true, // 包裹进了cursors内，位置错误
        default: {
            size: [32,32],
            image: 'i/cursor/cursor_default.gif',
            pixel: true,
            default: true,
            enableTouch: false // 包裹进了光标设置内，位置错误
        },
    }
});

而这上面是一个错误示范，注意 debug 和 enableTouch 在代码中的位置和注释文本。

光标类型

参数选项

所有光标参数

参数介绍

size

image

tags

default

frames

duration

pingpong

offset

scale

pixel

zindex

全局选项

什么是全局选项

全局选项介绍

debug

displayOnLoad

enableTouch

如何设置全局选项

✅合法的格式：

❌非法的格式：