PySide6 GUI 学习笔记——常用类及控件使用方法（常用类矩阵QRect）

📘 PySide6.QtCore.QRect 使用整数精度定义平面矩形区域，其官方文档参考这里。

---

一、构造与初始化方法

方法签名	说明
QRect()	构造空矩形（宽高为0）
QRect(x: int, y: int, width: int, height: int)	通过坐标和尺寸构造
QRect(topLeft: QPoint, size: QSize)	通过顶点和尺寸构造
QRect(topLeft: QPoint, bottomRight: QPoint)	通过对角点构造（不推荐）

# 空矩形
null_rect = QRect()# 标准构造
rect1 = QRect(10, 20, 300, 400)# QPoint+QSize构造
rect2 = QRect(QPoint(10, 20), QSize(300, 400))

---

二、坐标与尺寸获取

方法	返回值	说明
left()	int	左边界x坐标
top()	int	上边界y坐标
right()	int	右边界x坐标（含历史原因带来的偏移： left() + width() - 1）
bottom()	int	下边界y坐标（含历史偏移：top() + height() - 1）
width()	int	实际宽度（可能负数）
height()	int	实际高度（可能负数）
topLeft()	QPoint	左上角坐标
bottomRight()	QPoint	右下角坐标（含偏移）
center()	QPoint	中心点坐标
size()	QSize	尺寸对象

rect = QRect(10, 20, 30, 40)
print(rect.right())   # 39 (10+30-1)
print(rect.size())    # QSize(30, 40)
print(rect.top())     # 20
print(rect.width())     # 30
print(rect.height())    # 40
print(rect.x())         # 10
print(rect.y())         # 20
print(rect.bottom())    # 59 (20+40-1)
print(rect.left())      # 10，和x()一样

---

三、坐标与尺寸设置

方法	参数	说明
setLeft(x: int)	新左边界	保持右边界不变
setRight(x: int)	新右边界	改变宽度
setTop(y: int)	新上边界	保持下边界不变
setBottom(y: int)	新下边界	改变高度
setTopLeft(p: QPoint)	新顶点	改变位置，保持右下
setBottomRight(p: QPoint)	新对角点	改变尺寸
setWidth(w: int)	新宽度	右边界自动计算
setHeight(h: int)	新高度	下边界自动计算
setSize(s: QSize)	新尺寸	保持左上角不变
setCoords(x1: int, y1: int, x2: int, y2: int)	四坐标	直接设置四个边界
setRect(x: int, y: int, w: int, h: int)	坐标+尺寸	重置整个矩形

rect = QRect(10, 20, 30, 40)
rect.setRight(50)      # 新宽度=50-10+1=41
rect.setSize(QSize(20, 60))  # 变为(10,20,20,60)

---

四、几何运算方法

方法	返回值	说明
contains(QPoint)	bool	点是否在矩形内
contains(QRect)	bool	是否完全包含另一矩形
intersects(QRect)	bool	是否有重叠区域
intersected(QRect)	QRect	返回交集区域
united(QRect)	QRect	返回并集区域
adjusted(dx1: int, dy1: int, dx2: int, dy2: int)	QRect	调整边界后的新矩形
normalized()	QRect	标准化后的正尺寸矩形

rect_a = QRect(0, 0, 100, 100)
rect_b = QRect(50, 50, 100, 100)print(rect_a.intersected(rect_b))  # QRect(50,50,50,50)
print(rect_a.contains(QPoint(30,30)))  # True

---

五、移动与调整方法

方法	参数	说明
translate(dx: int, dy: int)	偏移量	相对移动
translated(dx: int, dy: int)	偏移量	返回移动后的新矩形
moveTo(x: int, y: int)	新坐标	绝对移动左上角
moveTopLeft(p: QPoint)	新顶点	移动左上角
adjust(dx1: int, dy1: int, dx2: int, dy2: int)	调整量	直接修改边界
marginsAdded(QMargins)	边距	增加外边距后的新矩形
marginsRemoved(QMargins)	边距	移除外边距后的新矩形

rect = QRect(10, 20, 30, 40)
rect.translate(5, -5)  # 新位置(15,15,30,40)
new_rect = rect.translated(0, 10)  # (15,25,30,40)
new_rect.moveTo(0, 0)   # (0,0,30,40)

---

六、状态判断方法

方法	返回值	说明
isEmpty()	bool	是否面积为零（允许负尺寸）
isNull()	bool	是否宽高均为0
isValid()	bool	是否满足 left<=right 且 top<=bottom

rect1 = QRect(10,10,-5,20)
print(rect1.isEmpty())  # True (宽度为负)
print(rect1.isValid())   # Falserect2 = QRect()
print(rect2.isNull())    # True

---

七、类型转换方法

方法	返回值	说明
toRectF()	QRectF	转为浮点矩形
getCoords()	(x1, y1, x2, y2)	获取四个边界坐标
getRect()	(x, y, w, h)	获取左上坐标和尺寸

rect = QRect(10, 20, 30, 40)
print(rect.getCoords())  # (10, 20, 39, 59)
print(rect.toRectF())    # QRectF(10.0,20.0,30.0,40.0)

---

八、操作符重载

操作符	等效方法	说明
&	intersected()	交集运算
|	united()	并集运算
+=	marginsAdded()	增加边距
-=	marginsRemoved()	移除边距
==	坐标相等判断	完全一致
-	差集运算	返回缩小后的矩形

rect1 = QRect(0,0,100,100)
rect2 = QRect(50,50,100,100)
print(rect1 & rect2)  # QRect(50,50,50,50)
print(rect1 | rect2)  # QRect(0,0,150,150)

---

九、静态方法

方法	说明
span(p1: QPoint, p2: QPoint)	创建包含两点的最小矩形

p1 = QPoint(10, 20)
p2 = QPoint(50, 60)
span_rect = QRect.span(p1, p2)  # QRect(10,20,41,41)

---

十、特殊方法

方法	说明
__reduce__()	序列化支持
__repr__()	字符串表示
transposed()	宽高交换后的新矩形

rect = QRect(10, 20, 30, 40)
print(rect.transposed())  # QRect(10,20,40,30)

---

附录

方法速查表

类别	方法
构造	QRect(), QRect(x,y,w,h), QRect(QPoint,QSize)
坐标获取	left(), right(), top(), bottom(), topLeft(), bottomRight(), center()
尺寸获取	width(), height(), size()
坐标设置	setLeft(), setRight(), setTop(), setBottom(), setTopLeft(), setBottomRight()
尺寸设置	setWidth(), setHeight(), setSize(), setCoords(), setRect()
几何运算	contains(), intersects(), intersected(), united(), adjusted(), normalized()
移动调整	translate(), translated(), moveTo(), adjust(), marginsAdded(), marginsRemoved()
状态判断	isEmpty(), isNull(), isValid()
类型转换	toRectF(), getCoords(), getRect()
操作符	&, |, +=, -=, ==, -
特殊方法	transposed(), span()

---

注意的问题

实际开发中需特别注意：

1. 历史坐标偏移问题（right/bottom返回值）
2. 负尺寸需用normalized()标准化
3. 移动与调整方法的原地修改与返回新对象的区别
4. 有效性验证应在几何运算前完成

交集和并集图解

• intersect
  
• united