NiceGUI 文档
赞助我们
- 如果你喜欢 NiceGUI ，欢迎前往 赞助者 页面捐赠 NiceGUI ，或者提交议题/拉取请求来成为 贡献者
- 如果你喜欢 NiceGUI 中文网，你也可以通过 爱发电 来维持本站的无偿运营，或者前往 NiceGUI 中文网 - Github 仓库 来提交/改进翻译。
[AD] 欢迎你加入译者的QQ交流群 云星启智网络交流群 和我们一起聊天吹水玩抽象：140438837
概览
NiceGUI 是一个开源的 Python 库，用于编写在浏览器中运行的图形用户界面。它的学习曲线非常平缓，同时仍提供高级定制选项。NiceGUI 遵循后端优先理念：它处理所有 Web 开发细节。您可以专注于编写 Python 代码。这使其非常适合各种项目，包括简短脚本、 仪表盘、机器人项目、物联网解决方案、智能家居自动化和机器学习。
如何使用本指南
本文档解释如何使用 NiceGUI。每个模块卡片都详细介绍了 NiceGUI 的一个主题。建议先完整阅读本介绍页面，之后根据需要查阅其他章节。
基本概念
NiceGUI 提供 UI 元素，如按钮、滑块、文本、图像、图表等。您的应用将这些组件组装成页面。当用户与页面元素交互时，NiceGUI 会触发事件（或动作）。您需要定义处理每个事件的代码，例如用户点击按钮、修改值或操作滑块时的响应逻辑。元素也可以绑定到模型（数据对象），当模型值变化时会自动更新用户界面。
元素使用 "声明式 UI"（或者说"基于代码的 UI"）排列在页面上。这意味着您可以直接用代码编写网格、卡片、标签页、轮播图、折叠面板、菜单和其他布局元素。这种理念因Flutter 和 SwiftUI 而流行。为了可读性，NiceGUI 使用 Python 的 with ... 语句。 该上下文管理器通过代码缩进来直观反映 UI 布局结构。
样式和外观可以通过多种方式控制。大多数元素接受常见样式和行为变更的可选参数，例如按钮图标或文本颜色。由于 NiceGUI 是 Web 框架，您可以用 CSS 修改元素的几乎任何外观。元素还提供 .classes 和 .props 方法来应用 Tailwind CSS 和 Quasar 属性， 这些高级特性在熟悉后日常使用更加简单高效。
动作、事件与任务
NiceGUI 使用异步/等待事件循环来实现并发，这种方式资源利用率高且无需担心线程安全。本节展示如何处理用户输入和定时器、键盘绑定等其他事件。同时描述如何用异步函数封装长时间运行的任务以保持 UI 响应性。请注意所有 UI 更新都必须在主线程的事件循环中进行。
实现原理
NiceGUI 基于 HTTP 服务器 FastAPI 的 HTML 组件实现，即使是原生窗口也是如此。如果您熟悉 HTML，所有内容都会非常亲切。如果不了解 HTML 也没关系！NiceGUI 抽象了底层细节，让您可以专注于创建美观界面而无需操心实现方式。
运行 NiceGUI 应用
NiceGUI 有多个部署选项。默认情况下，NiceGUI 在本地运行服务器，并将应用作为本地机器的私有网页运行。这种方式下，您的应用会显示在浏览器窗口中。 您也可以让 NiceGUI 在独立于浏览器的原生窗口中运行，或者将 NiceGUI 部署在服务多个客户端的服务器上，因为您正在阅读的网站就是用 NiceGUI 搭建的（NiceGUI 中文网就不是啦因为 VitePress 的性能实在是太高了，可读性也比 NiceGUI 官网好）。
用组件创建应用页面后，调用 ui.run() 来启动 NiceGUI 服务器。ui.run 的可选参数可以设置服务器绑定的网络地址和端口、是否以原生模式运行、初始窗口尺寸等众多选项。"配置与部署"章节详细介绍了 ui.run() 函数及其底层 FastAPI 框架的选项。
自定义扩展
如需更多定制，可以使用底层的 Tailwind 类和 Quasar 组件 来控制元素的样式或行为。您也可以通过继承现有 NiceGUI 组件或导入新的 Quasar 组件来扩展可用组件。所有这些功能都是可选的。开箱即用的 NiceGUI 已提供创建现代、时尚、响应式用户界面所需的一切。
测试框架
NiceGUI 提供基于 pytest 的完整测试框架，支持自动化测试用户界面。您可以使用 screen 夹具启动真实（无头）浏览器与应用交互，这对测试浏览器特定行为非常有用。
但大多数情况下，新引入的 user 夹具更适用：它仅在 Python 层面模拟用户交互，因此速度极快。这使得传统的测试金字塔模型（认为 UI 测试缓慢且昂贵）不再适用。这对开发速度、质量和信心都有重大提升。