Metadata-Version: 2.1
Name: lyzqt
Version: 0.1.0
Summary: 一个基于PySide6的轻量级Qt组件库
Home-page: https://github.com/zhenzi0322-package/lyzqt
Author: zhenzi0322
Author-email: zhenzi0322 <82131529@qq.com>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 # 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+ 以启用跟随系统深浅模式自动刷新）
 
 ## 安装
 
 ```bash
 pip install lyzqt
 ```
 
 ## 开发安装
 
 ```bash
 pip install -e . --force-reinstall --no-deps
 ```
 
 表示重新安装了最新版的 `lyzqt`（纯 Python 可编辑安装，改动源码即时生效）。
 
 > 若要编译发布版本（Cython 混淆，生成 `.so` 加速/保护源码），使用：
 > ```bash
 > LYZQT_BUILD_CYTHON=1 python setup.py build_ext --inplace
 > ```
 
 ## 快速开始
 
 ```python
 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())
 ```
 
 ## 主题与尺寸
 
 ```python
 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)
 ```
 
 自定义组件接入主题：
 
 ```python
 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 与更多示例见 [在线文档](https://your-docs-site)。
 
 ## 组件说明
 
 > 下面列出最常用组件的核心 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` 信号：选择变化时触发
 
 
 
Requires-Dist: pyside6
