Python NiceGUI 中可用的 Quasar 属性速查清单

# 尺寸'size="xs|sm|md|lg|xl"'# 预设尺寸'style="width: 100px; height: 50px"'# 内联样式# 间距'class="q-ma-md q-pa-sm"'# 外边距和内边距'no-margins'# 无外边距# 颜色'color="primary|secondary|accent|positive|negative|info|warning|dark|light|white|black|transparent"''text-color="..."'# 文字颜色'bg-color="..."'# 背景颜色# 主题'dark'# 暗色模式'light'# 亮色模式# 显示'hide'# 隐藏'hidden'# 隐藏（CSS）'show'# 显示'display="none|inline|block|flex|inline-flex"'

'disabled'# 禁用状态'readonly'# 只读状态'loading'# 加载状态'selected'# 选中状态'active'# 激活状态'highlight'# 高亮'focusable'# 可获得焦点'tabindex="0|1|-1"'# Tab 键顺序

# 断点相关'v-if="$q.screen.lt.sm"'# 屏幕宽度小于 sm'v-else-if="$q.screen.gt.md"'# 屏幕宽度大于 md':class="{ \'q-ml-sm\': $q.screen.gt.xs }"'# 条件类名# 方向'vertical'# 垂直方向'horizontal'# 水平方向'reverse'# 反向

# 类型'type="button|submit|reset|a"'# 按钮类型'outline'# 轮廓按钮'flat'# 扁平按钮'unelevated'# 无阴影按钮'push'# 按压效果'glossy'# 光泽效果# 形状'round'# 圆形按钮'rounded'# 圆角按钮'square'# 方形按钮# 图标'icon="material-icons-name"'# 图标名称'icon-right="icon-name"'# 右侧图标'icon-color="primary"'# 图标颜色'no-icon-animation'# 无图标动画# 标签'label="Button text"'# 按钮文本'no-caps'# 无大写转换'no-wrap'# 文本不换行'align="left|center|right"'# 文本对齐# 颜色和大小'color="primary"'# 颜色'text-color="white"'# 文字颜色'size="xs|sm|md|lg|xl"'# 尺寸'dense'# 紧凑模式'padding="xs|sm|md|lg|xl"'# 内边距

'to="/path"'# 路由跳转'href="https://..."'# 外部链接'target="_blank|_self|_parent|_top"'# 链接目标'disable'# 禁用'loading'# 加载状态'ripple'# 涟漪效果':ripple="{ center: true, color: \'primary\' }"'# 涟漪配置'no-ripple'# 无涟漪效果

# 外观变体'filled'# 填充样式'outlined'# 轮廓样式'borderless'# 无边框'standout'# 突出样式'rounded'# 圆角'square'# 方形'dense'# 紧凑# 标签和提示'label="Field label"'# 标签'stack-label'# 堆叠标签'hint="Helper text"'# 提示文本'hide-hint'# 隐藏提示'hide-bottom-space'# 隐藏底部空间# 前缀后缀'prefix="Prefix"'# 前缀文本'suffix="Suffix"'# 后缀文本'prefix-icon="icon-name"'# 前缀图标'suffix-icon="icon-name"'# 后缀图标# 功能属性'clearable'# 可清除'autofocus'# 自动聚焦'autocomplete="on|off"'# 自动完成'autocapitalize="on|off"'# 自动大写'spellcheck="true|false"'# 拼写检查'readonly'# 只读'disable'# 禁用# 计数器'counter'# 显示计数器'maxlength="100"'# 最大长度'lazy-rules'# 延迟验证# 验证':rules="[val => val.length > 3 || \'Minimum 4 characters\']"'# 验证规则'error'# 错误状态'error-message="Error text"'# 错误信息# 类型'type="text|password|textarea|email|search|tel|file|number|url|time|date"''mask="###-###"'# 输入掩码'unmasked-value'# 未掩码值

# 基础属性（继承 QInput）'filled|outlined|borderless|standout''rounded|square|dense'# 选择模式'multiple'# 多选'use-chips'# 使用标签显示'use-input'# 可输入搜索'new-value-mode="add|add-unique|toggle"'# 新值模式'hide-selected'# 隐藏已选# 下拉菜单'menu-anchor="bottom left|top right"'# 菜单锚点'menu-self="top left"'# 菜单自身位置'menu-offset="[10, 10]"'# 菜单偏移'menu-shrink'# 菜单收缩'menu-cover'# 菜单覆盖'transition-show="scale|fade"'# 显示过渡'transition-hide="scale|fade"'# 隐藏过渡# 选项配置':options="optionsArray"'# 选项数组'option-value="id"'# 值字段名'option-label="name"'# 标签字段名'option-disable="disabled"'# 禁用字段名'options-dense'# 紧凑选项'options-selected-class="text-primary"'# 选中选项类# 行为'emit-value'# 发射值而非对象'map-options'# 映射选项'behavior="menu|dialog"'# 行为模式'popup-content-class="custom-class"'# 弹出内容类

# 基础属性'label="Checkbox label"'# 标签'left-label'# 标签在左侧'color="primary"'# 颜色'keep-color'# 保持颜色'dark'# 暗色模式'dense'# 紧凑'size="xs|sm|md|lg|xl"'# 尺寸# 状态值'indeterminate-value="-1"'# 不确定状态值'true-value="true"'# 真值'false-value="false"'# 假值# 图标'checked-icon="check"'# 选中图标'unchecked-icon="clear"'# 未选中图标'indeterminate-icon="remove"'# 不确定图标# 行为'toggle-order="tf|ft"'# 切换顺序'disable'# 禁用'readonly'# 只读

# 基础属性'label="Toggle label"'# 标签'left-label'# 标签在左侧'color="green"'# 颜色'keep-color'# 保持颜色'icon="alarm"'# 图标'icon-color="red"'# 图标颜色# 样式'checked-icon="check"'# 选中图标'unchecked-icon="clear"'# 未选中图标'spread'# 分散布局# 行为'true-value="yes"'# 真值'false-value="no"'# 假值'disable'# 禁用'readonly'# 只读

# 基础属性'label="Radio label"'# 标签'left-label'# 标签在左侧'color="primary"'# 颜色'keep-color'# 保持颜色'dense'# 紧凑'val="option1"'# 选项值# 图标'checked-icon="done"'# 选中图标'unchecked-icon="panorama_fish_eye"'# 未选中图标# 布局'inline'# 内联显示'disable'# 禁用'readonly'# 只读

# 显示'label'# 标签'label-value="value + \'%\''# 自定义标签值'label-always'# 总是显示标签'label-color="primary"'# 标签颜色'markers'# 显示刻度'snap'# 吸附到刻度# 范围'min="0"'# 最小值'max="100"'# 最大值'step="1"'# 步长'inner-min="20"'# 内边界最小值'inner-max="80"'# 内边界最大值# 样式'color="primary"'# 颜色'track-color="grey-4"'# 滑块尺寸                    # 轨道颜色'selection-color="primary"'# 选择区域颜色'thumb-color="primary"'# 滑块颜色'thumb-size="20px"'# 滑块尺寸# 方向'vertical'# 垂直方向'reverse'# 反向# 行为'drag-range'# 拖拽范围'drag-only-range'# 仅拖拽范围'disable'# 禁用'readonly'# 只读

# 样式'flat'# 扁平'bordered'# 带边框'square'# 方形'dark'# 暗色模式# 尺寸'width="300px"'# 宽度'height="200px"'# 高度'style="max-width: 500px"'# 样式# 内容区域'title="Card title"'# 标题'title-class="text-h6"'# 标题类'actions-align="left|right|center|between|around|evenly"'# 动作对齐# 交互'clickable'# 可点击'v-ripple'# 涟漪效果':to="/path"'# 路由'disable'# 禁用

# 颜色'color="primary"'# 颜色'text-color="white"'# 文字颜色'bg-color="blue"'# 背景颜色# 样式'inset'# 内嵌'glossy'# 光泽'dense'# 紧凑# 位置'fixed'# 固定位置'absolute'# 绝对定位'sticky'# 粘性定位'top'# 顶部'bottom'# 底部# 内容'title="Toolbar title"'# 标题'title-align="left|center|right"'# 标题对齐'title-class="text-h4"'# 标题类

# 外观'align="left|center|right|justify"'# 对齐方式'breakpoint="600"'# 断点'narrow-indicator'# 窄指示器'indicator-color="primary"'# 指示器颜色'active-color="primary"'# 激活颜色'inactive-color="grey"'# 非激活颜色# 内容'content-class="custom-class"'# 内容类'left-icon="chevron_left"'# 左侧图标'right-icon="chevron_right"'# 右侧图标# 行为'no-caps'# 无大写'shrink'# 收缩'stretch'# 拉伸'switch-indicator'# 切换指示器'vertical'# 垂直标签

# 内容'label="Tab label"'# 标签'icon="home"'# 图标'alert="red"'# 提醒标记'alert-icon="notifications"'# 提醒图标# 状态'name="tab1"'# 名称（标识）'disable'# 禁用'no-caps'# 无大写'ripple'# 涟漪效果

# 容器'view="hHh lpR fFf"'# 布局视图模式'container'# 容器模式# 页面'page-container'# 页面容器'fullscreen'# 全屏# 头部'header'# 头部区域'header-height-hint="100"'# 头部高度提示'header-elevated'# 头部提升# 尾部'footer'# 尾部区域'footer-height-hint="50"'# 尾部高度提示# 抽屉'left-drawer'# 左侧抽屉'right-drawer'# 右侧抽屉'drawer-width="250"'# 抽屉宽度'drawer-breakpoint="1024"'# 抽屉断点'drawer-behavior="default|mobile|desktop"'# 抽屉行为

# 外观'flat'# 扁平'bordered'# 带边框'square'# 方形'grid'# 网格模式'dark'# 暗色模式'separator="horizontal|vertical|cell|none"'# 分隔线'wrap-cells'# 单元格换行# 功能'virtual-scroll'# 虚拟滚动'row-key="id"'# 行键名'selection="single|multiple|none"'# 选择模式'selected-rows="selected"'# 选中行绑定'pagination'# 分页':pagination="{ rowsPerPage: 10, page: 1 }"'# 分页配置# 过滤和排序'filter="searchText"'# 过滤文本'filter-method="customFilter"'# 过滤方法'sort-method="customSort"'# 排序方法'no-data-label="No data available"'# 无数据提示'no-results-label="No matching results"'# 无结果提示# 加载状态'loading'# 加载中'loading-label="Loading data..."'# 加载提示'hide-bottom'# 隐藏底部'hide-pagination'# 隐藏分页'hide-selected-banner'# 隐藏选中横幅# 密度'dense'# 紧凑模式'compact'# 超紧凑模式

columns = [    {'name': 'name',                     # 列标识'label': 'Name',                    # 列标题'field': 'name',                    # 数据字段'align': 'left|center|right',       # 对齐方式'sortable': True,                   # 可排序'sort': None,                       # 自定义排序函数'format': None,                     # 格式化函数'style': 'width: 100px',            # 样式'classes': 'text-bold',             # CSS 类'headerStyle': 'background: #f0f0f0',  # 表头样式'headerClasses': 'bg-grey-3',       # 表头类'required': False,                  # 必需列'filter': True,                     # 可过滤    }]

6. 对话框和弹出层

6.1 QDialog 属性

# 位置和尺寸'position="standard|top|bottom|right|left"'# 位置'maximized'# 最大化'fullscreen'# 全屏'full-width'# 全宽度'full-height'# 全高度'width="500"'# 宽度'height="400"'# 高度# 行为'persistent'# 持久化'seamless'# 无缝'no-backdrop-dismiss'# 点击背景不关闭'no-esc-dismiss'# ESC 键不关闭'auto-close'# 自动关闭# 过渡动画'transition-show="slide-up|slide-down|slide-left|slide-right|fade|scale|rotate"''transition-hide="slide-up|slide-down|slide-left|slide-right|fade|scale|rotate"''transition-duration="300"'# 过渡持续时间# 滚动'no-refocus'# 不重新聚焦'no-focus'# 不获取焦点'scroll="propagate|refuse"'# 滚动行为

6.2 QMenu 属性

# 位置'anchor="bottom left|top right"'# 锚点'self="top left"'# 自身位置'offset="[10, 10]"'# 偏移'cover'# 覆盖'shrink'# 收缩'fit'# 适应'persistent'# 持久化# 外观'max-height="300px"'# 最大高度'max-width="200px"'#最大宽度'dark'# 暗色模式'content-class="custom-menu"'# 内容类'content-style="background: #fff"'# 内容样式# 行为'auto-close'# 自动关闭'no-route-dismiss'# 路由切换不关闭'context-menu'# 上下文菜单'touch-position'# 触摸位置'separate-close-popup'# 分离关闭弹出层

6.3 QPopupProxy 属性

'breakpoint="1024"'# 断点'context-menu'# 上下文菜单'touch-position'# 触摸位置'self="top left"'# 自身位置'cover'# 覆盖'no-parent-event'# 无父事件'no-refocus'# 不重新聚焦

7. 日期时间组件

7.1 QDate 属性

# 外观'filled|outlined|borderless|standout''rounded|square|dense'# 选择模式'multiple'# 多选日期'range'# 范围选择'landscape'# 横向模式# 功能'today-btn'# 今天按钮'years-in-month-view'# 月视图中显示年'default-year-month="2024/06"'# 默认年月'first-day-of-week="0|1"'# 周起始日（0=周日）# 格式和区域'mask="YYYY/MM/DD"'# 日期格式'locale="en-us"'# 区域设置# 导航'minimal-navigation'# 最小化导航'show-adjacent-months'# 显示相邻月份'hide-navigation'# 隐藏导航'default-view="Calendar"'# 默认视图# 选项':options="date => date.getDay() !== 0"'# 可选日期函数'events="events"'# 事件标记'event-color="red"'# 事件颜色

7.2 QTime 属性

# 格式'format24h'# 24小时制'with-seconds'# 包含秒'mask="HH:mm"'# 时间格式# 外观'filled|outlined|borderless|standout''rounded|square|dense''landscape'# 横向模式# 功能'now-btn'# 现在按钮'lazy-rules''default-view="Hours"'# 默认视图# 选项':options="[time => time.hour >= 9 && time.hour <= 17]"'# 可选时间

8. 进度指示器

8.1 QLinearProgress 属性

# 显示'instant-feedback'# 即时反馈'show-value'# 显示值'rounded'# 圆角'stripe'# 条纹'animate'# 动画# 值和缓冲'value="50"'# 当前值（0-100）'buffer="75"'# 缓冲值（0-100）'indeterminate'# 不确定状态# 颜色'color="primary"'# 颜色'track-color="grey-4"'# 轨道颜色'reverse'# 反向'dark'# 暗色模式# 尺寸'size="xs|sm|md|lg|xl"'# 尺寸'height="10px"'# 高度

8.2 QCircularProgress 属性

# 外观'show-value'# 显示值'font-size="20px"'# 字体大小'thickness="0.2"'# 厚度（0-1）'angle="0"'# 起始角度（度）'rounded'# 圆角# 值和状态'value="65"'# 当前值（0-100）'indeterminate'# 不确定状态'reverse'# 反向# 颜色'color="primary"'# 颜色'center-color="white"'# 中心颜色'track-color="grey-4"'# 轨道颜色# 动画'animate'# 动画'animation-speed="600"'# 动画速度（ms）

8.3 QSpinner 属性

# 类型'spinner="audio|ball|bars|circles|cube|dots|grid|hearts|oval|puff|rings|tail-spin|three-dots"'# 尺寸和颜色'size="xs|sm|md|lg|xl|40px"'# 尺寸'color="primary"'# 颜色'thickness="2"'# 厚度# 速度'speed="100"'# 速度（ms）

9. 通知和消息

9.1 QNotification 属性（通过 ui.notify）

# 位置'position="top-left|top-right|bottom-left|bottom-right|top|bottom|left|right|center"'# 类型'type="positive|negative|warning|info|ongoing"''color="primary"'# 颜色'text-color="white"'# 文字颜色'icon="info"'# 图标'icon-color="white"'# 图标颜色# 内容'message="Notification text"'# 消息'caption="Additional info"'# 副标题'multi-line'# 多行显示'html'# HTML 内容# 行为'timeout="5000"'# 超时时间（ms）'close-btn="Close"'# 关闭按钮文本'progress'# 显示进度条'actions="[{ icon: \'close\', color: \'white\', handler: closeFn }]"'# 操作按钮'group="false"'# 不分组

9.2 QBanner 属性

# 外观'rounded'# 圆角'dense'# 紧凑'inline-actions'# 内联操作# 内容'icon="warning"'# 图标'icon-color="warning"'# 图标颜色# 行为'sticky'# 粘性'actions="[{ label: \'Action\', color: \'primary\', handler: actionFn }]"'

10. 文件上传 (QUploader)

# 外观'flat|outlined|borderless|standout''rounded|square|dense''color="primary"'# 功能'auto-upload'# 自动上传'multiple'# 多文件'accept=".jpg,.png,.pdf"'# 接受的文件类型'max-file-size="1048576"'# 最大文件大小（字节）'max-files="5"'# 最大文件数'max-total-size="5242880"'# 最大总大小# 显示'hide-upload-btn'# 隐藏上传按钮'no-thumbnails'# 无缩略图'hide-file-list'# 隐藏文件列表# 标签'label="Choose files"'# 标签'browse-icon="folder_open"'# 浏览图标'upload-icon="cloud_upload"'# 上传图标# 状态'disable'# 禁用'readonly'# 只读'reverse'# 反向

11. 图表组件 (QChart)

# 容器'style="height: 300px"'# 容器样式'class="shadow-2"'# 容器类# 配置':options="chartOptions"'# 图表配置对象':series="chartSeries"'# 数据系列':title="{ text: \'Chart Title\' }"'# 标题配置# 交互':plotOptions="{bar: {horizontal: true, borderRadius: 5}}"'# 绘图选项':tooltip="{shared: true, intersect: false}"'# 工具提示':legend="{position: \'bottom\', horizontalAlign: \'center\'}"'# 图例# 主题':theme="{mode: \'dark\', palette: \'palette1\'}"'# 主题配置# 事件'@dataPointSelection="handleSelection"'# 数据点选择事件'@legendClick="handleLegendClick"'# 图例点击事件

12. 树形组件 (QTree)

# 节点配置'node-key="id"'# 节点键名'default-expand-all'# 默认展开所有'expanded="expandedNodes"'# 展开的节点'expand-icon="folder_open"'# 展开图标'selected-icon="check"'# 选择模式'selected="selectedNodes"'# 选中节点'multiple'# 多选'tick-strategy="leaf|leaf-filtered|strict"'# 勾选策略'no-selection-unset'# 无选择不取消设置# 过滤'filter="filterText"'# 过滤文本'filter-method="customFilter"'# 过滤方法'no-nodes-label="No nodes"'# 无节点提示'no-results-label="No matching nodes"'# 无结果提示# 样式'dense'# 紧凑模式'dark'# 暗色模式'color="primary"'# 颜色

13. 轮播组件 (QCarousel)

# 动画'animated'# 动画效果'infinite'# 无限循环'autoplay'# 自动播放'autoplay-interval="3000"'# 自动播放间隔（ms）'transition-prev="slide-right"'# 上一个过渡'transition-next="slide-left"'# 下一个过渡# 控制'arrows'# 显示箭头'navigation'# 显示导航点'navigation-position="top|bottom|left|right"''navigation-icon="lens"'# 导航点图标'navigation-active-icon="radio_button_checked"'# 显示'height="300"'# 高度'padding'# 内边距'thumbnails'# 显示缩略图'vertical'# 垂直方向'dark'# 暗色模式

14. 分割面板 (QSplitter)

# 方向'horizontal'# 水平分割'vertical'# 垂直分割# 尺寸'unit="%"'# 单位'limits="[20, 80]"'# 限制范围'separator-style="width: 5px; background: #ccc"''separator-class="custom-separator"'# 行为'disable'# 禁用'reverse'# 反向'before-class="bg-blue-1"'# 前部面板类'after-class="bg-green-1"'# 后部面板类

15. 使用示例

按钮示例

from nicegui import uiui.button('高级按钮',    color='primary',    icon='rocket',    on_click=lambda: ui.notify('点击了!'),    props='''        outline        rounded        size=lg        glossy        :loading="isLoading"        :disable="!isValid"        @mouseenter="handleMouseEnter"        @mouseleave="handleMouseLeave"        class="q-mt-lg shadow-3"        style="min-width: 150px; transition: all 0.3s;"    ''',    classes='hover:scale-105 active:scale-95')# 动态绑定示例ui.button('动态按钮',    props=':color="buttonColor" :label="buttonText"')

表单组合示例

from nicegui import uiwith ui.card().props('flat bordered').classes('q-pa-lg max-w-md'):    ui.label('用户注册').props('class="text-h5 q-mb-lg"')# 输入框组    ui.input(        label='用户名',        placeholder='请输入用户名',        props='''            filled            clearable            :rules="[val => val.length >= 3 || '用户名至少3个字符']"            lazy-rules        ''',        classes='q-mb-md'    )    ui.input(        label='邮箱',        placeholder='user@example.com',        props='''            filled            type=email            suffix="@example.com"            :rules="[val => /.+@.+/.test(val) || '请输入有效邮箱']"        ''',        classes='q-mb-md'    )# 选择器    ui.select(        ['北京', '上海', '广州', '深圳'],        label='城市',        props='''            filled            use-input            use-chips            multiple        ''',        classes='q-mb-md'    )# 提交按钮    ui.button('提交注册',        color='primary',        icon='send',        props='size=lg full-width',        classes='q-mt-lg'    )

提示

1. 属性类型：

• 字符串属性：label="文本"
• 数值属性：max="100"
• 布尔属性：只需写属性名，如 disabled（而不是 disabled="true"）
• 动态属性：使用 : 前缀，如 :value="varName"

2. 属性优先级：

   # NiceGUI 参数 > Quasar props > 默认值ui.button('测试', color='red', props='color=blue')  # 最终为红色

3. 事件处理：

• 使用 @ 前缀绑定事件：@click="handler"
• NiceGUI 也支持 on_ 前缀的参数：on_click=handler

4. 兼容性：

• NiceGUI 封装了大部分常用 Quasar 属性
• 但所有 Quasar 属性理论上都可以通过 props 传递
• 建议优先使用 NiceGUI 封装的参数，复杂需求再用 props

本清单涵盖了 NiceGUI 中可用的主要 Quasar 属性。实际使用时，具体属性可能根据组件版本略有差异，建议参考 Quasar 官方文档 获取最新信息。