Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 索引、混合模式等。

教程¶

属性¶

ClipChildrenMode	clip_children	`0`
int	light_mask	`1`
Material	material
Color	modulate	`Color(1, 1, 1, 1)`
Color	self_modulate	`Color(1, 1, 1, 1)`
bool	show_behind_parent	`false`
TextureFilter	texture_filter	`0`
TextureRepeat	texture_repeat	`0`
bool	top_level	`false`
bool	use_parent_material	`false`
int	visibility_layer	`1`
bool	visible	`true`
bool	y_sort_enabled	`false`
bool	z_as_relative	`true`
int	z_index	`0`

方法¶

void	_draw ( ) virtual
void	draw_animation_slice ( float animation_length, float slice_begin, float slice_end, float offset=0.0 )
void	draw_arc ( Vector2 center, float radius, float start_angle, float end_angle, int point_count, Color color, float width=-1.0, bool antialiased=false )
void	draw_char ( Font font, Vector2 pos, String char, int font_size=16, Color modulate=Color(1, 1, 1, 1) ) const
void	draw_char_outline ( Font font, Vector2 pos, String char, int font_size=16, int size=-1, Color modulate=Color(1, 1, 1, 1) ) const
void	draw_circle ( Vector2 position, float radius, Color color )
void	draw_colored_polygon ( PackedVector2Array points, Color color, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )
void	draw_dashed_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, float dash=2.0, bool aligned=true )
void	draw_end_animation ( )
void	draw_lcd_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1) )
void	draw_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, bool antialiased=false )
void	draw_mesh ( Mesh mesh, Texture2D texture, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), Color modulate=Color(1, 1, 1, 1) )
void	draw_msdf_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1), float outline=0.0, float pixel_range=4.0, float scale=1.0 )
void	draw_multiline ( PackedVector2Array points, Color color, float width=-1.0 )
void	draw_multiline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0 )
void	draw_multiline_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_multiline_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_multimesh ( MultiMesh multimesh, Texture2D texture )
void	draw_polygon ( PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )
void	draw_polyline ( PackedVector2Array points, Color color, float width=-1.0, bool antialiased=false )
void	draw_polyline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0, bool antialiased=false )
void	draw_primitive ( PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs, Texture2D texture=null )
void	draw_rect ( Rect2 rect, Color color, bool filled=true, float width=-1.0 )
void	draw_set_transform ( Vector2 position, float rotation=0.0, Vector2 scale=Vector2(1, 1) )
void	draw_set_transform_matrix ( Transform2D xform )
void	draw_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_style_box ( StyleBox style_box, Rect2 rect )
void	draw_texture ( Texture2D texture, Vector2 position, Color modulate=Color(1, 1, 1, 1) )
void	draw_texture_rect ( Texture2D texture, Rect2 rect, bool tile, Color modulate=Color(1, 1, 1, 1), bool transpose=false )
void	draw_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1), bool transpose=false, bool clip_uv=true )
void	force_update_transform ( )
RID	get_canvas ( ) const
RID	get_canvas_item ( ) const
Transform2D	get_canvas_transform ( ) const
Vector2	get_global_mouse_position ( ) const
Transform2D	get_global_transform ( ) const
Transform2D	get_global_transform_with_canvas ( ) const
Vector2	get_local_mouse_position ( ) const
Transform2D	get_screen_transform ( ) const
Transform2D	get_transform ( ) const
Rect2	get_viewport_rect ( ) const
Transform2D	get_viewport_transform ( ) const
bool	get_visibility_layer_bit ( int layer ) const
World2D	get_world_2d ( ) const
void	hide ( )
bool	is_local_transform_notification_enabled ( ) const
bool	is_transform_notification_enabled ( ) const
bool	is_visible_in_tree ( ) const
Vector2	make_canvas_position_local ( Vector2 screen_point ) const
InputEvent	make_input_local ( InputEvent event ) const
void	move_to_front ( )
void	queue_redraw ( )
void	set_notify_local_transform ( bool enable )
void	set_notify_transform ( bool enable )
void	set_visibility_layer_bit ( int layer, bool enabled )
void	show ( )

信号¶

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

纹理过滤器在最邻近的四个像素之间混合。如果想要避免像素化样式，大多数情况下请使用此选项。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤器读取最邻近的 mipmap 中的最邻近像素。这是使用 mipmap 从纹理中读取的最快方法。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

纹理过滤器在最邻近的 4 个像素和最邻近的 2 个 mipmap 之间混合。请用于可能以低缩放率查看的非像素画纹理（例如由 Camera2D 缩放造成），因为 mipmap 对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤器读取最邻近的像素，但会根据表面和相机视图之间的角度选择 mipmap。可以减少几乎与相机成一直线的表面的伪影。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：这个纹理过滤器很少用于 2D 项目。TEXTURE_FILTER_NEAREST_WITH_MIPMAPS 通常更合适。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

纹理过滤器在最邻近的 4 个像素之间进行混合，并会根据表面和相机视图之间的角度选择 mipmap。可以减少几乎与相机成一直线的表面的伪影。这是最慢的过滤选项，但可以得到最高质量的纹理。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：这个纹理过滤器很少用于 2D 项目。TEXTURE_FILTER_NEAREST_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

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

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 ( ClipChildrenMode value )
ClipChildrenMode get_clip_children_mode ( )

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

int light_mask = 1

void set_light_mask ( int value )
int get_light_mask ( )

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

Material material

void set_material ( Material value )
Material get_material ( )

应用于这个 CanvasItem 的材质。

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

void set_modulate ( Color value )
Color get_modulate ( )

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

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

void set_self_modulate ( Color value )
Color get_self_modulate ( )

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

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

bool show_behind_parent = false

void set_draw_behind_parent ( bool value )
bool is_draw_behind_parent_enabled ( )

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

TextureFilter texture_filter = 0

void set_texture_filter ( TextureFilter value )
TextureFilter get_texture_filter ( )

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

TextureRepeat texture_repeat = 0

void set_texture_repeat ( TextureRepeat value )
TextureRepeat get_texture_repeat ( )

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

bool top_level = false

void set_as_top_level ( bool value )
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 ( bool value )
bool get_use_parent_material ( )

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

int visibility_layer = 1

void set_visibility_layer ( int value )
int get_visibility_layer ( )

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

bool visible = true

void set_visible ( bool value )
bool is_visible ( )

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

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

bool y_sort_enabled = false

void set_y_sort_enabled ( bool value )
bool is_y_sort_enabled ( )

如果为 true，则会在绘制 Y 位置最低的子节点之后再绘制 Y 位置较高的子节点。如果为 false，则禁用 Y 排序。Y 排序仅影响继承自 CanvasItem 的子节点。

可以将 Y 排序的节点进行嵌套。子级 Y 排序的节点，会与父级在同一空间中进行 Y 排序。此功能可以让你在不更改场景树的情况下，更好地组织场景，或者将场景分为多个场景。

bool z_as_relative = true

void set_z_as_relative ( bool value )
bool is_z_relative ( )

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

int z_index = 0

void set_z_index ( int value )
int get_z_index ( )

Z 索引。控制节点的渲染顺序。具有较高 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 ( float animation_length, float slice_begin, float slice_end, float offset=0.0 )

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

void draw_arc ( Vector2 center, float radius, float start_angle, float end_angle, int point_count, Color color, float width=-1.0, bool antialiased=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, Vector2 pos, String char, int font_size=16, Color modulate=Color(1, 1, 1, 1) ) const

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

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

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

void draw_circle ( Vector2 position, float radius, Color color )

绘制彩色的实心圆。另见 draw_arc、draw_polyline 和 draw_polygon。

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

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

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

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

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

void draw_end_animation ( )

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

void draw_lcd_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=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 ( Vector2 from, Vector2 to, Color color, float width=-1.0, bool antialiased=false )

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

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

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

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

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

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

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

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

void draw_multiline ( PackedVector2Array points, Color color, float width=-1.0 )

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

如果 width 为负