KivyMD 2.x 版本对原有组件架构做了较大调整，早期版本中常用的 MDFlatButton 组件已经被官方弃用，开发者在升级依赖后如果继续使用旧组件，会出现警告甚至运行报错的情况，需要按照官方规范完成组件迁移。
MDFlatButton 废弃的背景
KivyMD 2.x 重构了按钮组件的设计逻辑，将原本分散的不同样式按钮统一整合到 MDButton 组件中，通过属性配置实现不同样式的按钮效果，减少组件冗余。原有的 MDFlatButton、MDRaisedButton 等组件都被归为过时组件，官方不再维护相关功能，后续版本可能会直接移除这些组件，因此开发者需要尽快完成迁移。
核心替代组件 MDButton
MDButton 是 KivyMD 2.x 中通用的按钮组件，通过 style 属性可以设置按钮的样式，替代原来不同类名对应的按钮类型。常用的 style 取值包括 text、filled、outlined、tonal 等，分别对应无背景文本按钮、填充按钮、轮廓按钮、色调按钮，基本覆盖原来 MDFlatButton 系列组件的所有使用场景。
MDButton 常用属性说明
- style：按钮样式，默认值为 text，对应原来的 MDFlatButton 无背景样式
- text：按钮显示的文本内容
- theme_text_color：按钮文本的主题颜色配置
- on_release：按钮点击释放时的回调函数
- pos_hint：按钮的位置布局提示
- size_hint：按钮的尺寸布局提示
迁移代码示例
原有 MDFlatButton 使用示例
以下是 KivyMD 1.x 版本中使用 MDFlatButton 的典型代码：
from kivymd.app import MDApp
from kivymd.uix.button import MDFlatButton
from kivymd.uix.screen import MDScreen
class OldApp(MDApp):
def build(self):
screen = MDScreen()
# 创建无背景的扁平按钮
btn = MDFlatButton(
text="点击我",
pos_hint={"center_x": 0.5, "center_y": 0.5},
on_release=self.btn_click
)
screen.add_widget(btn)
return screen
def btn_click(self, instance):
print("按钮被点击了")
OldApp().run()
迁移后 MDButton 实现代码
将上述代码迁移到 KivyMD 2.x 版本，使用 MDButton 替代 MDFlatButton，代码如下：
from kivymd.app import MDApp
from kivymd.uix.button import MDButton
from kivymd.uix.screen import MDScreen
class NewApp(MDApp):
def build(self):
screen = MDScreen()
# 创建 style 为 text 的按钮，对应原来的 MDFlatButton 无背景样式
btn = MDButton(
text="点击我",
style="text",
pos_hint={"center_x": 0.5, "center_y": 0.5},
on_release=self.btn_click
)
screen.add_widget(btn)
return screen
def btn_click(self, instance):
print("按钮被点击了")
NewApp().run()
不同样式按钮的迁移对照
如果原来使用的是其他样式的扁平类按钮，可以通过调整 MDButton 的 style 属性实现对应效果，对照关系如下：
| 原组件 | 对应 MDButton style 值 | 效果说明 |
|---|---|---|
| MDFlatButton | text | 无背景文本按钮 |
| MDRaisedButton | filled | 填充背景按钮 |
| MDRectangleFlatButton | outlined | 带轮廓无填充按钮 |
| MDTonalButton | tonal | 色调背景按钮 |
迁移注意事项
在迁移过程中需要注意以下几点：
- MDButton 的子组件逻辑和原来的 MDFlatButton 存在差异，如果原来按钮内部添加了图标等子组件，需要按照 MDButton 的子组件规则重新调整
- 部分原来 MDFlatButton 支持的自定义属性在 MDButton 中可能没有对应实现，需要查看官方文档确认替代属性
- 如果项目中大量使用了 MDFlatButton，可以封装一个适配函数，统一处理新旧组件的转换，减少重复修改的工作量
- 迁移完成后建议全面测试按钮的点击响应、样式显示、布局适配等功能，确保没有遗漏的问题
总结
KivyMD 2.x 废弃 MDFlatButton 是为了优化组件架构，MDButton 作为统一替代方案功能更完善，适配性更强。开发者按照本文的对照关系和示例代码调整现有代码，就可以快速完成迁移，避免组件废弃带来的问题。如果后续遇到特殊的样式适配需求，可以参考 KivyMD 官方文档的 MDButton 章节获取更多配置说明。
KivyMDMDFlatButtonMDButton迁移指南替代方案修改时间：2026-06-11 15:39:22