lyzqt

一个基于 PySide6 的轻量级 Qt 组件库，提供 140+ 常用 UI 组件，内置语义化主题系统。

• 完整组件集：覆盖按钮、输入、对话框、反馈、布局、覆盖层、数据展示等 7 大类
• 6 套预设主题 + 跟随系统调色板自动生成主题，改动强调色/尺寸即全局生效
• 语义化设计令牌：所有组件只读 Theme.*，不写死色值，天然支持换肤

功能特性

按钮类

• Button 按钮：主要、次要、轮廓、文字、链接、危险、成功等多种样式
• IconButton 图标按钮：带图标的按钮，支持圆形、扁平样式
• ToggleButton 切换按钮：支持选中/未选中两种状态
• ButtonGroup 按钮组：支持单选和多选模式的按钮组合
• ButtonBar 工具栏：按钮条容器，支持分组与对齐
• DropdownButton 下拉按钮：主按钮 + 箭头组合，支持 click/hover 触发
• FloatButton 悬浮按钮：右下角悬浮操作按钮 / 按钮组

输入类

• Input / TextArea 输入框：单行/多行，支持前后缀、清除按钮、字数统计
• PasswordInput 密码输入框：内置明文/密文切换按钮
• OTPInput 验证码输入框：分段验证码录入，支持自动跳格与粘贴
• SpinBox 数字输入框：带步进按钮的数值录入
• Slider 滑块 / RangeSlider 双滑块：单值与区间数值选择
• Switch 开关：带动画效果的开关按钮，支持自定义颜色和大小
• Rating 评分：星级评分，支持半星、只读模式、自定义颜色
• Checkbox 复选框 / Radio 单选框 / RadioGroup 单选组
• Select 下拉选择 / AutoComplete 自动完成 / Cascader 级联选择 / TreeSelect 树形选择
• Segmented 分段控制器 / Transfer 穿梭框 / Mentions 提及
• DatePicker / TimePicker / DateTimePicker / RangePicker / Calendar：完整的日期时间录入族
• ColorPicker 颜色选择器 / ColorField 颜色选择输入框
• SearchBar 搜索框：带搜索图标和清除按钮
• Form / FormItem 表单：字段容器 + 校验规则 + 提交
• Upload / CardUpload 文件上传：拖拽上传、文件列表、进度显示

对话框类

• Toast 提示弹窗：轻量级提示消息，支持多种样式和位置，自动消失
• MessageBox 消息对话框：自定义消息对话框，支持多种类型和按钮
• InputDialog 输入对话框：支持文本、数字、小数、下拉选择、多行文本输入
• FileDialog 文件选择对话框：支持选择文件、多文件、文件夹、保存文件
• Modal 模态框 / Drawer 抽屉 / Popover 气泡卡片 / Popconfirm 气泡确认框

反馈类

• Loading 加载动画：支持旋转圆环、跳动圆点、进度条三种动画样式
• Spin / SpinContainer 加载中：局部加载态，可包裹任意组件并覆盖蒙层
• ProgressBar 进度条对话框：支持确定/不确定进度，多种颜色样式，可取消
• Alert 警告提示：静态提示条，支持四种语义色与可关闭
• Badge 徽章组件：支持数字、小红点、文字三种类型，可附加到任意控件上
• Notification 通知卡片：右上角堆叠通知，支持多种类型，自动消失
• Skeleton 骨架屏：单块/分组骨架，支持常用形态预设
• Result 结果页 / Empty 空状态

布局类

• Layout / Header / Footer / Content / Sider：经典后台布局容器
• Grid / Row / Col / SimpleGrid 栅格布局
• Flex 弹性布局：CSS Flexbox 语义的布局容器，支持方向、对齐、间距与子项占比
• Space / FlowLayout 间距与流式布局：自动换行的流式排列
• SplitPanel 分割面板：可拖拽的水平/垂直分割
• Tabs 标签页 / Collapse 折叠面板 / Sidebar 侧边栏 / Menu 菜单 / Dropdown 下拉菜单
• Affix 固钉 / Anchor 锚点导航 / PageHeader 页头 / Breadcrumb 面包屑 / Pagination 分页
• Divider / HLine / VLine 分割线

数据展示类

• Table 数据表格：列定义、排序、选择、分页配合
• Tree 树形控件：展开/折叠/选中，支持勾选
• List 列表 / Comment 评论 / Descriptions 描述列表
• Steps 步骤条 / Timeline 时间线 / Statistic 统计数值 / CountDown 倒计时
• Card 卡片 / CheckCard 可选卡片 / Tag 标签 / Avatar 头像 / AvatarGroup 头像组
• Carousel 轮播图 / Image 图片 / ImagePreview 图片预览
• ImageCompare / ImageCompareDual / ImageCompareView 图像对比
• QRCode 二维码 / Watermark 水印 / Tooltip 工具提示 / Icon 图标
• Typography 排版：Title / Text / Link / Paragraph / TextLabel
• Tour 漫游引导 / BackTop 回到顶部 / ContextMenu 右键菜单

主题系统

• 6 套预设主题：aether_dark、aether_light、night_sky_blue、seafoam、parchment、graphite_gold
• 跟随系统：ConfigProvider.set_theme_from_system() 按系统调色板自动生成主题，深浅模式切换时自动刷新（Qt 6.5+）
• 强调色定制：set_accent_color() 自动派生悬停色、激活色、浅色底、聚焦边框与发光阴影，无需手写每个衍生色
• 全局尺寸：set_size("small"|"medium"|"large") 联动间距、圆角与字号三组令牌
• 主题感知：继承 ThemeAwareMixin 的自定义组件会在主题变更时自动刷新

环境要求

• Python 3.9+
• PySide6 6.x（推荐 6.5+ 以启用跟随系统深浅模式自动刷新）

安装

pip install lyzqt

开发安装

pip install -e . --force-reinstall --no-deps

表示重新安装了最新版的 lyzqt（纯 Python 可编辑安装，改动源码即时生效）。

若要编译发布版本（Cython 混淆，生成 .so 加速/保护源码），使用：

LYZQT_BUILD_CYTHON=1 python setup.py build_ext --inplace

快速开始

from PySide6.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget
from lyzqt import Toast, Button, ConfigProvider
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("lyzqt 示例")
        self.resize(400, 300)

        central = QWidget()
        layout = QVBoxLayout(central)
        btn = Button.primary("点击我")
        btn.clicked.connect(lambda: Toast("Hello lyzqt!", parent=self))
        layout.addWidget(btn)
        self.setCentralWidget(central)

if __name__ == "__main__":
    app = QApplication(sys.argv)

    # 切换到亮色主题（不调用则按系统调色板自动生成）
    ConfigProvider.set_theme(ConfigProvider.THEME_AETHER_LIGHT)

    window = MainWindow()
    window.show()
    sys.exit(app.exec())

主题与尺寸

from lyzqt import ConfigProvider

# 切换预设主题
ConfigProvider.set_theme("night_sky_blue")

# 自定义强调色（悬停/激活/浅色/发光色自动派生）
ConfigProvider.set_accent_color("#EC4899")

# 全局尺寸（联动间距、圆角、字号）
ConfigProvider.set_size("large")

# 跟随系统深浅模式
ConfigProvider.set_theme_from_system(app, follow_system=True)

自定义组件接入主题：

from lyzqt import ThemeAwareMixin, Theme
from PySide6.QtWidgets import QWidget

class MyCard(ThemeAwareMixin, QWidget):   # 混类必须放在 Qt 基类之前
    def __init__(self, parent=None):
        super().__init__(parent)
        self._register_theme_aware()      # 注册后主题变更会自动回调
        self._apply_style()

    def _apply_style(self):
        self.setStyleSheet(f"""
            MyCard {{
                background: {Theme.BG_SURFACE};
                color: {Theme.TEXT_PRIMARY};
                border: 1px solid {Theme.BORDER};
                border-radius: {Theme.RADIUS_MEDIUM};
            }}
        """)

完整设计令牌清单、各组件 API 与更多示例见 在线文档。

组件说明

下面列出最常用组件的核心 API。全部 140+ 组件的完整参数、信号与示例请查阅 docs/components/ 下的分册文档。

Toast

• message (str)：提示消息内容
• duration (int)：显示时长，单位毫秒，默认 2000ms
• position (int)：显示位置
  • Toast.POS_TOP：顶部
  • Toast.POS_CENTER：居中（默认）
  • Toast.POS_BOTTOM：底部
• style (str)：样式
  • Toast.STYLE_DEFAULT：默认样式
  • Toast.STYLE_SUCCESS：成功样式（绿色）
  • Toast.STYLE_INFO：信息样式（蓝色）
  • Toast.STYLE_WARNING：警告样式（橙色）
  • Toast.STYLE_ERROR：错误样式（红色）
• parent：父窗口
• icon：自定义图标（可选）

MessageBox

• TYPE_INFO / TYPE_SUCCESS / TYPE_WARNING / TYPE_ERROR / TYPE_QUESTION：消息类型
• BTN_OK / BTN_CANCEL / BTN_YES / BTN_NO / BTN_ABORT / BTN_RETRY / BTN_IGNORE：按钮类型
• 快捷方法：info(), success(), warning(), error(), question()

InputDialog

• TYPE_TEXT / TYPE_NUMBER / TYPE_FLOAT / TYPE_COMBO / TYPE_TEXTAREA：输入类型
• 快捷方法：get_text(), get_number(), get_float(), get_item(), get_textarea()

FileDialog

• MODE_OPEN_FILE / MODE_OPEN_FILES / MODE_OPEN_DIR / MODE_SAVE_FILE：选择模式
• 快捷方法：get_open_file(), get_open_files(), get_open_dir(), get_save_file()

ColorPicker

• get_color()：返回 QColor 对象
• get_hex()：返回 HEX 格式字符串
• get_rgb()：返回 RGB 元组

Loading

• STYLE_SPINNER / STYLE_DOTS / STYLE_BAR：动画样式
• 快捷方法：show_spinner(), show_dots(), show_bar()
• set_message()：更新加载文字
• close()：关闭加载框

ProgressBar

• STYLE_DEFAULT / STYLE_SUCCESS / STYLE_INFO / STYLE_WARNING / STYLE_ERROR：颜色样式
• create()：创建确定进度对话框
• create_indeterminate()：创建不确定进度对话框
• set_value()：设置进度值
• set_message()：更新消息文字
• is_cancelled()：检查是否已取消
• cancellable：是否显示取消按钮

Badge

• TYPE_DOT / TYPE_NUMBER / TYPE_TEXT：徽章类型
• POS_TOP_RIGHT / POS_TOP_LEFT / POS_BOTTOM_RIGHT / POS_BOTTOM_LEFT：位置
• COLOR_RED / COLOR_ORANGE / COLOR_GREEN / COLOR_BLUE / COLOR_GRAY：颜色预设
• set_value()：设置数字
• show_dot() / show_number() / show_text()：切换显示类型
• hide_badge()：隐藏徽章

Switch

• size：大小，可选 "small" / "medium" / "large"
• on_color / off_color：开启/关闭时的颜色
• toggled 信号：状态改变时触发
• isChecked() / setChecked()：获取/设置状态

Rating

• value：当前评分值
• max_value：最大评分值
• size：星星大小
• readonly：是否只读
• color / inactive_color：激活/未激活颜色
• allow_half：是否允许半星
• value_changed 信号：评分改变时触发

SearchBar

• placeholder：占位文字
• width：宽度
• clearable：是否显示清除按钮
• search 信号：回车搜索时触发
• text_changed 信号：文字变化时触发
• cleared 信号：清除时触发

Avatar

• SHAPE_CIRCLE / SHAPE_SQUARE：形状
• SIZE_SMALL / SIZE_MEDIUM / SIZE_LARGE：大小预设
• text：文字头像内容
• image：图片路径
• bg_color / text_color：背景/文字颜色

Tooltip

• POS_TOP / POS_BOTTOM / POS_LEFT / POS_RIGHT：位置
• STYLE_DARK / STYLE_LIGHT / STYLE_SUCCESS / STYLE_WARNING / STYLE_ERROR：样式
• show_tooltip()：显示提示
• hide_tooltip()：隐藏提示

Notification

• TYPE_INFO / TYPE_SUCCESS / TYPE_WARNING / TYPE_ERROR：类型
• info() / success() / warning() / error()：快捷方法
• duration：显示时长（毫秒）
• closable：是否可关闭

Button

• STYLE_PRIMARY / STYLE_SECONDARY / STYLE_OUTLINE / STYLE_TEXT / STYLE_LINK / STYLE_DANGER / STYLE_SUCCESS / STYLE_WARNING：样式
• SIZE_SMALL / SIZE_MEDIUM / SIZE_LARGE：大小
• primary() / secondary() / outline() / danger() / success() / warning()：快捷方法
• set_style() / set_size() / set_block()：设置样式/大小/块级

IconButton

• ICON_LEFT / ICON_RIGHT / ICON_TOP：图标位置
• SIZE_SMALL / SIZE_MEDIUM / SIZE_LARGE：大小
• circular()：创建圆形图标按钮
• from_theme()：从系统主题创建
• set_icon_from_theme()：设置系统主题图标

ToggleButton

• SIZE_SMALL / SIZE_MEDIUM / SIZE_LARGE：大小
• primary() / success() / danger() / warning()：快捷方法
• set_color()：设置选中颜色
• toggled 信号：状态切换时触发

ButtonGroup

• SIZE_SMALL / SIZE_MEDIUM / SIZE_LARGE：大小
• single_select() / multi_select()：创建单选/多选按钮组
• set_selected() / set_selected_multi()：设置选中项
• get_selected() / get_selected_multi() / get_selected_text()：获取选中项
• set_color()：设置选中颜色
• selection_changed / selections_changed 信号：选择变化时触发