customtkinter 原生不支持 gif 动画自动播放，需手动提取每一帧并配合 `after()` 实现循环刷新；本文提供可复用的 `giflabel` 自定义组件，支持自适应尺寸、帧率控制与无缝循环播放。
在 CustomTkinter 中显示静态图片（如 PNG、JPEG）非常简单，直接使用 CTkImage 配合 CTkLabel 即可。但若要播放 动画 GIF，则必须自行处理帧序列与定时刷新逻辑——因为 CTkImage 仅加载首帧，且 CTkLabel 不具备内置动画机制。
下面是一个完整、健壮的解决方案：我们继承 CTkLabel 创建 GIFLabel 类，它会：
- 自动读取 GIF 文件所有帧；
- 将每帧转换为独立的 CTkImage（适配目标尺寸）；
- 利用 after() 方法按原始帧间隔（或自定义时长）循环切换图像；
- 支持宽高自动匹配 GIF 原图尺寸，也允许显式指定。
import customtkinter as ctk
from PIL import Image
class GIFLabel(ctk.CTkLabel):
def __init__(self, master, image_path, duration=None, size=None, **kwargs):
"""
初始化 GIF 动画标签
:param master: 父容器
:param image_path: GIF 文件路径
:param duration: 每帧显示毫秒数（可选），默认取 GIF 元数据中的 duration
:param size: (width, height) 元组，用于缩放每帧；若为 None，则使用 GIF 原始尺寸
"""
self._gif_image = Image.open(image_path)
# 设置默认尺寸（优先使用传入的 size，否则用 GIF 原图尺寸）
if size is None:
width, height = self._gif_image.width, self._gif_image.height
else:
width, height = size
kwargs.setdefault("width", width)
kwargs.setdefault("height", height)
kwargs.setdefault("text", "") # 隐藏文字内容
super().__init__(master, **kwargs)
# 获取帧间隔（单位：毫秒）
self._duration = duration or self._gif_image.info.get("duration", 100)
# 提取并缓存所有帧（转为 CTkImage）
self._frames = []
for i in range(self._gif_image.n_frames):
self._gif_image.seek(i)
frame = self._gif_image.copy()
ct_img = ctk.CTkImage(light_image=frame, dark_image=frame, size=(width, height))
self._frames.append(ct_img)
# 启动动画
self._current_frame = 0
self._animate()
def _animate(self):
"""私有方法：更新当前帧并调度下一帧"""
if self._frames:
self.configure(image=self._frames[self._current_frame])
self._current_frame = (self._current_frame + 1) % len(self._frames)
self.after(self._duration, self._animate)
def stop(self):
"""暂停动画（可选扩展）"""
self.after_cancel(self._animate.__func__ if hasattr(self, '_animate') else None)
def play(self):
"""恢复动画（可选扩展）"""
self._animate()✅ 使用示例：
app = ctk.CTk()
app.title("GIF in CustomTkinter")
app.geometry("1300x750")
# 播放本地 GIF（自动适配原图尺寸）
gif_label = GIFLabel(app, "resources/images/background.gif")
gif_label.pack(pady=20)
# 或指定固定尺寸（例如适配窗口区域）
# gif_label = GIFLabel(app, "loading.gif", size=(300, 300), duration=80)
app.mainloop()⚠️ 注意事项：
- 确保已安装依赖：pip install customtkinter pillow
- GIF 路径需为有效绝对或相对路径（推荐使用 os.path.join() 构建跨平台路径）；
- 大型 GIF（帧数多/分辨率高）可能造成内存占用上升，建议预处理为合适尺寸；
- 当前方案不支持 MP4 视频——CustomTkinter 无内置视频解码能力；如需播放 MP4，应改用 tkinter 原生 VideoPlayer（如基于 OpenCV + Canvas）或切换至 PyQt/Kivy 等支持媒体控件的框架；
- 若需响应式缩放（如随窗口调整 GIF 尺寸），需监听 <Configure> 事件并重载 _frames，本例暂未包含该高级功能。
通过封装 GIFLabel，你可在任意 CustomTkinter 项目中以声明式方式嵌入高质量 GIF 动画，兼顾简洁性与可控性。
