NiceGUI props 使用教程

PieroPC
62 阅读4分钟

NiceGUI .props() 完整列表教程

.props() 是 NiceGUI 中最强大的底层控制方法，用于设置 Quasar 组件的原生属性。

1. 基础语法

# 单个属性
element.props('flat')

# 多个属性（空格分隔）
element.props('flat color=primary size=lg')

# 布尔属性（直接写属性名）
element.props('disable readonly')

# 带特殊字符的值（用引号包裹）
element.props('placeholder="请输入内容..." rules="[val => val.length > 0]"')

2. 按组件分类的 Props 列表

image.png

🔵 按钮 Button

Props说明示例
flat扁平样式.props('flat')
outline轮廓样式.props('outline')
push按压效果.props('push')
round圆形.props('round')
glossy光泽效果.props('glossy')
size=xs|sm|md|lg|xl尺寸.props('size=lg')
color=primary|red|...背景色.props('color=red-5')
text-color=white|black文字色.props('text-color=white')
icon=edit|delete|...图标.props('icon=edit')
loading加载状态.props('loading')
disable禁用.props('disable')
ripple涟漪效果.props('ripple')

示例：

ui.button('保存').props('icon=save color=positive size=lg outline')

image.png

🟦 输入框 Input

Props说明示例
outlined轮廓边框.props('outlined')
filled填充背景.props('filled')
borderless无边框.props('borderless')
standout突出样式.props('standout')
disable禁用.props('disable')
readonly只读.props('readonly')
loading加载中.props('loading')
clearable可清空.props('clearable')
dense紧凑模式.props('dense')
prefix=前缀前缀文本.props('prefix=$')
suffix=后缀后缀文本.props('suffix=@email.com')
placeholder="..."占位符.props('placeholder="搜索..."')
type=password|email|...输入类型.props('type=password')
rules="[...]"验证规则`.props('rules="[val => !!val'必填']"')`

示例：

ui.input('邮箱').props('outlined placeholder="user@example.com" suffix=@email.com')

image.png

🟩 选择器 Select

Props说明示例
outlined轮廓边框.props('outlined')
filled填充背景.props('filled')
use-chips标签式显示.props('use-chips')
multiple多选模式.props('multiple')
use-input可搜索.props('use-input')
clearable可清空.props('clearable')
dense紧凑模式.props('dense')
options-dense选项紧凑.props('options-dense')

示例：

ui.select(['A', 'B', 'C']).props('multiple use-chips outlined')

image.png

🟨 复选框/单选 Checkbox/Radio

Props说明示例
indeterminate半选状态.props('indeterminate')
toggle切换开关样式.props('toggle')
color=positive|red颜色.props('color=positive')
size=xs|sm|md|lg|xl尺寸.props('size=lg')
disable禁用.props('disable')

示例：

ui.checkbox('同意').props('toggle color=positive')

image.png

🟧 卡片 Card

Props说明示例
flat无阴影.props('flat')
bordered有边框.props('bordered')
square直角.props('square')
dark暗色模式.props('dark')
elevation=0-24阴影深度.props('elevation=3')

示例：

ui.card().props('flat bordered').classes('p-4')

image.png

🟥 对话框 Dialog/Notification

Props说明示例
position=top|right|bottom|left位置.props('position=top')
color=positive|negative颜色.props('color=positive')
icon=check_circle图标.props('icon=check_circle')
timeout=3000自动关闭时间(ms).props('timeout=3000')
message="..."消息内容.props('message="操作成功"')
multi-line多行显示.props('multi-line')

示例：

ui.notify('保存成功！').props('position=top-right color=positive icon=check_circle timeout=2000')

🟪 布局与分隔

Props说明示例
gutter-x-xs|sm|md|lg|xl水平间距.props('gutter-x-md')
gutter-y-xs|sm|md|lg|xl垂直间距.props('gutter-y-sm')
spaced均匀间隔.props('spaced')
inset缩进分隔线.props('inset')
vertical垂直分隔.props('vertical')

示例：

ui.row().props('gutter-x-md gutter-y-sm')

3. 动态修改 Props

btn = ui.button('提交')

# 运行时添加属性
btn.props('loading')  # 变为加载状态

# 运行时移除属性
btn.props('remove loading')  # 移除加载状态

# 替换所有 props
btn.props('flat color=red')  # 覆盖之前的 props

# 获取当前 props
print(btn.props)  # 输出: flat color=red

4. Props vs Classes vs Style

方法作用优先级使用场景
.props()控制组件行为和类型低改变按钮样式、输入框类型、验证规则
.classes()控制布局和外观中调整边距、颜色、字体大小
.style()精细微调高自定义圆角、阴影、动画

协作示例

ui.button('保存').props('icon=save color=primary').classes('px-6 py-2').style('border-radius: 8px; font-weight: 600')

5. 高级技巧

A. 条件 Props

is_loading = True
btn = ui.button('提交')
if is_loading:
    btn.props('loading disable')
else:
    btn.props('remove loading remove disable')

B. 字典转 Props

props_dict = {
    'color': 'primary',
    'size': 'lg',
    'flat': True  # 布尔值直接写
}
props_str = ' '.join([f'{k}={v}' if not isinstance(v, bool) else k for k, v in props_dict.items()])
ui.button('动态').props(props_str)

C. 验证规则 Props

ui.input('密码').props('type=password rules="[val => val.length >= 8 || \'至少8位\']"')

6. 常见 Props 值参考

颜色系统（Quasar 标准）

  • primary, secondary, accent
  • positive, negative, info, warning
  • red-1 到 red-14, blue-1 到 blue-14, 等
  • dark, light

尺寸系统

  • xs (12px), sm (14px), md (16px), lg (20px), xl (24px)

位置

  • top, right, bottom, left
  • top-left, top-right, bottom-left, bottom-right

7. 调试与查找

快速调试

# 在浏览器控制台查看实际渲染的元素
# 1. 右键点击元素 -> 检查
# 2. 查看 class 和 data-v-* 属性
# 3. 这些就是 props 的实际效果

查找可用 Props

  1. Quasar 官方文档: quasar.dev/vue-compone…
  2. 浏览器 DevTools: 查看渲染后的 HTML 属性
  3. NiceGUI 源码: nicegui/elements/ 目录下的组件定义

8. 实战完整示例

image.png

from nicegui import ui

# 复杂表单
with ui.card().props('flat bordered'):
    ui.label('用户注册').props('text-h5').classes('mb-4')
    
    ui.input('用户名').props(
        'outlined dense rules="[val => val.length > 0 || \'必填\']" placeholder="输入用户名"'
    ).classes('w-full mb-2')
    
    ui.input('邮箱').props(
        'outlined dense type=email placeholder="user@example.com" suffix=@email.com'
    ).classes('w-full mb-2')
    
    ui.select(['男', '女', '其他']).props(
        'outlined dense use-chips'
    ).classes('w-full mb-4')
    
    with ui.row().props('gutter-x-sm'):
        ui.button('提交').props('color=positive outline size=lg')
        ui.button('取消').props('color=negative flat')
        
    ui.checkbox('同意协议').props('toggle color=primary')

ui.run()

总结：.props() 是连接 NiceGUI 和 Quasar 的桥梁，掌握它能让你的 UI 更专业、更灵活！

avatar
文章
阅读
粉丝