概览
本指南会带你了解 PicoPixel 中 sprite 的所有基础：它是什么、什么时候该用、如何一步步构建自己的 sprite、如何让它对屏幕上发生的事作出反应，以及如何复用它，避免重复制作同一个东西。
不需要动画经验。如果你能拖放图片，就能制作 sprite。
是什么？
sprite 是一个 PicoPixel widget，它包含多个不同动画，并允许你随时在它们之间切换。每个动画叫做一个 mode 或 state，例如 "Idle"、"Running" 或 "Happy"。
可以把它想成电子游戏里的角色。屏幕上的角色是同一个，但它可以根据情况走路、跳跃或挥手。sprite 也是这样：一个 widget，多种外观，由你决定播放哪一个。
使用 PicoPixel 强大的 event editor，你可以触发不同 state，让 sprite 更有生命力！
示例：假设你有一个动画角色，或者想为 ESP32 或其他 LVGL 应用制作自己的 stack-chan 表情。你可以用一个 sprite，根据条件触发 "Running"、"Thinking"、"Failed" 等不同 mode，而不需要管理一堆独立 widget。
从技术上说，LVGL 原生并不支持带不同 state 的 sprite，因此我们基于 LVGL animated image widget 构建了自己的实现。你可以获得便利性，而不必亲自把这些逻辑接起来。
什么时候应该使用 sprite？
不是每张图片都需要做成 sprite。下面是一个快速判断方式：
- 单张静态图片？ 使用普通 Image。对于永远不动的东西，sprite 太重了。
- 一个永远循环的动画（比如旋转加载器）？使用 Animated Image。它更简单也更轻。
- 需要根据情况变化的东西，例如任务成功时微笑的脸，或从 idle 切换到 running 的角色？这正是 sprite 的用途。
经验法则：如果你的图形有不止一种 "mood" 或 "behavior"，并且你想在它们之间切换，就使用 sprite。
如何创建 sprite？
- 选择 "Sprite" widget。在右侧边栏中，你可以添加这个 sprite 的第一个 mode。例如第一个 state 可能是 "Idle"。请为每个 state 起清晰的名字，方便之后设置 triggers。
- 上传一组图片序列，也就是组成这个 mode 的帧。每一帧都是一张图片，按顺序播放它们就会形成像翻页动画一样的效果。
- 你可以调整该 state 的 duration。更长的 duration 会让动画更慢；更短则更快。
- 添加另一个 state。sprite 至少需要 2 个 mode。（如果你永远只需要一个动画，更适合使用 Animated Image widget，见上面的 When should I use a sprite?。）
- 使用 Events tab/editor 按条件触发并切换不同 state。这会让 sprite 看起来有生命，下一节会继续说明。
一个 sprite 的所有 mode 中，所有图片或帧都必须共享完全相同的尺寸。如果一帧是 64×64，另一帧是 80×80，sprite 就无法正确对齐。上传前请先统一尺寸。
请让帧数和图片尺寸保持合理。更多帧、更大图片会更平滑，但会占用设备更多内存，尤其是小型微控制器。若刷入后 sprite 不显示，请看 Common issues。
让 sprite 动起来
只显示一种 state 的 sprite 没有太大意义。真正神奇的部分，是告诉它 什么时候 切换，这正是 Events editor 的用途。
思路很简单：当某件事发生时，切换到某个 state。 你选择那个 "something"（按钮按下、值变化、定时器等），PicoPixel 处理其余部分。
一个典型例子：
- 你的 sprite 默认从 "Idle" state 开始。
- 在 Events editor 中添加一个 event：按钮被按下时，将 sprite 切换到 "Running" state。
- 再添加一个 event：任务完成时，切换到 "Happy"（或回到 "Idle"）。
就是这样。无需你写代码，sprite 就能对用户操作作出反应。你可以串接任意数量的事件，构建真正有表现力的 widgets。
从小处开始。先让两个 state 来回切换，在 preview 中确认效果正确，再在满意后添加更多 state。
如何复用 sprite？
构建好 sprite 后，你大概不想在每个项目里从头再做一遍。Library 功能可以让你保存一次，然后放入任何项目。
- 右键点击完成的 sprite widget，并点击 "Add Library Widget"。
- 这会在 Assets tab 的 library 中创建一个可复用条目。可以把它想成你个人的现成 widget 货架。
- 若要在项目之间移动该 library，或与队友分享，请进入 Library 并点击 Export。
- 之后创建新项目或打开现有 workspace 时，你可以 import 该 library，并直接放入 sprite：无需重建。
- 所有 frames、durations 和 states 都会从原始副本完美同步，因此它在所有使用位置表现一致。
常见问题
sprite 刷入设备后不显示。
- 这几乎总是内存问题：设备需要足够 RAM 来保存 sprite 的图片帧。
- 这由 LVGL 配置决定，不是 PicoPixel 能替你修改的内容，它取决于你的具体开发板。
- 导出的
README.md文件会说明这一点，因此你的 AI assistant 可以帮你为嵌入式设备更新 SDK/LVGL 配置。
帧看起来错位或跳动。
- 再次确认每个 state 中的每一帧都有完全相同的尺寸。即使只差几个像素，也会破坏对齐。
动画播放太快或太慢。
- 调整受影响 state 的 duration。记住每个 state 都有自己的 duration，因此可能需要分别微调。
sprite 不让我保存 / 要求再添加一个 state。
- sprite 至少需要 2 个 state。如果只有一个，请添加第二个 state，或改用 Animated Image widget。
