如何在Kivy多文件项目中正确添加外部类？

一、Python类的导入规则 #

• 每个自定义类单独存放在对应名称的.py文件中（比如Example.py中定义Example类），仅在项目入口文件（如main.py）中导入一次，示例：

  # main.py
  from kivy.app import App
  from Example import Example  # 仅此处导入一次
  
  class MyApp(App):
      def build(self):
          return Example()
  
  if __name__ == "__main__":
      MyApp().run()
  

• 避免在多个Python文件中重复导入同一个类，否则会触发Kivy的类重复注册提示。

二、KV文件的加载逻辑 #

Kivy自带自动匹配加载机制，无需手动include：

• 自定义类的KV规则文件命名必须与类名完全对应（类名转小写），比如Example类对应example.kv。
• 只要Python入口文件已经导入了该类，Kivy会自动查找并加载同名KV文件，无需在任何KV文件中写include "example.kv"。
• 若要在其他KV文件中使用该自定义组件，直接写类名规则即可（如<Example>），前提是对应的Python类已被入口文件导入。

三、解决“类已被包含”的问题 #

你遇到的提示，本质是重复注册：

• 检查是否在多个Python文件中重复导入了同一个自定义类；
• 检查是否在多个KV文件中重复使用include加载了同一个KV文件；
• 确保每个自定义类仅被导入一次，对应的KV文件仅被Kivy自动加载一次（或手动include一次）。

标准项目结构示例 #

my_kivy_project/
├── main.py
├── Example.py
└── example.kv

Example.py代码：

from kivy.uix.widget import Widget

class Example(Widget):
    pass

example.kv代码：

<Example>:
    Label:
        text: "自定义Example组件"
        pos: self.parent.pos
        size: self.parent.size

内容的提问来源于stack exchange，提问作者Marek Umiński