Kivy非主线程创建图形指令TypeError报错解决方案

开发客户端-服务端架构的Kivy聊天应用时，需要实现客户端接收消息后渲染到界面的功能，程序运行抛出如下错误：

TypeError: Cannot create graphics instruction outside the main Kivy thread

已知报错由非主线程操作UI触发，未找到可行修复方案，核心业务代码如下。

现有核心代码 #

Client类 #

class Client(object):
    def __init__(self) -> None:
        self.server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self.server.connect((socket.gethostname(), 7777))
        self.message, self.username = None, None

    def recv(self) -> None:
        data = self.server.recv(1024)
        return self.parse(pickle.loads(data))

    def parse(self, data: dict) -> None:
        if (action := data.get("action")):
            print(data)
            if action == "update":
                clients = pickle.loads(data.get("active-users"))
                # 在线用户列表更新逻辑
            elif action == "message":
                self.message, self.username = data.get("data"), data.get("username")
                return "message_done"

MainScreen类 #

class MainScreen(Screen):
    container = ObjectProperty(None)
    messages = ObjectProperty(None)
    text = ObjectProperty(None)
    def __init__(self, **kw):
        super(MainScreen,self).__init__(**kw)

    def add_message(self, username: str, message: str):
        self.messages.add_widget(CustomLabel(text="[size=17][i][b]" + username + ":[/b][/i][/size]  " + message))

    def on_pre_enter(self, *args):
        threading.Thread(target = self.receive_messages).start()

    def receive_messages(self):
        while True:
            if client.recv() == "message_done":
                self.add_message(client.username,client.message)

    def remove_specific_widget(self, username: str):
        for user in self.container.children:
            if user.text == username:
                return self.container.remove_widget(user)

    def send(self, text: str) -> None:
        client.send(self.text.text)

Kivy的所有图形相关操作（包括创建控件、新增/移除控件、修改控件属性）必须在主线程执行，当前代码在socket消息接收子线程中直接调用add_message新增CustomLabel控件，直接触发了线程安全限制。使用Kivy内置的Clock模块将UI操作调度到主线程执行即可修复。

具体修改步骤 #

1. 在文件头部引入Clock模块：

from kivy.clock import Clock

2. 修改消息接收逻辑，不要在子线程直接执行UI更新，通过Clock.schedule_once将更新任务抛到主线程执行：

def receive_messages(self):
    while True:
        if client.recv() == "message_done":
            # 调度UI操作到主线程执行
            Clock.schedule_once(
                lambda dt: self.add_message(client.username, client.message)
            )

3. （可选优化）将消息接收线程设置为守护线程，避免窗口关闭后子线程仍在后台阻塞运行：

def on_pre_enter(self, *args):
    threading.Thread(target = self.receive_messages, daemon=True).start()

注意：后续如果实现在线用户列表更新的UI逻辑，同样不能直接在子线程操作控件，所有UI相关修改都需要通过Clock调度到主线程运行。

内容的提问来源于stack exchange，提问作者Mar3C10canar