Обзор NiceGUI: веб-интерфейс из Python объясняет, как библиотека собирает страницу из готовых элементов и отдаёт её в браузер через HTTP-сервер. Документация проекта на nicegui.io называет NiceGUI открытой Python-библиотекой для графических интерфейсов, работающих в браузере. Ниже — разбор того, что инструмент делает, как связать контролы с Python-callback и где проходят его границы.
Что делает NiceGUI
Документация проекта на nicegui.io описывает NiceGUI как открытую Python-библиотеку для графических интерфейсов, которые работают в браузере. Реализация опирается на HTML-компоненты, которые отдаёт HTTP-сервер на FastAPI, и это верно даже для нативных окон. Практический вывод для читателя: код на Python описывает интерфейс, а браузер получает готовую страницу.
README проекта в репозитории zauberzeug/nicegui добавляет, что речь идёт о browser-based graphical user interface. Там же названы multi-page и single-page приложения, то есть библиотека покрывает оба способа организации страниц. Для небольшой внутренней панели этого достаточно: одна страница со списком заявок и фильтром закрывает типовую задачу.
README упоминает implicit reload on code change. Во время разработки правка файла перезапускает приложение, и цикл «изменил — посмотрел» сокращается. Это удобно на этапе проектирования, когда вы подбираете состав колонок и поведение фильтра.
Отдельно README говорит о straightforward data binding and refreshable functions to write even less code. Связывание данных и обновляемые функции уменьшают объём ручного кода обновления интерфейса. Документация на nicegui.io уточняет механику: элементы можно привязать к модели, объекту данных, и интерфейс обновляется автоматически при изменении значения модели.
Здесь же лежит важное ограничение. Документация проекта предупреждает, что все обновления UI должны происходить в главном потоке с его event loop. Если вы запускаете фоновую работу, результат возвращается в основной цикл. Это влияет на архитектуру: длительные операции выносятся отдельно, а обновление элементов остаётся в главном потоке.
Сравнение с соседним инструментом помогает выбрать. В типичном приложении Streamlit взаимодействие вызывает повторный прогон скрипта; для сохранения состояния между такими прогонами предусмотрен session state. NiceGUI держит приложение как сервер с элементами и обработчиками, поэтому панель с таблицей и фильтром описывается привычным образом. Для форм, таблиц и кнопок это даёт более прямой контроль над состоянием.
Контролы и Python-callback
Контролы в NiceGUI — это Python-объекты. Вы создаёте select, input, table или button, и каждый из них принимает обработчик. Исходный код элемента input в репозитории проекта фиксирует поведение события on_change: оно вызывается на каждое нажатие клавиши, и значение обновляется соответственно. Для поля поиска это означает живой отклик, для тяжёлой проверки — лишние вызовы.
Там же описана валидация. Ключ первого правила, которое не прошло проверку, показывается как сообщение об ошибке. Такой порядок задаёт приоритет сообщений: читатель видит первую причину отказа. Метод without_auto_validation отключает автоматическую проверку при каждом изменении значения, и тогда проверку запускают в удобный момент.
Практический порядок работы с контролами:
- Создайте элемент и сохраните ссылку в переменной.
- Передайте функцию-обработчик в параметр события.
- Внутри обработчика меняйте данные и обновляйте связанные элементы.
- Проверьте поведение при пустом вводе и при недопустимом значении.
- Убедитесь, что обновление интерфейса идёт в главном потоке.
Промпт ниже помогает спроектировать обработчики для панели заявок. Это заготовка запроса к модели, её можно скопировать и подставить свои значения.
Ты помогаешь спроектировать панель заявок на NiceGUI.
Дано: rows = [{id: 1, title: "Обложка", status: "new"},
{id: 2, title: "Текст", status: "done"},
{id: 3, title: "Ссылки", status: "new"}].
Нужны: select статуса со значениями all/new/done, таблица с колонками ID/title/status,
кнопка закрытия конкретного ID.
Опиши для каждого контрола: какой обработчик вызывается, что он меняет в rows,
какой элемент обновляется после этого.
Отдельно перечисли проверки: недопустимый ID, пустой фильтр, повторный клик по кнопке.
Тему панели возьми [ваша тема], стиль интерфейса — [ваш стиль].
В промпте меняйте тему и стиль, а также состав колонок. Список rows оставьте как учебный вход, чтобы сверять поведение фильтров с ожидаемым результатом.
Данные и отображение
Таблица — основной элемент для списка заявок. Исходный код table.py в репозитории проекта сообщает, что обновления попадают в таблицу через изменение свойств rows или columns. После правки исходных данных передайте обновлённые rows таблице. В примере ниже затем явно вызывается table.update().
Там же указано, что колонка с уникальными данными строки называется по умолчанию id. Уникальный ключ нужен, чтобы таблица различала строки при обновлении. Если в ваших данных идентификатор называется иначе, это учитывается при настройке колонок.
Для выбора строк исходный код описывает свойство selected. Оно доступно, когда selection равен single или multiple, и содержит выбранные строки. Так строится сценарий «выбрал заявку — нажал кнопку — статус изменился».
Связывание с моделью из документации проекта дополняет картину. Элемент привязывается к объекту данных, и интерфейс обновляется при изменении значения модели. Для панели это означает: храните rows в одном месте, а таблица и счётчики читают то же состояние.
| Элемент | Что задаёт | Что проверять |
|---|---|---|
| select | значение фильтра all/new/done | сброс к all и пустой выбор |
| table | rows и columns | уникальный ключ строки, обновление после правки |
| button | обработчик закрытия по ID | недопустимый ID и повторный клик |
| input | значение и on_change | частота вызовов при вводе |
| модель | объект данных | обновление интерфейса при изменении |
Таблица выше задаёт порядок проверки. Сначала фильтр, затем состав строк, затем действие по кнопке. Такой порядок ловит ошибки на раннем шаге, когда причина ещё очевидна.
Полный учебный набор
Ниже — учебный пример панели заявок. Это авторский fixture: реальный запуск внешнего сервиса, обучение модели, измерение скорости и платные API здесь не заявлены. Результат сверяется с заданным входом, а параметры продукта — с текущей документацией.
import os
from nicegui import ui
rows = [
{"id": 1, "title": "Обложка", "status": "new"},
{"id": 2, "title": "Текст", "status": "done"},
{"id": 3, "title": "Ссылки", "status": "new"},
]
columns = [
{"name": "id", "label": "ID", "field": "id"},
{"name": "title", "label": "Title", "field": "title"},
{"name": "status", "label": "Status", "field": "status"},
]
@ui.page("/")
def panel():
state = {"filter": "all"}
def visible_rows():
return [dict(row) for row in rows
if state["filter"] == "all"
or row["status"] == state["filter"]]
def refresh():
table.rows = visible_rows()
table.update()
def on_filter_change(event):
state["filter"] = event.value or "all"
refresh()
def close_selected_id():
try:
row_id = int(id_input.value.strip())
except (ValueError, AttributeError):
ui.notify("Введите целый ID")
return
for row in rows:
if row["id"] == row_id:
row["status"] = "done"
refresh()
return
ui.notify(f"ID {row_id} не найден")
ui.select(["all", "new", "done"], value="all", label="Статус",
on_change=on_filter_change)
table = ui.table(columns=columns, rows=visible_rows(), row_key="id")
id_input = ui.input("ID для закрытия")
ui.button("Закрыть", on_click=close_selected_id)
ui.run(host=os.environ.get("NICEGUI_HOST", "127.0.0.1"),
port=int(os.environ.get("NICEGUI_PORT", "8080")))
Порядок работы с примером:
- Сохраните код в файл app.py.
- Установите библиотеку командой pip install nicegui.
- Запустите python app.py и откройте адрес из вывода.
- Проверьте фильтр all: видны строки 1, 2, 3.
- Переключите фильтр new: остаются 1 и 3.
- Переключите фильтр done: остаётся 2.
- Введите 3 в поле ID, нажмите «Закрыть» и повторите проверку фильтров. Затем проверьте пустой ввод, неизвестный ID 99 и повторное закрытие 3.
После закрытия ID 3 фильтр new показывает 1, а done показывает 2 и 3. Недопустимый ID 99 даёт сообщение и оставляет rows без изменений. Хост и порт читаются из переменных окружения, секреты в коде не хранятся.
Фильтр и изменение статуса
Фильтр — это функция от состояния и данных. В примере состояние фильтра лежит в словаре state, а visible_rows возвращает подмножество rows. Такое разделение упрощает проверку: вы меняете одно значение и сравниваете состав строк.
Исходный набор даёт три ожидаемых результата. Фильтр all показывает 1, 2, 3. Фильтр new показывает 1 и 3. Фильтр done показывает 2. Эти три проверки стоит выполнить до изменения статусов, чтобы убедиться в корректности отбора.
Изменение статуса затрагивает данные. После перевода ID 3 в done фильтр new показывает 1, а done показывает 2 и 3. Проверка подтверждает, что обновление дошло до таблицы и что отбор читает актуальные значения.
Ошибки ввода обрабатываются отдельно. Недопустимый ID 99 приводит к сообщению и оставляет rows без изменений. Это ожидаемое поведение: операция не проходит, данные сохраняются, читатель видит причину.
| Действие | Фильтр | Ожидаемый состав |
|---|---|---|
| исходно | all | 1, 2, 3 |
| исходно | new | 1, 3 |
| исходно | done | 2 |
| закрыть ID 3 | new | 1 |
| закрыть ID 3 | done | 2, 3 |
| закрыть ID 99 | любой | без изменений |
Таблица служит эталоном для сверки. Если состав строк отличается, ищите причину в функции отбора и в моменте обновления таблицы.
Сессии и доступ
В примере state и элементы интерфейса создаются внутри функции страницы с @ui.page, поэтому каждый её клиент получает свой словарь фильтра. Это конструкция нашего кода: глобальный state дал бы другую область данных. Требование приёмки — фильтр клиента A=new не переключает фильтр клиента B=done; проверьте это в двух браузерных контекстах.
Общие данные и доступ настраиваются явно. В нашем коде rows — общий список процесса, а state — локальный фильтр клиента. Правка статуса меняет общий список, однако refresh вызывается только для текущего клиента. Для остальных клиентов нужно отдельно организовать обновление отображения. Для нескольких процессов и постоянного хранения нужен общий слой данных.
Проверка многопользовательского режима требует двух браузерных контекстов и фактической проверки изоляции. В учебном примере инструмент не поднимался, поэтому выводы ограничены логикой кода. Для рабочей панели такую проверку выполняют на развёрнутом приложении.
Доступ к сервису и его API проверяется отдельно. Успешное размещение таблицы на странице подтверждает работу интерфейса и не подтверждает auth. Аутентификацию и права на операции закрытия заявок настраивают поверх интерфейса и проверяют своими сценариями.
Если в панель добавляют длительное действие, например обращение к внешнему источнику, состояние операции описывают полностью: running, success, error. Повторное нажатие кнопки и недоступность источника проверяют до того, как называть приложение надёжным. Обновление интерфейса при этом остаётся в главном потоке, как указывает документация проекта.
Границы инструмента
NiceGUI покрывает веб-интерфейс, контролы, таблицы, формы и фоновую работу. Документация проекта описывает привязку элементов к модели и обновление интерфейса при изменении значения. README называет одностраничные и многостраничные приложения. Этого набора достаточно для внутренней панели.
Рассматриваемый маршрут — веб-панель в браузере. Упомянутые документацией нативные окна также используют HTTP-сервер на FastAPI. Если нужна отдельная мобильная сборка, оцените этот путь отдельно до выбора архитектуры.
Общее состояние для всех пользователей настраивается явно. Локальный фильтр сессии остаётся локальным, а общие данные требуют отдельного места хранения. Это влияет на проектирование: определите, что принадлежит сессии, а что является общим ресурсом.
Длительные операции требуют аккуратности. Обновления UI идут в главном потоке с его event loop, поэтому фоновая работа возвращает результат в основной цикл. Состояния running, success и error описывают заранее, а повтор кнопки и недоступность источника проверяют на практике.
Сверяйте параметры с текущей документацией. Библиотека развивается, и аргументы элементов могут отличаться между версиями. Учебный пример выше задаёт логику панели, а конкретные имена параметров уточняйте по актуальной документации проекта.
Частые вопросы
Что такое NiceGUI простыми словами?
Документация проекта на nicegui.io называет NiceGUI открытой Python-библиотекой для графических интерфейсов, работающих в браузере. Вы пишете код на Python, а пользователь открывает страницу в браузере. Реализация опирается на HTML-компоненты, которые отдаёт HTTP-сервер на FastAPI.
Чем NiceGUI отличается от Streamlit?
Streamlit строит интерфейс вокруг перезапуска скрипта при взаимодействии. NiceGUI держит приложение как сервер с элементами и обработчиками, поэтому таблица, фильтр и кнопка описываются как объекты с callback. Подход к состоянию и событиям нужно выбирать под свою панель.
Как связать кнопку с Python-функцией?
Создайте элемент и передайте функцию в параметр события, например on_click. Внутри функции меняйте данные и обновляйте связанные элементы. Исходный код input.py в репозитории проекта показывает, что on_change вызывается на каждое нажатие клавиши, и значение обновляется соответственно.
Как обновить таблицу после изменения данных?
Исходный код table.py в репозитории проекта сообщает, что обновления попадают в таблицу через изменение свойств rows или columns. Присвойте новое значение rows и вызовите обновление. Уникальный ключ строки задаётся колонкой id по умолчанию.
Почему фильтр одного пользователя не влияет на другого?
В нашем коде словарь фильтра создаётся внутри функции страницы @ui.page, отдельно для каждого клиента. Общий список rows объявлен снаружи; обновление его отображения у других клиентов и права доступа требуют отдельной настройки. Для многопользовательского режима проверяют два браузерных контекста и фактическую изоляцию.
