最后同步日期：2026-04-15 | Godot 官方原文 — TextureRect

TextureRect

节点继承关系

继承链：Node → CanvasItem → Control → TextureRect

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

TextureRect 是 UI 中显示图片的标准方式。就像一个相框——你往里面放一张照片，它就帮你展示出来。

使用频率：★★★★ 维度专用常用（几乎每个游戏都需要显示图片）

节点用途

• 显示角色头像、图标
• 显示背景图片
• 显示物品图片

使用场景

• 主菜单的背景图
• 角色选择界面的头像
• 背包系统中的物品图标
• HUD 上的技能图标

常用节点搭配

• 搭配 CenterContainer 居中显示
• 搭配 GridContainer 排列多个图标
• 搭配 NinePatchRect 做背景 + 内容布局

生效必备素材/资源

• 必需：一张图片文件（PNG、JPG、SVG 等）

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
texture	Texture2D	null	—	要显示的图片资源
stretch_mode	枚举	Keep	—	图片拉伸方式（见下表）
expand_mode	枚举	KeepSize	—	控件如何适配图片大小

stretch_mode 常用值

值	含义	什么时候用
Scale	直接拉伸填满	图片和控件比例一致时
Tile	像贴瓷砖一样重复	做背景图案
Keep	保持原图大小不缩放	精确尺寸的图标
KeepCentered	保持大小居中	居中显示小图标
KeepAspect	等比缩放，不变形	显示角色头像等
KeepAspectCentered	等比缩放并居中	最常用的方式

信号

信号	触发时机	参数
（TextureRect 没有特有信号）	—	—

常用方法

方法	说明
SetTexture(Texture2D)	设置图片
GetTexture()	获取图片

代码示例

C

using Godot;

public partial class ImageDemo : Control
{
    public override void _Ready()
    {
        var imageRect = new TextureRect();
        imageRect.Texture = GD.Load<Texture2D>("res://icon.svg");
        imageRect.StretchMode = TextureRect.StretchModeEnum.KeepAspectCentered;
        imageRect.ExpandMode = TextureRect.ExpandModeEnum.IgnoreSize;
        imageRect.Position = new Vector2(50, 50);
        imageRect.Size = new Vector2(200, 200);

        AddChild(imageRect);
    }
}

GDScript

extends Control

func _ready():
    var image_rect = TextureRect.new()
    image_rect.texture = load("res://icon.svg")
    image_rect.stretch_mode = TextureRect.StretchModeEnum.KEEP_ASPECT_CENTERED
    image_rect.expand_mode = TextureRect.ExpandModeEnum.IGNORE_SIZE
    image_rect.position = Vector2(50, 50)
    image_rect.size = Vector2(200, 200)

    add_child(image_rect)