# awesome-flet-development-skill

**Repository Path**: hernan/awesome-flet-development-skill

## Basic Information

- **Project Name**: awesome-flet-development-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flet-development Skill

**中文** | [English](README-en.md)

<div align="center">

![Flet Version](https://img.shields.io/badge/Flet-0.82.0%2B-blue)
![Python](https://img.shields.io/badge/Python-3.10%2B-green)
![License](https://img.shields.io/badge/License-MIT-yellow)

</div>

**专为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个覆盖各场景的完整示例

### 为什么需要这个 Skill？

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生成的代码直接出现大量报错，根本无法运行！

![效果演示](./error.png)

- ✨ 使用Skill之后：AI生成的代码几乎没有报错，直接运行即可！

![效果演示](./success.png)

### 🧠 实战测试
使用本Skill，开发一款复杂的雷电式飞机射击游戏！

- 提示词：
```
# Python Flet飞机射击游戏
基于flet开发skill技能，使用 Flet Canvas开发雷电风格的竖屏的飞机射击游戏。
**玩家**：蓝色战斗机（头朝上飞机图标），WASD移动，初始直接自动射击，武器3级（单/双/三发），3条命
**敌机**（头朝下飞机图标）：小型红色（1血）、中型紫色（3血可射击）、大型深红（10血扇形射击显血条）
**道具**：红色+命、黄色升武器、绿色射速+、紫色射速-。均有持续时间限制
**UI**：得分、关卡、生命、武器等级
**画布**：自适应宽高，竖屏游戏界面（后续会打包到Windows和Android端）。
**控制**：WASD移动、P暂停、R重开。每次按键只平滑移动一小段距离，这样方便控制
**注意事项**：(1)注意移动到边界时的逻辑、以及飞机碰撞机制等相关问题；(2)注意画风要满足基本的游戏感觉，有基本的审美。在让整个项目不要太复杂的前提下，也要兼顾可玩性；(3)注意相关元素显示不能超出画布范围。(4)注意游戏画面的实时刷新、连贯性。
```

- AI开发的效果：

![效果演示](./game.png)

- 注：这里本例AI开发的代码，项目仓库在：

[![flet-game-by-using-flet-skill-demo01](https://img.shields.io/badge/🚀_flet--game--by--using--flet--skill--demo01-点击查看-brightgreen?style=for-the-badge)](https://github.com/HnBigVolibear/flet-game-by-using-flet-skill-demo01)

（1）可以看到，在使用本Skill后，AI开发的代码的报错返工次数大幅减小，开发复杂项目也变得实际可行了！而在没有使用本Skill的情况下，AI开发这种程度的Flet项目，几乎会陷入无休止的报错排障中。。。
（2）当然，你所使用的大模型AI的能力也很重要！如果你的AI模型能力不够，那么你可能需要使用更强的AI模型来完成这个任务。

---

## 🎯 核心特性

### 1. 🔍 智能错误诊断

自动识别常见错误模式，提供精准解决方案：

```python
# ❌ 错误：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,
)
```

### 2. 📚 完整文档体系

- **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 新发现记录

### 3. 💡 20个示例代码

覆盖常见开发场景：（这些实际上就是现成的初学者入门上手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` | 图表可视化 |

### 4. 🚨 实时陷阱提醒

在开发过程中自动提醒常见陷阱：

| 陷阱 | 后果 | 正确做法 |
|------|------|---------|
| 手动创建 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+

### 安装 Flet

```bash
pip install flet[all]
```

### 创建新项目

```bash
# 创建新项目（推荐）
flet create

# 进入项目目录
cd your-project-name

# 运行项目
flet run
```

# 使用本 Skill

### 将本Skill文件夹，安装导入到你的AI IDE（例如Claude Code、Trae、Cursor、CodeBuddy、甚至是OpenClaw）里即可！

- 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 # 图表可视化
```

---

## 🔑 关键 API 变更

- 1. Tabs 控件重写（最重要）
- 2. Badge 控件受限
- 3. BorderRadius 创建方式
- 4. Colors 枚举规范化
- 5. 启动方式变更
- 6. 控件重命名和移除

大量的破坏性变更！

---

## ❓ 常见问题

### Q1: 如何快速定位错误？

**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` |

### Q2: 如何从 Flet 0.x 迁移到 1.0+？

**A**: 按以下步骤进行：

1. **阅读破坏性变更**：`references/breaking-changes.md`
2. **更新依赖**：`pip install flet>=0.82.0`
3. **检查 Tabs 用法**：所有 Tabs 都要改为三件套
4. **检查 Badge 用法**：移除除 `label` 外的所有参数
5. **检查 Colors 引用**：改为 `ft.Colors.XXX`
6. **更新启动方式**：改为 `ft.run(main)`

### Q3: 为什么我的界面不实时更新？

**A**: 可能使用了线程 + `time.sleep()`，应该改为异步：

```python
# ❌ 错误：线程 + 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())
```

### Q4: 如何处理键盘事件？

**A**: 使用 `page.on_keyboard_event`：

```python
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`
- ✅ 事件会在按键按下时重复触发

### Q5: NavigationDrawer 如何使用？

**A**: 使用 `page.drawer` 属性和异步方法：

```python
# ✅ 正确用法
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** - 文件操作

#### 🎨 UI 和动画
- **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 绑制

### 运行示例

```bash
# 进入示例目录
cd examples

# 运行示例
python 01_basic_app.py
```

### 运行效果截图

![img](./demo1.png)
![img](./demo2.png)
![img](./demo3.png)
![img](./demo4.png)
![img](./demo5.png)
![img](./demo6.png)
![img](./demo7.png)
![img](./demo8.png)
![img](./demo9.png)

---

## 🎯 使用场景

### 适合人群

- ✅ Flet 初学者：快速上手 Flet 1.0+ 开发
- ✅ Flet Vibe Coding 用户：直接帮助AI绕开绝大多数的破坏性变更导致的代码错误bug
- ✅ 遇到 API 错误的开发者：快速定位和解决问题
- ✅ 需要最佳实践的开发者：学习正确的代码模式

### 适用项目类型

- 🖥️ 桌面端应用（Windows、macOS、Linux）
- 🌐 Web 应用
- 📱 移动端应用（Android、IOS）
- 📊 数据可视化应用
- 🎮 交互式工具
- 📝 表单和数据收集应用

---

## 🤝 贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 贡献类型

- 🐛 Bug 修复：修复文档错误或示例代码问题
- 📚 文档改进：完善文档内容
- 💡 新示例：添加新的示例代码
- 🔍 API 发现：发现新的 API 用法和陷阱

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

感谢以下项目和资源：

- [Flet](https://flet.dev/) - 优秀的 Python UI 框架
- [Flet 官方文档](https://flet.dev/docs/) - API 参考
- [Flet GitHub](https://github.com/flet-dev/flet) - 源码和问题追踪

---

## 👨‍💻 作者信息

**作者**：湖南大白熊 

![img](bear.png)

**GitHub 主页**：[https://github.com/HnBigVolibear](https://github.com/HnBigVolibear) 

**问题反馈**：请在 GitHub Issues 中提交。不过反正我也不亲自看，反正我也是把你发我的直接发我AI改。。。毕竟这整个Skill都是AI写的（天哪，你想不到吧，耗费了我2亿的tokens。。。我的OpenClaw龙虾都累死啦！），哈哈哈！

**捐赠**：Buy me a coffee~

![img](sponsor.png)

---

<div align="center">

**如果这个 Skill 对你有帮助，请给一个 ⭐️ Star！**

Made with ❤️ by 湖南大白熊

</div>