中文 | English
专为AI Coding设计的 Python Flet开发技能Skill，解决因Flet新老版本的大量破坏性变更，导致AI开发的代码老是报错的Coding痛点！
- 提供全面的Flet API变更指南
- 自动诊断和修复常见错误
- 提供20个最佳实践和示例代码
本 Skill 是专为 Flet 1.0+ (>= 0.82.0) 开发设计的专家级助手，提供：
- ✅ 版本迁移指南：完整的 Flet 0.x → 1.0+ 迁移路径
- ✅ API 变更详解：大量破坏性变更的详细说明和解决方案。覆盖80+ API
- ✅ 错误排查手册：常见错误原因和修复方法
- ✅ 最佳实践：基于实际开发经验的代码模式
- ✅ 示例代码库：20个覆盖各场景的完整示例
Flet 1.0+ 引入了大量破坏性变更，导致许多旧代码无法运行：
- Tabs API 完全重写 - 三件套模式（Tabs + TabBar + TabBarView）
- Badge 控件功能受限 - 只能使用
label参数 - BorderRadius 创建方式变更 - 函数 → 类方法
- Colors 枚举规范化 - 小写 s → 大写 C
- 控件移除和重命名 - ElevatedButton → Button
因此，亟需本 Skill 帮助开发者快速定位和解决这些问题，避免踩坑！
** 💬 用户体验后评论：**
不错啊，非常实用！不用这个Skill，直接让AI写，基本上返工次数 10+ 次，几乎都是因为破坏性变更的语法导致大量报错！心态爆炸！
但是用了skill后，常见功能，几乎都可以一次性AI生成就能直接打开用！返工次数大约只有1-3次！
- ❌ 使用Skill之前：AI生成的代码直接出现大量报错，根本无法运行！
- ✨ 使用Skill之后：AI生成的代码几乎没有报错，直接运行即可！
使用本Skill，开发一款复杂的雷电式飞机射击游戏！
- 提示词：
# Python Flet飞机射击游戏
基于flet开发skill技能，使用 Flet Canvas开发雷电风格的竖屏的飞机射击游戏。
**玩家**：蓝色战斗机（头朝上飞机图标），WASD移动，初始直接自动射击，武器3级（单/双/三发），3条命
**敌机**（头朝下飞机图标）：小型红色（1血）、中型紫色（3血可射击）、大型深红（10血扇形射击显血条）
**道具**：红色+命、黄色升武器、绿色射速+、紫色射速-。均有持续时间限制
**UI**：得分、关卡、生命、武器等级
**画布**：自适应宽高，竖屏游戏界面（后续会打包到Windows和Android端）。
**控制**：WASD移动、P暂停、R重开。每次按键只平滑移动一小段距离，这样方便控制
**注意事项**：(1)注意移动到边界时的逻辑、以及飞机碰撞机制等相关问题；(2)注意画风要满足基本的游戏感觉，有基本的审美。在让整个项目不要太复杂的前提下，也要兼顾可玩性；(3)注意相关元素显示不能超出画布范围。(4)注意游戏画面的实时刷新、连贯性。
- AI开发的效果：
- 注：这里本例AI开发的代码，项目仓库在：
（1）可以看到，在使用本Skill后，AI开发的代码的报错返工次数大幅减小，开发复杂项目也变得实际可行了！而在没有使用本Skill的情况下，AI开发这种程度的Flet项目，几乎会陷入无休止的报错排障中。。。 （2）当然，你所使用的大模型AI的能力也很重要！如果你的AI模型能力不够，那么你可能需要使用更强的AI模型来完成这个任务。
自动识别常见错误模式，提供精准解决方案：
# ❌ 错误：Tabs API 旧写法
ft.Tabs(tabs=[ft.Tab(text="Home", content=...)])
# ✅ 正确：Tabs API 新写法（三件套）
ft.Tabs(
content=ft.Column([
ft.TabBar(tabs=[
ft.Tab(label=ft.Row([...]))
]),
ft.TabBarView(height=120, controls=[...])
]),
length=3,
)- SKILL.md：核心开发指南和最佳实践
- references/api-quick-reference.md：API 快速参考
- references/breaking-changes.md：破坏性变更详解
- references/error-guide.md：错误排查手册
- references/error-quick-reference.md：错误快速查找表
- references/discovery-log.md：API 新发现记录
覆盖常见开发场景：（这些实际上就是现成的初学者入门上手Flet的参考示例脚本！）
| 示例 | 描述 |
|---|---|
01_basic_app.py |
基础应用结构 |
02_async_clock.py |
异步操作和计时器 |
03_form_validation.py |
表单验证 |
04_file_picker_service.py |
文件选择器服务 |
05_shared_preferences.py |
本地存储 |
06_animation_effects.py |
动画效果 |
07_dialog_example.py |
对话框使用 |
08_layout_responsive.py |
响应式布局 |
09_theme_styling.py |
主题和样式 |
10_navigation_menu.py |
导航菜单 |
11_data_table.py |
数据表格 |
12_window_controls.py |
窗口控制 |
13_drag_drop.py |
拖放功能 |
14_keyboard_events.py |
键盘事件 |
15_gestures.py |
手势识别 |
16_clipboard.py |
剪贴板操作 |
17_media_player.py |
媒体播放 |
18_canvas_custom_paint.py |
Canvas 绑制 |
19_file_operations.py |
文件操作 |
20_charts_canvas_visualization.py |
图表可视化 |
在开发过程中自动提醒常见陷阱：
| 陷阱 | 后果 | 正确做法 |
|---|---|---|
| 手动创建 pyproject.toml | 版本不兼容 | 使用 flet create |
使用 ft.app() 启动 |
已废弃 | 使用 ft.run(main) |
ft.colors.RED（小写 s） |
AttributeError | ft.Colors.RED（大写 C） |
Badge 使用 text 参数 |
TypeError | 只能用 label 参数 |
- Python 3.8+
- Flet 0.82.0+
pip install flet[all]# 创建新项目（推荐）
flet create
# 进入项目目录
cd your-project-name
# 运行项目
flet run- IDE里找到Skills导入的地方手动导入文件夹；
- 或直接前往IDE在系统本地的Skills文件夹里，拷贝本文件夹到Skills文件夹里；
- 重启IDE，即可在Skills列表里看到本Skill。
然后，当你在用 AI 开发 Flet 应用时，会自动激活并提供：
- API 用法建议
- 错误诊断和修复方案
- 版本兼容性提示
- 最佳实践指导
flet-development-1.0.1/
├── SKILL.md # 核心开发指南
├── README.md # 本文档
├── references/ # 参考文档目录
│ ├── api-quick-reference.md # API 快速参考
│ ├── breaking-changes.md # 破坏性变更详解
│ ├── error-guide.md # 错误排查手册
│ ├── error-quick-reference.md # 错误快速查找表
│ └── discovery-log.md # API 新发现记录
└── examples/ # 示例代码目录
├── README.md # 示例说明
├── 01_basic_app.py # 基础应用
├── 02_async_clock.py # 异步时钟
├── ... (共 20 个示例)
└── 20_charts_canvas_visualization.py # 图表可视化
-
- Tabs 控件重写（最重要）
-
- Badge 控件受限
-
- BorderRadius 创建方式
-
- Colors 枚举规范化
-
- 启动方式变更
-
- 控件重命名和移除
大量的破坏性变更！
A: 查阅 references/error-quick-reference.md，按错误信息查找解决方案。
常见错误示例：
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
Tabs.__init__() got an unexpected keyword argument 'tabs' |
Tabs API 重写 | 使用三件套模式 |
Badge.__init__() got an unexpected keyword argument 'label_style' |
Badge 功能受限 | 只用 label 参数 |
'NavigationDrawer' object has no attribute 'open' |
API 变更 | 使用 page.show_drawer() |
coroutine 'Window.center' was never awaited |
异步方法未 await | 添加 await |
A: 按以下步骤进行：
- 阅读破坏性变更：
references/breaking-changes.md - 更新依赖：
pip install flet>=0.82.0 - 检查 Tabs 用法：所有 Tabs 都要改为三件套
- 检查 Badge 用法：移除除
label外的所有参数 - 检查 Colors 引用：改为
ft.Colors.XXX - 更新启动方式：改为
ft.run(main)
A: 可能使用了线程 + time.sleep()，应该改为异步：
# ❌ 错误：线程 + time.sleep
import threading
import time
def update():
time.sleep(1)
page.update()
threading.Thread(target=update).start()
# ✅ 正确：asyncio
import asyncio
async def update():
await asyncio.sleep(1)
page.update()
asyncio.create_task(update())A: 使用 page.on_keyboard_event：
def on_keyboard(e: ft.KeyboardEvent):
print(f"按键: {e.key}")
print(f"Shift: {e.shift}")
print(f"Ctrl: {e.ctrl}")
print(f"Alt: {e.alt}")
print(f"Meta: {e.meta}")
page.on_keyboard_event = on_keyboard注意：
- ❌ 没有
e.type属性（无法区分 keydown/keyup） - ❌ 没有
page.on_key_down和page.on_key_up - ✅ 只有
page.on_keyboard_event - ✅ 事件会在按键按下时重复触发
A: 使用 page.drawer 属性和异步方法：
# ✅ 正确用法
drawer = ft.NavigationDrawer(...)
async def open_drawer(e):
page.drawer = drawer
await page.show_drawer()
async def close_drawer(e):
await page.close_drawer()
# ❌ 错误用法
drawer.open() # AttributeError
page.overlay.append(drawer) # 错误所有示例都在 examples/ 目录下，每个示例都可以独立运行！
这些本身就是现成的初学者入门上手Flet的参考示例脚本！
- 01_basic_app.py - 基础应用结构
- 02_async_clock.py - 异步操作和计时器
- 03_form_validation.py - 表单验证
- 04_file_picker_service.py - 文件选择器服务
- 05_shared_preferences.py - 本地存储
- 19_file_operations.py - 文件操作
- 06_animation_effects.py - 动画效果
- 07_dialog_example.py - 对话框使用
- 08_layout_responsive.py - 响应式布局
- 09_theme_styling.py - 主题和样式
- 10_navigation_menu.py - 导航菜单
- 11_data_table.py - 数据表格
- 20_charts_canvas_visualization.py - 图表可视化
- 12_window_controls.py - 窗口控制
- 13_drag_drop.py - 拖放功能
- 14_keyboard_events.py - 键盘事件
- 15_gestures.py - 手势识别
- 16_clipboard.py - 剪贴板操作
- 17_media_player.py - 媒体播放（已标记移除）
- 18_canvas_custom_paint.py - Canvas 绑制
# 进入示例目录
cd examples
# 运行示例
python 01_basic_app.py
- ✅ Flet 初学者：快速上手 Flet 1.0+ 开发
- ✅ Flet Vibe Coding 用户：直接帮助AI绕开绝大多数的破坏性变更导致的代码错误bug
- ✅ 遇到 API 错误的开发者：快速定位和解决问题
- ✅ 需要最佳实践的开发者：学习正确的代码模式
- 🖥️ 桌面端应用（Windows、macOS、Linux）
- 🌐 Web 应用
- 📱 移动端应用（Android、IOS）
- 📊 数据可视化应用
- 🎮 交互式工具
- 📝 表单和数据收集应用
欢迎贡献！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
- 🐛 Bug 修复：修复文档错误或示例代码问题
- 📚 文档改进：完善文档内容
- 💡 新示例：添加新的示例代码
- 🔍 API 发现：发现新的 API 用法和陷阱
本项目采用 MIT 许可证 - 详见 LICENSE 文件。
感谢以下项目和资源：
- Flet - 优秀的 Python UI 框架
- Flet 官方文档 - API 参考
- Flet GitHub - 源码和问题追踪
作者：湖南大白熊
GitHub 主页：https://github.com/HnBigVolibear
问题反馈：请在 GitHub Issues 中提交。不过反正我也不亲自看，反正我也是把你发我的直接发我AI改。。。毕竟这整个Skill都是AI写的（天哪，你想不到吧，耗费了我2亿的tokens。。。我的OpenClaw龙虾都累死啦！），哈哈哈！
捐赠：Buy me a coffee~
如果这个 Skill 对你有帮助，请给一个 ⭐️ Star！
Made with ❤️ by 湖南大白熊