【Python开发 | 图文教程】NiceGUI：Web 界面的优雅之选

【精选优质专栏推荐】

• 《AI 技术前沿》 —— 紧跟 AI 最新趋势与应用
• 《网络安全新手快速入门(附漏洞挖掘案例)》 —— 零基础安全入门必看
• 《BurpSuite 入门教程(附实战图文)》 —— 渗透测试必备工具详解
• 《网安渗透工具使用教程(全)》 —— 一站式工具手册
• 《CTF 新手入门实战教程》 —— 从题目讲解到实战技巧
• 《前后端项目开发(新手必知必会)》 —— 实战驱动快速上手

每个专栏均配有案例与图文讲解，循序渐进，适合新手与进阶学习者，欢迎订阅。

项目说明

NiceGUI 是一个基于 Python 的轻量级 UI 框架，旨在帮助开发者快速构建交互式 Web 界面。它通过浏览器呈现用户界面，支持按钮、对话框、Markdown、3D 场景、图表等多种组件，适用于微型 Web 应用、仪表板、机器人项目、智能家居解决方案等场景。

项目特点

• 浏览器呈现
  界面直接在浏览器中显示，无需额外安装客户端。

• 实时交互
  支持 WebSocket，实现前后端实时通信，界面无需刷新即可更新。

• 组件丰富
  提供按钮、输入框、滑块、图表、3D 场景等多种 UI 元素。

• 简洁代码
  使用 Python 代码即可定义界面，免去 HTML、CSS 的编写。

• 易于部署
  支持通过 Docker、PyPI 等方式安装，部署简单。

• 扩展性强
  支持自定义路由、数据响应、持久化存储等功能，适用于构建完整的 Web 应用。

项目地址

GitHub 仓库：

https://github.com/zauberzeug/nicegui

官方网站：

https://nicegui.io/

安装使用教程

安装

使用 pip 安装 NiceGUI：

python -m pip install nicegui

创建应用

删除 main.py 中的所有代码：

在 main.py 中编写以下代码：

from nicegui import ui

ui.label('Hello NiceGUI!')

ui.button('Click me', on_click=lambda: ui.notify('Button pressed!'))

ui.run()

运行应用

在命令行中运行：

python main.py

然后在浏览器中访问 http://127.0.0.1:8080/ 即可看到界面：

示例1

以下是一个包含滑块和数字输入框的示例，实时同步值：

from nicegui import ui

class Demo:
    def __init__(self):
        self.number = 1

demo = Demo()

ui.slider(min=1, max=5).bind_value(demo, 'number')
ui.number().bind_value(demo, 'number')
ui.toggle({1: 'A', 2: 'B', 3: 'C', 4: 'D', 5: 'E'}).bind_value(demo, 'number')

ui.run()

在上述示例中，滑块、数字输入框和切换按钮的值会实时同步，展示了 NiceGUI 的数据绑定功能。

示例2

main.py：

from nicegui import ui
from pathlib import Path

# -----------------------------
# 左侧导航菜单
# -----------------------------
menu_items = [
    {"label": "仪表盘", "callback": "show_dashboard"},
    {"label": "安全审核", "callback": "show_security_audit"},
    {"label": "设置", "callback": "show_settings"},
]

# -----------------------------
# 右侧内容区
# -----------------------------
with ui.row().style("height: 100vh;"):
    # 左侧导航栏
    with ui.column().style("width: 220px; background-color: #f0f0f0; padding: 16px;"):
        ui.label("菜单").classes("text-xl mb-4")
        buttons = {}
        for item in menu_items:
            btn = ui.button(
                item['label'],
                on_click=lambda e, cb=item['callback']: globals()[cb](),
            )
            btn.classes("w-full mb-2 text-left")
            buttons[item['label']] = btn

    # 右侧内容区
    content = ui.column().style("flex: 1; padding: 20px; overflow-y: auto;")

# -----------------------------
# 页面渲染函数
# -----------------------------
def show_dashboard():
    content.clear()
    with content:
        ui.label("仪表盘").classes("text-2xl")
        ui.markdown("欢迎来到仪表盘！这里可以显示统计数据和图表。")

def show_security_audit():
    content.clear()
    with content:
        ui.label("安全审核").classes("text-2xl mb-2")
        # 加载本地 HTML 文件
        html_path = Path("security_audit.html")  # 请放置你的 HTML 文件在项目根目录
        if html_path.exists():
            html_code = html_path.read_text(encoding="utf-8")
            ui.html(html_code)
        else:
            ui.label("未找到 security_audit.html 文件")

def show_settings():
    content.clear()
    with content:
        ui.label("设置").classes("text-2xl")
        ui.markdown("这里可以修改系统配置或管理用户权限。")

# -----------------------------
# 默认加载仪表盘
# -----------------------------
show_dashboard()

# -----------------------------
# 启动应用
# -----------------------------
ui.run()

开发文档与示例

可访问以下链接获取开发文档，其中存在大量演示：

https://nicegui.io/documentation

可访问以下链接查看更多示例：

https://github.com/zauberzeug/nicegui/tree/main/examples

Wiki：

https://github.com/zauberzeug/nicegui/wiki

依赖包内部版本不兼容解决方法

可能出现的报错：

PS D:\I\Envir\Python\WorkSpace> cd .\nicegui-main\ PS D:\I\Envir\Python\WorkSpace\nicegui-main> python3 -m pip install nicegui PS D:\I\Envir\Python\WorkSpace\nicegui-main> & D:/I/Envir/Python/python.exe d:/I/Envir/Python/WorkSpace/nicegui-main/main.py Traceback (most recent call last): File “d:\I\Envir\Python\WorkSpace\nicegui-main\main.py”, line 5, in module from fastapi import Request File “D:\I\Envir\Python\lib\site-packages\fastapi_init.py”, line 7, in module from .applications import FastAPI as FastAPI File “D:\I\Envir\Python\lib\site-packages\fastapi\applications.py”, line 16, in module from fastapi import routing File “D:\I\Envir\Python\lib\site-packages\fastapi\routing.py”, line 45, in module from fastapi.exceptions import ( ImportError: cannot import name ‘ResponsttttidationError’ from ‘fastapi.exceptions’ (D:\I\Envir\Python\lib\site-packages\fastapi\exceptions.py) PS D:\I\Envir\Python\WorkSpace\nicegui-main>

出现报错的原因是依赖包内部版本不兼容，解决方法如下：

1.卸载旧版本 FastAPI 和 Starlette

python -m pip uninstall fastapi starlette -y

2.安装兼容版本
根据 NiceGUI 官方推荐（截至目前），安装：

python -m pip install fastapi==0.109.1 starlette==0.27.0

3.确认 NiceGUI 版本

python -m pip install --upgrade nicegui

4.清理缓存

python -m pip cache purge