Alpha v1.0.0

InstructionX_UIKit alpha-v1.0.0

首个公开测试版本。InstructionX_UIKit 是一个基于 PySide6（Qt for Python）的纯桌面 UI 组件库：设计令牌 + 亮/暗双主题、57 个组件、12 个响应式布局预设、52 个动画预设、原生图表引擎与蓝图节点图编辑器。

本版本为 Alpha 阶段：API 整体趋于稳定，但细节仍可能调整；暗色主题为实验性功能，个别组件在暗色下的细节表现仍在打磨。

亮点

• 设计令牌 + 双主题：色彩 / 字体 / 间距 / 圆角 / 阴影 / 断点 / 动效全部令牌化，ThemeManager 一键切换亮 / 暗主题，无需重启，全部组件实时热切换。
• 57 个组件：输入 / 展示 / 反馈三大类，动态属性 + 全局 QSS 驱动，统一 sm / md / lg 尺寸体系与完整状态矩阵（hover / pressed / disabled / focus）。
• 12 个响应式布局预设：API 驱动工厂函数，基于断点的响应式重排，空数据自动显示优雅占位。
• 52 个动画预设：28 个属性动画（快照覆盖层方案，规避 Qt6 + QSS + 高 DPI 下 QGraphicsEffect 失效问题）+ 24 个 QTimer 自绘动画组件。
• 原生图表引擎：纯 QPainter 实现的 ECharts 风格图表，不依赖 WebView / JavaScript；set_option 数据驱动，20+ 系列类型，主题感知实时换肤。
• 蓝图节点图：类 UE5 Blueprint / ComfyUI 的节点图编辑器，支持右键建节点、引脚拖线、类型校验、JSON 序列化与执行状态模拟。
• 职责分离：Kit 包零假数据、零 Demo 逻辑，一切内容由调用方 API 传入；独立 Demo 程序内置 74+ 演示页，每页顶部附「用法」代码示例。

安装

pip install -r requirements.txt

依赖：PySide6>=6.6（含 Addons）与 qrcode[pil]>=7.4，除此之外无任何第三方依赖。要求 Python 3.14+。

快速开始

import sys
from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget

from InstructionX_UIKit.theme import ThemeManager
from InstructionX_UIKit.components import Button, LineEdit, Statistic

app = QApplication(sys.argv)
ThemeManager.instance().apply(app)   # 应用全局主题（默认亮色）

win = QWidget()
lay = QVBoxLayout(win)
lay.addWidget(Statistic(title="活跃用户", value=24317))
lay.addWidget(LineEdit(placeholder="请输入关键词"))
lay.addWidget(Button("确定", variant="primary"))
win.resize(720, 560)
win.show()
sys.exit(app.exec())

运行完整 Demo（74+ 演示页，含 Playground 调参与「用法」示例）：

python main.py

文档

• README — 项目总览与快速上手
• docs/USAGE.md — 使用手册（主题系统、全部组件 / 布局 / 动画 / 图表 / 蓝图示例）
• docs/Design.md — 设计规范（令牌数值、断点、动效、状态矩阵）

说明

• 暗色主题为实验性功能：亮 / 暗切换机制与令牌体系已完整，个别组件在暗色下的细节表现仍在打磨，欢迎反馈。
• 测试代码在 test 分支：main / dev 仅含源码与文档；全部离屏自测（含截图回归）随完整源码维护在 test 分支。
• Alpha 阶段如遇到 API 调整，会在后续 Release 中明确列出变更点。