Python Gui：NiceGui交互组件（输入类）

1 输入类组件概述

输入类组件是用户与应用交互的主要桥梁，NiceGui提供了丰富的输入组件类型：

2 单行文本输入 (ui.input)

基本用法

from nicegui import ui

name = ui.input(label='用户名', placeholder='输入您的姓名')

ui.label().bind_text_from(name, 'value', backward=lambda v: f'您输入了: {v}')

ui.run()

关键参数说明

表2-1 ui.input参数表

进阶功能示例

# 带验证的输入框

defvalidate_email(text):

return'@'in text if text elseTrue

email = ui.input(

  label='邮箱',

  placeholder='user@example.com',

  validation=validate_email

).props('type="email"')

# 动态提示

with ui.input('搜索') as search:

with search.add_slot('append'):

      ui.icon('search')

3 多行文本输入 (ui.textarea)

基本用法

comment = ui.textarea(

  label='留言',

  placeholder='请输入您的意见...',

  rows=5

).classes('w-full')

特殊功能实现

# 带字数统计的文本域

from nicegui import events

def update_counter(e: events.ValueChangeEventArguments):

  counter.set_text(f'{len(e.value)}/200')

textarea = ui.textarea(label='简介').on('update:model-value', update_counter)

counter = ui.label('0/200').classes('self-end')

4 数字输入 (ui.number)

基本数值输入

age = ui.number(

  label='年龄',

  min=0,

  max=120,

  step=1,

  value=18

)

带单位的输入框

with ui.number(label='温度', suffix='°C') as temp:

  with temp.add_slot('append'):

      ui.label('°C').classes('text-gray-500')

5 滑块输入 (ui.slider)

基本滑块

volume = ui.slider(

  min=0,

  max=100,

  value=50,

  on_change=lambda e: ui.notify(f'音量设置为: {e.value}%')

)

范围滑块

range_slider = ui.slider(

  min=0,

  max=100,

  value={'min': 20, 'max': 80},

  range=True

)

6 下拉选择 (ui.select)

单选下拉框

fruits = ['苹果', '香蕉', '橙子']

fruit_select = ui.select(

  options=fruits,

  label='选择水果',

  value='苹果'

)

多选下拉框

languages = ['Python', 'JavaScript', 'Java', 'C++']

lang_select = ui.select(

  options=languages,

  label='选择语言',

  multiple=True

).classes('w-full')

7 日期时间输入

日期选择器

date = ui.date(

  label='选择日期',

  value='2023-01-01',

  on_change=lambda e: ui.notify(f'选择了: {e.value}')

时间选择器

time = ui.time(

  label='选择时间',

  format='24h',

  value='14:30'

)

8 示例程序：用户注册表单

from nicegui import ui

defsubmit():

  ui.notify(f'注册成功! 用户名: {username.value}')

with ui.card().classes('w-96 p-4 mx-auto'):

  ui.label('用户注册').classes('text-2xl mb-4')

  username = ui.input(

      label='用户名',

      validation={'至少4个字符': lambda v: len(v) >= 4}

  )

  password = ui.input(

      label='密码',

      password=True,

      password_toggle_button=True

  )

  gender = ui.select(

      ['男', '女', '其他'],

      label='性别'

  )

  age = ui.number(

      label='年龄',

min=1,

max=120

  )

  ui.button('提交', on_click=submit)

ui.run()

将上述代码保存为inputEg.py，然后在终端执行：

python inputEg.py

运行效果如下：

9 输入组件高级应用

验证策略

即时验证（输入时）

提交时验证

复合验证规则

# 复合验证示例

defvalidate_username(name):

iflen(name) < 4:

return'用户名太短'

ifnot name.isalnum():

return'只能包含字母数字'

returnNone

ui.input('用户名').props('rules=[validate_username]')

性能优化

对高频更新使用防抖

大数据集使用虚拟滚动

# 防抖示例

from functools import partial

from datetime import datetime

def search(query):

  print(f'{datetime.now()} 搜索: {query}')

search_input = ui.input('实时搜索').on(

  'update:model-value',

  partial(ui.timer.debounce, search, timeout=0.5)

)

无障碍访问

始终设置label

使用ARIA属性

确保键盘可操作

ui.input(

  label='搜索框',

  placeholder='按Enter搜索'

).props('aria-label="Search box"')

10 常见问题排查

问题1：输入值无法获取

解决方案：

# 错误方式

value = ui.input().value  # 立即获取，此时为空

# 正确方式

input = ui.input()

value = input.value  # 在事件回调中获取

问题2：验证不生效

检查点：

验证函数返回True/False或错误信息

没有在on_change中覆盖验证

使用了正确的props名称

问题3：样式错乱

调试方法：

ui.input().style('border: 1px solid red')  # 添加调试边框

11 练习

任务：创建一个智能表单系统，要求：

根据用户选择的表单类型动态显示不同字段

实现级联选择（省市区三级联动）

添加表单验证和提交功能

提示代码结构：

更新日期：2025-05-17

交流讨论：欢迎在评论区留言！

重要提示：本文主要是记录自己的学习与实践过程，所提内容或者观点仅代表个人意见，只是我以为的，不代表完全正确，不喜请勿关注。