如何解决pygame.mouse.set_cursor方法导致的TypeError: expected a pygame.cursors.Cursor object错误？

问题现象描述

在使用pygame.mouse.set_cursor()方法时，开发者经常会遇到如下错误提示：

TypeError: expected a pygame.cursors.Cursor object

这个错误通常发生在尝试设置自定义光标时，传入的参数不符合方法要求的数据类型。错误的核心在于没有正确创建pygame.cursors.Cursor类的实例。

错误原因分析

通过分析Pygame源码和文档，我们发现这个错误主要由以下原因导致：

直接传入原始数据：试图将二进制数据或元组直接传给set_cursor方法
使用旧版API格式：Pygame 2.0+版本修改了光标系统的实现方式
缺少构造函数调用：未使用pygame.cursors.Cursor()显式创建对象
参数类型不匹配：传入了字符串、整数等不兼容的类型

解决方案

方法一：使用标准构造函数

正确创建Cursor对象的方法如下：

import pygame
from pygame.locals import *

# 初始化Pygame
pygame.init()

# 创建系统默认光标
system_cursor = pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW)
pygame.mouse.set_cursor(system_cursor)

方法二：从位图创建自定义光标

对于需要完全自定义的光标，可以这样实现：

# 定义光标位图数据（示例为16x16箭头）
cursor_data = (
    "XX                      ",
    "X.X                     ",
    "X..X                    ",
    "X...X                   ",
    # 更多行数据...
)

# 转换为二进制格式
cursor_binary = pygame.cursors.compile(cursor_data)

# 创建Cursor对象
custom_cursor = pygame.cursors.Cursor(
    (16, 16),  # 光标尺寸
    (0, 0),    # 热点位置
    *cursor_binary  # 展开二进制数据
)

pygame.mouse.set_cursor(custom_cursor)

方法三：使用预设系统光标

Pygame提供了一系列预设系统光标：

# 可用系统光标类型列表
system_cursors = [
    pygame.SYSTEM_CURSOR_ARROW,
    pygame.SYSTEM_CURSOR_IBEAM,
    pygame.SYSTEM_CURSOR_WAIT,
    pygame.SYSTEM_CURSOR_CROSSHAIR,
    # 更多系统光标...
]

# 设置等待光标
wait_cursor = pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_WAIT)
pygame.mouse.set_cursor(wait_cursor)

最佳实践建议

始终检查Pygame版本（pygame.version.ver）
对自定义光标使用pygame.cursors.compile()预处理
捕获并处理可能的异常：

try:
    pygame.mouse.set_cursor(cursor_obj)
except TypeError as e:
    print(f"光标设置失败: {e}")
    # 回退到默认光标
    pygame.mouse.set_cursor(pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW))

版本兼容性说明

Pygame 2.0及以上版本对光标系统进行了重大重构：

特性	Pygame 1.x	Pygame 2.0+
API调用方式	直接传入元组数据	必须使用Cursor对象
系统光标支持	有限	扩展支持
错误处理	较宽松	严格类型检查

调试技巧

当遇到光标问题时，可以：

打印检查Cursor对象的类型：print(type(cursor_obj))
验证热点位置是否在尺寸范围内
测试使用最简单的系统光标确认基础功能
检查SDL视频驱动是否正常初始化