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

NinePatchRect

节点继承关系

继承链：Node → CanvasItem → Control → NinePatchRect

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()	获取父节点

定义

九宫格拉伸是一种神奇的图片缩放方式：把一张图片切成 9 块（像九宫格），四角保持原样不动，四条边只在一个方向拉伸，中间部分自由拉伸。这样做的好处是：不管你怎么放大缩小，圆角不会变形、边框不会模糊。这就像一个有弹性的相框——框本身不变粗变细，只有中间的"画面"在变大变小。

使用频率：★★★★ 常用（做 UI 背景面板时常用）

节点用途

• 制作可缩放的圆角面板背景
• 做不变形的边框
• 制作可变大小的 UI 装饰框

使用场景

• 对话框的背景面板
• 物品栏的格子边框
• 任何需要缩放但不变形的 UI 元素

常用节点搭配

• 搭配 CenterContainer 做居中内容
• 搭配 MarginContainer 加内边距

生效必备素材/资源

• 必需：一张准备好的九宫格图片（PNG，带透明区域的边框/面板图片）

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
texture	Texture2D	null	—	原始图片
patch_margin_left	int	0	—	左侧切割线位置（像素）
patch_margin_right	int	0	—	右侧切割线位置（像素）
patch_margin_top	int	0	—	顶部切割线位置（像素）
patch_margin_bottom	int	0	—	底部切割线位置（像素）
axis_stretch_horizontal	枚举	Stretch	—	水平方向拉伸模式
axis_stretch_vertical	枚举	Stretch	—	垂直方向拉伸模式

信号

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

常用方法

方法	说明
SetTexture(Texture2D)	设置图片
SetPatchMargin(Margin, int)	设置某条边的切割位置

代码示例

C

using Godot;

public partial class NinePatchDemo : Control
{
    public override void _Ready()
    {
        var ninePatch = new NinePatchRect();
        ninePatch.Texture = GD.Load<Texture2D>("res://assets/ui/panel_bg.png");
        // 设置九宫格的切割边距（四条切线的位置）
        ninePatch.PatchMarginLeft = 10;
        ninePatch.PatchMarginRight = 10;
        ninePatch.PatchMarginTop = 10;
        ninePatch.PatchMarginBottom = 10;
        ninePatch.Position = new Vector2(50, 50);
        ninePatch.Size = new Vector2(400, 300);

        AddChild(ninePatch);
    }
}

GDScript

extends Control

func _ready():
    var nine_patch = NinePatchRect.new()
    nine_patch.texture = load("res://assets/ui/panel_bg.png")
    # 设置九宫格的切割边距（四条切线的位置）
    nine_patch.patch_margin_left = 10
    nine_patch.patch_margin_right = 10
    nine_patch.patch_margin_top = 10
    nine_patch.patch_margin_bottom = 10
    nine_patch.position = Vector2(50, 50)
    nine_patch.size = Vector2(400, 300)

    add_child(nine_patch)