下面给出一份“NiceGUI 2025 年最新版（v3.2.0）”零基础到进阶的完整学习路线与示例，全部基于 2025-10 以后发布的官方功能与中文社区实践整理，可直接复制运行。
1. 环境准备（2025 版）
# 1. 建议使用 Python 3.11+（3.14 已在 CI 验证）
python -m venv venv
source venv/bin/activate
# 2. 安装最新正式版
pip install -U nicegui
# 3. 查看版本
python -m pip show nicegui
官方文档与在线示例永远是最新的：nicegui.io/documentati…
2. 10 行代码跑通第一个 Web GUI
# main.py
from nicegui import ui
ui.label('👋 你好，NiceGUI 2025！')
ui.button('点我', on_click=lambda: ui.notify('按钮被点了'))
ui.run(title='NiceGUI 2025 快速体验', port=8080)
运行 python main.py 后浏览器自动打开 http://localhost:8080，支持热重载（改代码即刷新）。
3. 2025 重点新特性速览
| 功能 | 说明 | 最低版本 |
|---|---|---|
ui.page_sticky(expand=True) | 页脚/侧边栏可真正的“粘性”扩展 | 2.11.0+ |
ui.interactive_image 新增 loaded 事件 | 图片加载完成后再绘制标注 | 1.4.13+ |
ui.aggrid 支持直接调用 Column API | 动态显示/隐藏列、排序 | 1.3.8+ |
ui.timer 异常捕获链修复 | 定时器内出错不会导致页面卡死 | 3.0.4+ |
ui.download 支持本地文件路径 | 一键导出本地 csv/zip | 1.3.8+ |
4. 实战 1：实时仪表盘（CSV → 动态柱图）
需求：把不断增长的 csv 每 10 秒画成“温度计”柱状图，浏览器零刷新。 2025 官方已修复 ui.timer 异常链，可放心在异步场景使用 。
from nicegui import ui
import pandas as pd, asyncio, random, datetime as dt, pathlib
CSV = pathlib.Path('temp.csv')
def append_new_row():
"""模拟传感器：追加一行随机值"""
new = {'time': dt.datetime.now(), 'value': random.randint(20, 40)}
pd.DataFrame([new]).to_csv(CSV, index=False, header=not CSV.exists(), mode='a')
# 首次启动先生成一点数据
for _ in range(5):
append_new_row()
# 初始化 ECharts
echart = ui.echart({
'xAxis': {'type': 'category', 'data': []},
'yAxis': {'type': 'value'},
'series': [{'type': 'bar', 'name': '温度', 'data': []}],
'color': ['#ff6565']
})
def update_chart():
df = pd.read_csv(CSV, parse_dates=['time'])
echart.options['xAxis']['data'] = df['time'].dt.strftime('%H:%M:%S').tolist()
echart.options['series'][0]['data'] = df['value'].tolist()
echart.update() # 关键：推送 diff 到前端
ui.notify('图表已刷新')
# 定时任务：追加 + 刷新
ui.timer(10, lambda: (append_new_row(), update_chart()))
ui.button('手动刷新', on_click=update_chart)
ui.run(port=8081)
要点
- 用
ui.timer而非while True，不会阻塞事件循环 ； - 通过
echart.update()完成“差量刷新”，性能优于整页重载； - 若 csv 由外部进程写入，也无需加锁，Pandas 读操作是原子性的。
5. 实战 2：响应式三栏后台（Header / Side / Content）
2025 中文社区给出的“够用就好”布局模板 ，结合 Tailwind CSS 栅格，可一键适配手机/PC。
也可以点出来！！
from nicegui import ui
# --- 通用头 ---
with ui.header(elevated=True).classes('items-center justify-between'):
ui.icon('menu').on('click', lambda: left_drawer.toggle())
ui.label('🐍 NiceGUI 2025 后台').classes('text-lg')
with ui.button_group():
ui.button(icon='menu', on_click=lambda: right_drawer.toggle())
ui.button(icon='logout', on_click=lambda: ui.notify('退出登录'))
# --- 左侧抽屉 ---
with ui.left_drawer(value=True, bordered=True).classes('bg-blue-50') as left_drawer:
ui.label('导航').classes('text-bold')
ui.separator()
for title, icon in [('首页', 'home'), ('数据', 'analytics'), ('设置', 'settings')]:
ui.button(title, icon=icon).classes('w-full')
# --- 右侧抽屉 ---
with ui.right_drawer(value=False, bordered=False).classes('bg-blue-50') as right_drawer:
ui.label('右侧面板').classes('text-bold')
ui.separator()
for title, icon in [('首页', 'home'), ('数据', 'analytics'), ('设置', 'settings')]:
ui.button(title, icon=icon).classes('w-full')
# --- 主内容区 ---
with ui.column().classes('w-full p-4'):
ui.label('欢迎使用最新版 NiceGUI').classes('text-h5')
ui.card().classes('w-full max-w-3xl mx-auto mt-4').tight()
with ui.row().classes('items-center'):
ui.circular_progress(value=0.73, show_value=False).props('size=4rem')
ui.label('服务器负载 73%').classes('ml-4')
# --- 底栏 ---
with ui.footer().classes('text-center text-sm'):
ui.label('© 2025 公司名 | Powered by NiceGUI v3.0.4')
ui.run(title='后台模板')
要点
left_drawer(value=True)默认展开；- 使用 Tailwind 工具类（
w-full,max-w-3xl,mx-auto）完成响应式； - 卡片
tight()属性可让内部元素更紧凑（申缩菜单），2025 新增。
6. 进阶路线 & 学习资源
- 官方在线 demos 与 API 速查 nicegui.io/documentati…（含 200+ 可交互示例）
7. 常见坑与 2025 修复记录
| 问题 | 现象 | 解决 | 版本 |
|---|---|---|---|
ui.timer 内抛异常导致页面卡死 | 定时器不再回调 | 已捕获到 UI 上下文 | 3.0.4 |
ui.number 输入非法时尾部多小数点 | 1.230000000 | 校验逻辑重写 | 1.4.13 |
ui.scene 中 draggable() 成组对象无法拖动 | 3D 场景交互失效 | 事件代理修复 | 2.1.0 |
| 断线重连后事件丢失 | WebSocket 重连后按钮失效 | 避免重连时退订事件 | 3.0.4 |
8. 小结
- NiceGUI 2025（v3.2.0）已非常稳定，可用于内部后台、实时仪表盘、低代码 CRUD。
- 官方文档 + 社区模板足够覆盖 90% 场景；遇到定制需求可深挖 Vue/Quasar 层。
- 记住“能用
ui.timer就别写while True，能update()就别整页刷新”，性能与体验兼得。
用 Python 写出最漂亮的 Web GUI！
