# 方圆GUI库 v1.1.0 教程

一个旨在简化 PySide6 桌面应用程序开发的 Python 库，使用更自然的中文函数名和增强的视觉效果。

## 📁 项目结构

```
方圆/
├── __init__.py              # 主入口文件
├── 核心.py                  # 基础GUI功能和工具函数
├── 样式/                    # 主题系统和视觉样式
│   ├── __init__.py
│   └── 主题.py
├── 组件/                    # 高级UI组件和控件
│   ├── __init__.py
│   ├── 高级按钮.py
│   └── 卡片.py
├── 语法/                    # 多种编程语法风格
│   ├── __init__.py
│   ├── 传统.py
│   ├── 上下文.py
│   ├── 链式.py
│   └── 装饰器.py
├── 示例/                    # 使用示例
│   ├── 基础示例.py
│   ├── 多语法演示.py
│   ├── 主题演示.py
│   └── 组件演示.py
└── 测试/                    # 测试文件
    ├── 兼容性测试.py
    └── 功能测试.py
```

## 🚀 安装和使用

### 方式一：直接使用（最简单，推荐）
```bash
# 1. 将下载的「方圆」文件夹直接拖到您的项目文件夹中
# 2. 然后在代码中使用：
#    from 方圆 import *
```

### 方式二：
```bash
首先把方圆文件夹放到你的项目文件夹里

首先使用这行指令获得你的Python路径
python -c "import site; print(site.getsitepackages())"
或者
python -c "import sys; print([p for p in sys.path if 'site-packages' in p])"

您应该会看到类似这样的路径
['/Users/yourname/.venv/lib/python3.12/site-packages']

然后使用这行安装
cp -r 方圆 刚刚的文件路径

# 然后在代码中使用：
# from 方圆 import *
```

## 🎯 快速开始

### 最简单的使用方式
```python
# hello_world.py
from 方圆 import *

def 创建界面():
    窗口 = 创建窗口("我的第一个应用", 400, 300)
    中央区域, 布局 = 设置布局(窗口)
    添加标签(布局, "你好，世界！")
    return 窗口

运行应用(创建界面)
```

### 传统语法（兼容v1.0.0）
```python
# 传统语法示例.py
from 方圆 import *

def 创建传统界面():
    窗口 = 创建主窗口("传统语法示例", 600, 400)
    中央区域, 布局 = 为窗口设置中央区域和布局(窗口, "垂直", 20, 15)
    
    添加标签到布局(布局, "传统语法演示", "居中")
    添加按钮到布局(布局, "点击我", lambda: 显示信息(窗口, "提示", "传统语法工作正常"))
    
    return 窗口

运行应用(创建传统界面)
```

## 🌈 多语法演示

### 上下文语法
```python
# 上下文语法示例.py
from 方圆 import *
使用语法("上下文")

def 创建界面():
    窗口, 界面 = 创建窗口("上下文语法示例")
    
    with 界面:
        界面.标签("上下文语法演示", 字体大小="20px")
        
        with 界面.水平布局():
            界面.输入框("请输入内容")
            界面.按钮("提交", lambda: print("提交点击"))
        
        with 界面.阴影框(背景颜色="#FFFFFF"):
            界面.标签("卡片内容")
    
    return 窗口

运行应用(创建界面)
```

### 链式语法
```python
# 链式语法示例.py
from 方圆 import *
使用语法("链式")

界面 = (创建界面("链式语法示例", 500, 400)
    .标签("链式语法演示")
    .垂直()
        .按钮("确定")
        .按钮("取消")
    .结束()
    .显示())
```

### 装饰器语法
```python
# 装饰器语法示例.py
from 方圆 import *
使用语法("装饰器")

界面 = 创建装饰界面("装饰器语法示例")

@布局块(界面.获取上下文())
def 创建内容():
    界面.标签("装饰器语法演示")
    界面.按钮("测试按钮")

运行应用(界面.获取窗口)
```

## 🎨 主题和样式演示

```python
# 主题演示.py
from 方圆 import *

def 创建主题界面():
    窗口 = 创建窗口("主题演示", 700, 500)
    
    # 应用主题
    应用主题(窗口, "material")
    
    中央区域, 布局 = 设置布局(窗口, 内边距=25, 间距=20)
    
    # 使用预设样式
    添加标签(布局, "🎨 主题系统演示", "居中")
    控件样式(添加标签(布局, "🎨 主题系统演示", "居中"), 
              {"字体大小": "28px", "字体粗细": "bold"})
    
    # 创建卡片
    卡片, 卡片布局 = 添加带阴影的框架到布局(布局, 背景颜色="#FFFFFF", 圆角=16)
    添加标签(卡片布局, "Material Design 主题", "居中")
    
    # 使用主题颜色
    主题 = 获取主题("material")
    print(f"主题主色: {主题['primary']}")
    
    return 窗口

运行应用(创建主题界面)
```

## 🧩 组件演示

```python
# 组件演示.py
from 方圆 import *

def 创建组件界面():
    窗口 = 创建窗口("组件演示", 600, 500)
    
    中央区域, 布局 = 设置布局(窗口)
    
    # 使用高级按钮
    添加标签(布局, "🛠️ 高级组件演示", "居中")
    
    按钮1 = 创建按钮("主要按钮", 样式="primary", 
                   点击时执行=lambda: 信息框(窗口, "提示", "主要按钮点击"))
    
    按钮2 = 创建按钮("次要按钮", 样式="secondary")
    
    布局.addWidget(按钮1)
    布局.addWidget(按钮2)
    
    # 使用卡片组件
    卡片 = 创建卡片("信息卡片", "light")
    卡片.添加控件(添加标签(卡片布局, "卡片内容"))
    布局.addWidget(卡片)
    
    return 窗口

运行应用(创建组件界面)
```

## ✅ 兼容性测试

```python
# 测试/兼容性测试.py
from 方圆 import *

def 测试v1_0_0兼容性():
    """验证v1.0.0所有功能在v1.1.0中正常工作"""
    窗口 = 创建主窗口("兼容性测试", 500, 400)
    中央区域, 布局 = 为窗口设置中央区域和布局(窗口)
    
    # 测试所有v1.0.0功能
    添加标签到布局(布局, "v1.0.0兼容性测试通过", "居中")
    添加按钮到布局(布局, "测试按钮", lambda: 显示信息(窗口, "成功", "兼容性验证通过"))
    
    return 窗口

运行应用(测试v1_0_0兼容性)
```

## 🧪 功能测试

```python
# 测试/功能测试.py
from 方圆 import *

def 测试新功能():
    """测试v1.1.0新功能"""
    窗口 = 创建窗口("新功能测试", 600, 500)
    中央区域, 布局 = 设置布局(窗口)
    
    # 测试自动Qt导入
    添加标签(布局, "✅ 自动Qt导入测试", "居中")
    列表 = 添加列表(布局)
    项目 = 向列表添加可勾选项目(列表, "测试项目", 已完成=False)
    
    # 应该可以直接使用Qt常量
    if 项目.checkState() == Qt.Unchecked:
        添加标签(布局, "✅ Qt常量自动导入成功")
    
    # 测试便捷常量
    添加标签(布局, "测试对齐", 对齐方式["居中"])
    添加标签(布局, "✅ 便捷常量测试通过")
    
    return 窗口

运行应用(测试新功能)
```

## 📖 核心概念（更新）

### 自动导入系统
v1.1.0 自动导入常用 Qt 模块，无需手动导入：
```python
# 不需要这些导入了：
# from PySide6.QtCore import Qt
# from PySide6.QtWidgets import QWidget, QHBoxLayout, QVBoxLayout

# 可以直接使用：
项目.checkState() == Qt.Checked  # ✅ 自动可用
布局 = QVBoxLayout()            # ✅ 自动可用
```

### 便捷常量
```python
# 使用对齐方式字典
添加标签(布局, "文本", 对齐方式["居中"])

# 使用勾选状态常量  
向列表添加可勾选项目(列表, "任务", 勾选状态["已勾选"])
```

## 🚀 部署说明

### 对于新用户
1. 下载整个 `方圆` 文件夹
2. 放在项目目录中或 Python 路径下
3. 使用 `from 方圆 import *` 导入

### 对于v1.0.0用户升级
1. **无需任何代码修改**
2. 所有现有代码继续正常工作
3. 可以按需使用新功能

### 验证安装
```python
# 验证安装.py
from 方圆 import *

print(f"方圆库版本: v{__version__}")
print(f"当前语法: {获取当前语法()}")
print("✅ 安装成功！")
```

## 🆕 v1.1.0 新特性总结

- **多语法支持**: 4种编程风格满足不同偏好
- **主题系统**: 现代化主题和预设样式
- **高级组件**: 可扩展的组件架构
- **自动导入**: 无需手动导入Qt模块
- **模块化设计**: 更好的代码组织
- **完全兼容**: 所有v1.0.0代码无需修改

## 💡 最佳实践

1. **选择适合的语法**: 根据项目复杂度选择语法风格
2. **使用主题系统**: 保持UI风格一致性
3. **渐进式采用**: 可以先使用传统语法，逐步尝试新特性
4. **模块化开发**: 利用新的模块化架构组织代码

## ❓ 常见问题

**Q: 升级后现有代码需要修改吗？**
A: 不需要，v1.1.0完全兼容v1.0.0的所有代码。

**Q: 如何切换语法风格？**
A: 使用 `使用语法("风格名称")` 函数，如 `使用语法("链式")`

**Q: 新功能是必须使用的吗？**
A: 不是，新功能都是可选的，可以按需使用。

---

🎉 **开始使用方圆库v1.1.0，享受更简单、更强大的GUI开发体验！**