CanvasItem

继承： Node < Object

派生： Control, Node2D

2D 空间中所有对象的抽象基类。

描述

2D 空间中所有对象的抽象基类。画布项目以树状排列；子节点继承并扩展其父节点的变换。CanvasItem 由 Control 扩展为 GUI 相关的节点，由 Node2D 扩展为 2D 游戏对象。

任何 CanvasItem 都可以进行绘图。绘图时，引擎会调用 queue_redraw，然后 NOTIFICATION_DRAW 就会在空闲时被接收到以请求重绘。因此，画布项目不需要每一帧都重绘，这显著提升了性能。这个类还提供了几个用于在 CanvasItem 上绘图的函数（见 draw_* 函数）。不过这些函数都只能在 _draw 及其对应的 Object._notification 或连接到 draw 的方法内使用。

画布项目在其画布层上是按树状顺序绘制的。默认情况下，子项目位于其父项目的上方，因此根 CanvasItem 将被画在所有项目的后面。这种行为可以针对每个画布项目进行更改。

CanvasItem 可以隐藏，隐藏时也会隐藏其子项目。通过调整 CanvasItem 的各种其它属性，你还可以调制它的颜色（通过 modulate 或 self_modulate）、更改 Z 索引、混合模式等。

请注意，变换、调制、可见性等属性只会传播至直属的 CanvasItem 子节点。如果中间有 Node、AnimationPlayer 等非 CanvasItem 节点，那么更深层 CanvasItem 的位置和 modulate 链就是独立的了。另见 top_level。

教程

• Viewport 和画布变换

• 2D 中的自定义绘图

• 音频频谱可视化演示

属性

方法

信号

draw() 🔗

当该 CanvasItem 必须重绘时发出，发生在相关的 NOTIFICATION_DRAW 通知之后，调用 _draw 之前。

注意：延迟连接无法使用 draw_* 方法进行绘制。

hidden() 🔗

当隐藏时发出。

item_rect_changed() 🔗

当 CanvasItem 的 Rect2 边界（位置或大小）发生变化时，或者当发生可能影响这些边界的操作（例如，更改 Sprite2D.texture）时发出。

visibility_changed() 🔗

当可见性（隐藏/可见）更改时发出。

枚举

enum TextureFilter: 🔗

TextureFilter TEXTURE_FILTER_PARENT_NODE = 0

该 CanvasItem 将从其父级继承过滤器。

TextureFilter TEXTURE_FILTER_NEAREST = 1

纹理过滤仅从最近的像素读取。这使得纹理从近距离看是像素化的，从远处看是颗粒状的（由于多级渐远纹理没有被采样）。

TextureFilter TEXTURE_FILTER_LINEAR = 2

纹理过滤在最近的 4 个像素之间进行混合。这使得纹理从近处看起来很平滑，从远处看起来却有颗粒感（由于多级渐远纹理没有被采样）。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤从最近的像素读取并在最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来像素化，从远处看起来平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

纹理过滤在最近的 4 个像素和最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来平滑，从远处看起来也平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤从最近的像素读取并根据表面和相机视图之间的角度在 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来像素化，从远处看起来平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量，但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：该纹理过滤在 2D 项目中很少有用。TEXTURE_FILTER_NEAREST_WITH_MIPMAPS 在这种情况下通常更合适。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

纹理过滤在最近的 4 个像素之间进行混合，并基于表面与相机视图之间的角度在 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来平滑，从远处看起来也平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量，但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：该纹理过滤在 2D 项目中很少有用。TEXTURE_FILTER_LINEAR_WITH_MIPMAPS 在这种情况下通常更合适。

TextureFilter TEXTURE_FILTER_MAX = 7

代表 TextureFilter 枚举的大小。

enum TextureRepeat: 🔗

TextureRepeat TEXTURE_REPEAT_PARENT_NODE = 0

该 CanvasItem 将从其父级继承过滤器。

TextureRepeat TEXTURE_REPEAT_DISABLED = 1

纹理不会重复。

TextureRepeat TEXTURE_REPEAT_ENABLED = 2

纹理将正常重复。

TextureRepeat TEXTURE_REPEAT_MIRROR = 3

纹理将以 2×2 平铺模式重复，其中偶数位置的元素会被镜像。

TextureRepeat TEXTURE_REPEAT_MAX = 4

代表 TextureRepeat 枚举的大小。

enum ClipChildrenMode: 🔗

ClipChildrenMode CLIP_CHILDREN_DISABLED = 0

子级绘制在父级之上，不会被裁剪。

ClipChildrenMode CLIP_CHILDREN_ONLY = 1

父级仅用于裁剪目的。子级被裁剪到父级的可见区域，不绘制父级。

ClipChildrenMode CLIP_CHILDREN_AND_DRAW = 2

父级用于裁剪子级，但在将子级剪裁到其可见区域之前，父级也像往常一样绘制在子级下方。

ClipChildrenMode CLIP_CHILDREN_MAX = 3

代表 ClipChildrenMode 枚举的大小。

常量

NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗

该 CanvasItem 的全局变换已更改。只有在通过 set_notify_transform 启用时，才会收到这个通知。

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35 🔗

该 CanvasItem 的局部变换已更改。只有在通过 set_notify_local_transform 启用时，才会收到这个通知。

NOTIFICATION_DRAW = 30 🔗

要求绘制该 CanvasItem（见 _draw）。

NOTIFICATION_VISIBILITY_CHANGED = 31 🔗

该 CanvasItem 的可见性已更改。

NOTIFICATION_ENTER_CANVAS = 32 🔗

该 CanvasItem 已进入画布。

NOTIFICATION_EXIT_CANVAS = 33 🔗

该 CanvasItem 已退出画布。

NOTIFICATION_WORLD_2D_CHANGED = 36 🔗

该 CanvasItem 的活动 World2D 已更改。

属性说明

ClipChildrenMode clip_children = 0 🔗

• void set_clip_children_mode(value: ClipChildrenMode)

• ClipChildrenMode get_clip_children_mode()

允许当前节点裁剪子节点，本质上是充当遮罩。

int light_mask = 1 🔗

• void set_light_mask(value: int)

• int get_light_mask()

该 CanvasItem 的渲染层，用于响应 Light2D 节点。

Material material 🔗

• void set_material(value: Material)

• Material get_material()

应用于这个 CanvasItem 的材质。

Color modulate = Color(1, 1, 1, 1) 🔗

• void set_modulate(value: Color)

• Color get_modulate()

应用于这个 CanvasItem 的颜色。这个属性会影响子级 CanvasItem，与只会影响节点自身的 self_modulate 不同。

Color self_modulate = Color(1, 1, 1, 1) 🔗

• void set_self_modulate(value: Color)

• Color get_self_modulate()

应用于这个 CanvasItem 的颜色。这个属性不会影响子级 CanvasItem，与会同时影响节点自身和子级的 modulate 不同。

注意：内部子节点（例如 ColorPicker 中的滑块、TabContainer 中的选项卡栏）也不受这个属性的影响（见 Node.get_child 等类似方法的 include_internal 参数）。

bool show_behind_parent = false 🔗

• void set_draw_behind_parent(value: bool)

• bool is_draw_behind_parent_enabled()

如果为 true，则对象在其父对象后面绘制。

TextureFilter texture_filter = 0 🔗

• void set_texture_filter(value: TextureFilter)

• TextureFilter get_texture_filter()

在该 CanvasItem 上使用的纹理过滤模式。

TextureRepeat texture_repeat = 0 🔗

• void set_texture_repeat(value: TextureRepeat)

• TextureRepeat get_texture_repeat()

在该 CanvasItem 上使用的纹理重复模式。

bool top_level = false 🔗

• void set_as_top_level(value: bool)

• bool is_set_as_top_level()

如果为 true，则该 CanvasItem 不会继承父级 CanvasItem 的变换。它的绘制顺序也会发生改变，会在其他没有将 top_level 设置为 true 的 CanvasItem 之上绘制。效果和把该 CanvasItem 作为裸 Node 的子级一样。

bool use_parent_material = false 🔗

• void set_use_parent_material(value: bool)

• bool get_use_parent_material()

如果为 true，则将父级 CanvasItem 的 material 属性用作此项的材质。

int visibility_layer = 1 🔗

• void set_visibility_layer(value: int)

• int get_visibility_layer()

Viewport 节点渲染该 CanvasItem 时所使用的渲染层。只有 CanvasItem 及其所有父级均与 Viewport 的画布剔除遮罩有交集，该 Viewport 才会渲染此 CanvasItem。

bool visible = true 🔗

• void set_visible(value: bool)

• bool is_visible()

如果为 true，这个 CanvasItem 被绘制。只有当它的所有父节点也可见时，该节点才是可见的（换句话说，is_visible_in_tree 必须返回 true）。

注意：对于继承了 Popup 的控件，使其可见的正确方法是调用多个 popup*() 函数之一。

bool y_sort_enabled = false 🔗

• void set_y_sort_enabled(value: bool)

• bool is_y_sort_enabled()

If true, this and child CanvasItem nodes with a higher Y position are rendered in front of nodes with a lower Y position. If false, this and child CanvasItem nodes are rendered normally in scene tree order.

With Y-sorting enabled on a parent node (‘A’) but disabled on a child node (‘B’), the child node (‘B’) is sorted but its children (‘C1’, ‘C2’, etc) render together on the same Y position as the child node (‘B’). This allows you to organize the render order of a scene without changing the scene tree.

Nodes sort relative to each other only if they are on the same z_index.

bool z_as_relative = true 🔗

• void set_z_as_relative(value: bool)

• bool is_z_relative()

如果为 true，节点的 Z 索引是相对于它的父节点的 Z 索引而言的。如果这个节点的 Z 索引是 2，它的父节点的实际 Z 索引是 3，那么这个节点的实际 Z 索引将是 2 + 3 = 5。

int z_index = 0 🔗

• void set_z_index(value: int)

• int get_z_index()

控制节点的渲染顺序。具有较高 Z 索引的节点将显示在其他节点的前面。必须在 RenderingServer.CANVAS_ITEM_Z_MIN 和 RenderingServer.CANVAS_ITEM_Z_MAX之间（包含）。

注意：改变 Control 的 Z 索引只影响绘图顺序，不影响处理输入事件的顺序。可用于实现某些 UI 动画，例如对处于悬停状态的菜单项进行缩放，此时会与其他内容重叠。

方法说明

void _draw() virtual 🔗

当 CanvasItem 被请求重绘时调用（手动调用或者引擎调用 queue_redraw 之后）。

对应于 Object._notification 中的 NOTIFICATION_DRAW 通知。

void draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) 🔗

后续的绘制命令将被忽略，除非它们位于指定的动画切片内。这是实现在背景上循环而不是不断重绘的动画的更快方法。

void draw_arc(center: Vector2, radius: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) 🔗

使用一个 uniform color 和 width 以及可选的抗锯齿（仅支持正 width ），在给定的角度之间绘制一条未填充的弧线。point_count 的值越大，该曲线越平滑。另见 draw_circle。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该弧线。这意味着当缩放 CanvasItem 时，弧线将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 start_angle < end_angle ，则圆弧是从 start_angle 朝向 end_angle 的值绘制的，即是顺时针方向；否则为逆时针方向。以相反的顺序传递相同的角度，将产生相同的弧线。如果 start_angle 和 end_angle 的差的绝对值大于 @GDScript.TAU 弧度，则绘制一个完整的圆弧（即弧线不会与自身重叠）。

void draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1)) const 🔗

使用自定义字体绘制字符串的第一个字符。

void draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1)) const 🔗

使用自定义字体绘制字符串中第一个字符的轮廓。

void draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) 🔗

绘制圆形。另见 draw_arc、draw_polyline、draw_polygon。

如果 filled 为 true，则圆形将使用指定的 color 填充。如果 filled 为 false，则圆形将被绘制为具有指定的 color 和 width 的笔划。

如果 width 为负，则将绘制两点图元而不是四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：width 只有在 filled 为 false 时才有效。

void draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) 🔗

绘制一个由任意数量的点组成的彩色多边形，凸形或凹形。与 draw_polygon 不同，必须为整个多边形指定一个单一颜色。

void draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false) 🔗

使用给定的颜色和宽度，从一个 2D 点到另一个点绘制一条虚线。另见 draw_multiline 和 draw_polyline。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条部分将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

void draw_end_animation() 🔗

通过 draw_animation_slice 提交所有动画切片后，该函数可以被用来将绘制恢复到其默认状态（所有后续绘制命令都将可见）。如果不关心这个特定用例，则不需要在提交切片后使用该函数。

void draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) 🔗

在给定的位置绘制一个带有 LCD 子像素抗锯齿的字体纹理的矩形区域，可以选择用一种颜色来调制。

纹理是通过以下混合操作绘制的，CanvasItemMaterial 的混合模式被忽略：

dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a);
dst.g = texture.g * modulate.g * modulate.a + dst.g * (1.0 - texture.g * modulate.a);
dst.b = texture.b * modulate.b * modulate.a + dst.b * (1.0 - texture.b * modulate.a);
dst.a = modulate.a + dst.a * (1.0 - modulate.a);

void draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false) 🔗

使用给定的颜色和宽度，从一个 2D 点到另一个点绘制一条直线。它可以选择抗锯齿。另请参阅 draw_multiline 和 draw_polyline。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

void draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1)) 🔗

使用所提供的纹理以 2D 方式绘制一个 Mesh。相关文档请参阅 MeshInstance2D。

void draw_msdf_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), outline: float = 0.0, pixel_range: float = 4.0, scale: float = 1.0) 🔗

在给定位置，绘制一条多通道有符号距离场纹理的纹理矩形区域，可以选择用一种颜色来调制。有关 MSDF 字体渲染的更多信息和注意事项，请参阅 FontFile.multichannel_signed_distance_field。

如果 outline 为正，则区域中像素的每个 Alpha 通道值都被设置为 outline 半径内真实距离的最大值。

pixel_range 的值应该与距离场纹理生成期间使用的值相同。

void draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) 🔗

使用一致的宽度 width 和颜色 color 绘制多条断开的线段。points 数组中相邻的两个点定义一条线段，即第 i 条线段由端点 points[2 * i] 和 points[2 * i + 1] 组成。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制相连的线段，请改用 draw_polyline。

如果 width 为负数，则会绘制由两个点组成的图元，不使用四个点组成的图元。此时如果 CanvasItem 发生缩放，则线段仍然会很细。如果不想要这样的行为，请传入 1.0 等正数 width。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

void draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) 🔗

使用一致的宽度 width 分段颜色绘制多条断开的线段。points 数组中相邻的两个点定义一条线段，即第 i 条线段由端点 points[2 * i] 和 points[2 * i + 1] 组成，使用的颜色为 colors[i]。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制相连的线段，请改用 draw_polyline_colors。

如果 width 为负数，则会绘制由两个点组成的图元，不使用四个点组成的图元。此时如果 CanvasItem 发生缩放，则线段仍然会很细。如果不想要这样的行为，请传入 1.0 等正数 width。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

void draw_multiline_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

将 text 分成几行，并在 pos（左上角）处使用指定的 font 绘制文本。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则当该文本超过指定宽度时将被裁剪。

void draw_multiline_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

将 text 分成几行，并在 pos（左上角）处使用指定的 font 绘制文本轮廓。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则当该文本超过指定宽度时将被裁剪。

void draw_multimesh(multimesh: MultiMesh, texture: Texture2D) 🔗

用所提供的纹理以 2D 方式绘制一个 MultiMesh。相关文档请参考 MultiMeshInstance2D。

void draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) 🔗

绘制一个由任意数量的点构成的实心多边形，凸形或凹形。与 draw_colored_polygon 不同，每个点的颜色都可以单独改变。另见 draw_polyline 和 draw_polyline_colors。如果你需要更大的自由度（例如能够使用骨骼），请改用 RenderingServer.canvas_item_add_triangle_array。

void draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) 🔗

使用一致的 color 和 width 以及可选的抗锯齿（仅支持正 width ），绘制相互连接的线段。绘制大量线条时，这比使用单独的 draw_line 调用更快。要绘制不相连的的线段，请改用 draw_multiline。另见 draw_polygon。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该折线。这意味着当 CanvasItem 被缩放时，折线将保持为细线。如果不需要该行为，请传入一个正的 width，如 1.0。

void draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) 🔗

绘制相连的线段，使用一致的宽度 width，按点指定颜色，还可以开启抗锯齿（仅支持正的 width）。将颜色与线段上的点匹配时，使用的是 points 和 colors 的索引，即每条线段填充的都是在两个端点之间颜色的渐变色。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制不相连的线段，请改用 draw_multiline_colors。另见 draw_polygon。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该折线。这意味着当 CanvasItem 被缩放时，折线将保持为细线。如果不需要该行为，请传入一个正的 width，如 1.0。

void draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) 🔗

绘制自定义图元。1 个点的是个点，2 个点的是线段，3 个点的是三角形，4 个点的是四边形。如果没有指定点或者指定了超过 4 个点，则不会绘制任何东西，只会输出错误消息。另请参阅 draw_line、draw_polyline、draw_polygon、draw_rect。

void draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) 🔗

绘制一个矩形。如果 filled 为 true，则矩形将使用指定的 color 填充。如果 filled 为 false，则矩形将被绘制为具有指定的 color 和 width 的笔划。另见 draw_texture_rect。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：width 只有在 filled 为 false 时才有效。

注意：使用负 width 绘制的未填充矩形可能不会完美显示。例如，由于线条的重叠，角可能会缺失或变亮（对于半透明的 color）。

void draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) 🔗

使用分量设置用于绘图的自定义变换。后续的绘制都会使用这个变换。

注意：FontFile.oversampling 不会考虑 scale。这意味着将位图字体及栅格化（非 MSDF）动态字体放大/缩小会产生模糊或像素化的结果。要让文本无论如何缩放都保持清晰，可以启用 MSDF 字体渲染，方法是启用 ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field（仅应用于默认项目字体），或者启用自定义 DynamicFont 的多通道带符号距离场导入选项。对于系统字体，可以在检查器中启用 SystemFont.multichannel_signed_distance_field。

void draw_set_transform_matrix(xform: Transform2D) 🔗

设置通过矩阵绘制时的自定义变换。此后绘制的任何东西都将被它变换。

void draw_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

使用指定的 font 在 pos（使用的字体的基线的左下角）处绘制 text。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则文本超过指定宽度将被裁剪。

使用项目默认字体的例子：

GDScriptC#

# 如果在不断重绘的脚本中使用此方法，
# 则将 `default_font` 声明移动到在 `_ready()` 中赋值的成员变量中
# 这样 Control 只创建一次。
var default_font = ThemeDB.fallback_font
var default_font_size = ThemeDB.fallback_font_size
draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size)

// 如果在不断重绘的脚本中使用此方法，
// 则将 `default_font` 声明移动到在 `_ready()` 中赋值的成员变量中
// 这样 Control 只创建一次。
Font defaultFont = ThemeDB.FallbackFont;
int defaultFontSize = ThemeDB.FallbackFontSize;
DrawString(defaultFont, new Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, defaultFontSize);

另请参阅 Font.draw_string。

void draw_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

在 pos（左下角使用字体的基线）处使用指定的 font 绘制 text 轮廓。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则当文本超过指定宽度时将被裁剪。

void draw_style_box(style_box: StyleBox, rect: Rect2) 🔗

绘制一个样式矩形。

void draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1)) 🔗

在给定的位置绘制纹理。

void draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) 🔗

在给定位置绘制一个带纹理的矩形，可以选择用颜色调制。如果 transpose 为 true，则纹理将交换其 X 和 Y 坐标。另见 draw_rect 和 draw_texture_rect_region。

void draw_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) 🔗

在给定的位置绘制具有纹理的矩形，可以指定所使用的纹理区域（由 src_rect 指定），可选择用颜色调制。如果 transpose 为 true，则纹理将交换其 X 和 Y 坐标。另见 draw_texture_rect。

void force_update_transform() 🔗

强制更新变换。由于性能原因，物理中的变换改变不是即时的。变换是在累积后再设置。如果你在进行物理操作时需要最新的变换，请使用此功能。

RID get_canvas() const 🔗

返回此项目所在的 World2D 画布的 RID。

RID get_canvas_item() const 🔗

返回 RenderingServer 对该项目使用的画布项目 RID。

CanvasLayer get_canvas_layer_node() const 🔗

返回包含该节点的 CanvasLayer，如果该节点不在任何 CanvasLayer 中，则返回 null。

Transform2D get_canvas_transform() const 🔗

返回从该项目所在的画布坐标系到 Viewport 坐标系的变换。

Vector2 get_global_mouse_position() const 🔗

返回该 CanvasItem 所在的 CanvasLayer 中鼠标的位置，使用该 CanvasLayer 的坐标系。

注意：要得到屏幕空间的坐标（例如使用非嵌入式 Popup 时），你可以使用 DisplayServer.mouse_get_position。

Transform2D get_global_transform() const 🔗

返回该项目的全局变换矩阵，即到最顶层的 CanvasItem 节点的综合变换。最顶层的项目是一个 CanvasItem，它要么没有父级，要么有非 CanvasItem 父级，或者要么它启用了 top_level。

Transform2D get_global_transform_with_canvas() const 🔗

返回从该 CanvasItem 的局部坐标系到 Viewport 坐标系的变换。

Vector2 get_local_mouse_position() const 🔗

返回该 CanvasItem 中鼠标的位置，使用该 CanvasItem 的局部坐标系。

Transform2D get_screen_transform() const 🔗

返回该 CanvasItem 在全局屏幕坐标中的变换（即考虑窗口位置）。主要用于编辑器插件。

如果窗口是嵌入的，则等于 get_global_transform（参见 Viewport.gui_embed_subwindows）。

Transform2D get_transform() const 🔗

返回此项目的变换矩阵。

Rect2 get_viewport_rect() const 🔗

以 Rect2 形式返回视口的边界。

Transform2D get_viewport_transform() const 🔗

返回从该项目所在的画布坐标系到 Viewport 嵌入坐标系的变换。

bool get_visibility_layer_bit(layer: int) const 🔗

返回渲染可见层上的某个比特位。

World2D get_world_2d() const 🔗

返回此物品所在的 World2D。

void hide() 🔗

如果该 CanvasItem 目前是可见的，则将其隐藏。相当于将 visible 设为 false。

bool is_local_transform_notification_enabled() const 🔗

如果将局部变换通知传达给子级，则返回 true。

bool is_transform_notification_enabled() const 🔗

如果将全局变换通知传达给子级，则返回 true。

bool is_visible_in_tree() const 🔗

Returns true if the node is present in the SceneTree, its visible property is true and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see _draw).

Visibility is checked only in parent nodes that inherit from CanvasItem, CanvasLayer, and Window. If the parent is of any other type (such as Node, AnimationPlayer, or Node3D), it is assumed to be visible.

Vector2 make_canvas_position_local(screen_point: Vector2) const 🔗

将 screen_point 指定为该节点的新局部变换。

InputEvent make_input_local(event: InputEvent) const 🔗

event 的输入发出的变换将在局部空间而不是全局空间中应用。

void move_to_front() 🔗

移动该节点以显示在其同级节点之上。

在内部，该节点被移动到父节点的子节点列表的底部。该方法对没有父节点的节点没有影响。

void queue_redraw() 🔗

将该 CanvasItem 加入重绘队列。空闲时，如果 CanvasItem 可见，则会发送 NOTIFICATION_DRAW 并调用 _draw。即便多次调用这个方法，每帧也都只会发生一次绘制。

void set_notify_local_transform(enable: bool) 🔗

如果 enable 为 true，则该节点将在其局部变换发生改变时收到 NOTIFICATION_LOCAL_TRANSFORM_CHANGED。

void set_notify_transform(enable: bool) 🔗

如果 enable 为 true，那么这个节点会在其全局变换发生改变时接收到 NOTIFICATION_TRANSFORM_CHANGED。

void set_visibility_layer_bit(layer: int, enabled: bool) 🔗

设置或清除渲染可见层上的单个位。这简化了对该 CanvasItem 的可见层的编辑。

void show() 🔗

如果该 CanvasItem 目前是隐藏的，则将其显示。相当于将 visible 设为 true。对于继承自 Popup 的控件，让它们可见的正确做法是换成调用各种 popup*() 函数的其中之一。