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...

TreeItem

继承： Object

代表 Tree 中某个项目的内部控件。

描述

Tree 控件中的单个项目。可以包含其他 TreeItem 作为子级，从而创建层级结构。还可以包含文本和按钮。TreeItem 不是 Node，在 Tree 内部使用。

创建 TreeItem 请使用 Tree.create_item() 或 create_child()。移除 TreeItem 请使用 Object.free()。

注意：按钮的 ID 值为 32 位，与始终为 64 位的 int 不同。取值范围为 -2147483648 到 2147483647。

属性

bool	collapsed
int	custom_minimum_height
bool	disable_folding
bool	visible

方法

void	add_button(column: int, button: Texture2D, id: int = -1, disabled: bool = false, tooltip_text: String = "")
void	add_child(child: TreeItem)
void	call_recursive(method: StringName, ...) vararg
void	clear_buttons()
void	clear_custom_bg_color(column: int)
void	clear_custom_color(column: int)
TreeItem	create_child(index: int = -1)
void	deselect(column: int)
void	erase_button(column: int, button_index: int)
AutoTranslateMode	get_auto_translate_mode(column: int) const
AutowrapMode	get_autowrap_mode(column: int) const
Texture2D	get_button(column: int, button_index: int) const
int	get_button_by_id(column: int, id: int) const
Color	get_button_color(column: int, id: int) const
int	get_button_count(column: int) const
int	get_button_id(column: int, button_index: int) const
String	get_button_tooltip_text(column: int, button_index: int) const
TreeCellMode	get_cell_mode(column: int) const
TreeItem	get_child(index: int)
int	get_child_count()
Array[TreeItem]	get_children()
Color	get_custom_bg_color(column: int) const
Color	get_custom_color(column: int) const
Callable	get_custom_draw_callback(column: int) const
Font	get_custom_font(column: int) const
int	get_custom_font_size(column: int) const
bool	get_expand_right(column: int) const
TreeItem	get_first_child() const
Texture2D	get_icon(column: int) const
int	get_icon_max_width(column: int) const
Color	get_icon_modulate(column: int) const
Texture2D	get_icon_overlay(column: int) const
Rect2	get_icon_region(column: int) const
int	get_index()
String	get_language(column: int) const
Variant	get_metadata(column: int) const
TreeItem	get_next() const
TreeItem	get_next_in_tree(wrap: bool = false)
TreeItem	get_next_visible(wrap: bool = false)
TreeItem	get_parent() const
TreeItem	get_prev()
TreeItem	get_prev_in_tree(wrap: bool = false)
TreeItem	get_prev_visible(wrap: bool = false)
float	get_range(column: int) const
Dictionary	get_range_config(column: int)
StructuredTextParser	get_structured_text_bidi_override(column: int) const
Array	get_structured_text_bidi_override_options(column: int) const
String	get_suffix(column: int) const
String	get_text(column: int) const
HorizontalAlignment	get_text_alignment(column: int) const
TextDirection	get_text_direction(column: int) const
OverrunBehavior	get_text_overrun_behavior(column: int) const
String	get_tooltip_text(column: int) const
Tree	get_tree() const
bool	is_any_collapsed(only_visible: bool = false)
bool	is_button_disabled(column: int, button_index: int) const
bool	is_checked(column: int) const
bool	is_custom_set_as_button(column: int) const
bool	is_edit_multiline(column: int) const
bool	is_editable(column: int)
bool	is_indeterminate(column: int) const
bool	is_selectable(column: int) const
bool	is_selected(column: int)
bool	is_visible_in_tree() const
void	move_after(item: TreeItem)
void	move_before(item: TreeItem)
void	propagate_check(column: int, emit_signal: bool = true)
void	remove_child(child: TreeItem)
void	select(column: int)
void	set_auto_translate_mode(column: int, mode: AutoTranslateMode)
void	set_autowrap_mode(column: int, autowrap_mode: AutowrapMode)
void	set_button(column: int, button_index: int, button: Texture2D)
void	set_button_color(column: int, button_index: int, color: Color)
void	set_button_disabled(column: int, button_index: int, disabled: bool)
void	set_button_tooltip_text(column: int, button_index: int, tooltip: String)
void	set_cell_mode(column: int, mode: TreeCellMode)
void	set_checked(column: int, checked: bool)
void	set_collapsed_recursive(enable: bool)
void	set_custom_as_button(column: int, enable: bool)
void	set_custom_bg_color(column: int, color: Color, just_outline: bool = false)
void	set_custom_color(column: int, color: Color)
void	set_custom_draw(column: int, object: Object, callback: StringName)
void	set_custom_draw_callback(column: int, callback: Callable)
void	set_custom_font(column: int, font: Font)
void	set_custom_font_size(column: int, font_size: int)
void	set_edit_multiline(column: int, multiline: bool)
void	set_editable(column: int, enabled: bool)
void	set_expand_right(column: int, enable: bool)
void	set_icon(column: int, texture: Texture2D)
void	set_icon_max_width(column: int, width: int)
void	set_icon_modulate(column: int, modulate: Color)
void	set_icon_overlay(column: int, texture: Texture2D)
void	set_icon_region(column: int, region: Rect2)
void	set_indeterminate(column: int, indeterminate: bool)
void	set_language(column: int, language: String)
void	set_metadata(column: int, meta: Variant)
void	set_range(column: int, value: float)
void	set_range_config(column: int, min: float, max: float, step: float, expr: bool = false)
void	set_selectable(column: int, selectable: bool)
void	set_structured_text_bidi_override(column: int, parser: StructuredTextParser)
void	set_structured_text_bidi_override_options(column: int, args: Array)
void	set_suffix(column: int, text: String)
void	set_text(column: int, text: String)
void	set_text_alignment(column: int, text_alignment: HorizontalAlignment)
void	set_text_direction(column: int, direction: TextDirection)
void	set_text_overrun_behavior(column: int, overrun_behavior: OverrunBehavior)
void	set_tooltip_text(column: int, tooltip: String)
void	uncollapse_tree()

枚举

enum TreeCellMode: 🔗

TreeCellMode CELL_MODE_STRING = 0

单元格显示字符串标签，可以带图标。单元格可编辑时，文本可以使用 LineEdit 进行编辑，如果使用了 set_edit_multiline() 则会使用 TextEdit 弹框进行编辑。

TreeCellMode CELL_MODE_CHECK = 1

单元格显示复选框，可以带文本和图标。复选框可以处于勾选、未勾选以及未定状态（使用 set_indeterminate()）。单元格可编辑时才能够点击复选框。

TreeCellMode CELL_MODE_RANGE = 2

单元格显示数字范围。可编辑时，该数字可以使用范围滑块编辑。设值请使用 set_range()，设置范围请使用 set_range_config()。

如果使用 set_text() 设置文本，该单元格也可以处于文本下拉框模式。请使用英文逗号分隔选项，例如 "选项甲,选项乙,选项丙"。

TreeCellMode CELL_MODE_ICON = 3

单元格显示图标。无法编辑和显示文本。图标始终在单元格内居中。

TreeCellMode CELL_MODE_CUSTOM = 4

单元格显示可点击的按钮。单元格会显示一个类似于 OptionButton 的箭头，但是不带下拉框（如果对此有需要请使用 CELL_MODE_RANGE）。点击按钮会发出 Tree.item_edited 信号。按钮默认是扁平的，可以使用 set_custom_as_button() 为其设置 StyleBox。

该模式还支持通过使用 set_custom_draw_callback() 进行自定义绘制。

属性说明

bool collapsed 🔗

void set_collapsed(value: bool)
bool is_collapsed()

如果为 true，则该 TreeItem 被折叠。

int custom_minimum_height 🔗

void set_custom_minimum_height(value: int)
int get_custom_minimum_height()

自定义最小高度。

bool disable_folding 🔗

void set_disable_folding(value: bool)
bool is_folding_disabled()

如果为 true，则这个 TreeItem 禁用折叠。

bool visible 🔗

void set_visible(value: bool)
bool is_visible()

如果为 true，则该 TreeItem 可见（默认）。

请注意，如果将 TreeItem 设置为不可见，则其子项也将不可见。

方法说明

void add_button(column: int, button: Texture2D, id: int = -1, disabled: bool = false, tooltip_text: String = "") 🔗

在 column 列的末尾添加一个带有 Texture button 的按钮。id 用于标识按钮。如果未指定，则使用下一个可用索引，可以在此方法之前调用 get_button_count() 来获取该索引。另外，该按钮还可以通过 disabled 禁用、通过 tooltip_text 设置工具提示。

void add_child(child: TreeItem) 🔗

将已解除父子关系的 TreeItem 添加为这个树项的直接子项。child 树项必须不是任何 Tree 的一部分，也不能有任何 TreeItem 父级。另见 remove_child()。

void call_recursive(method: StringName, ...) vararg 🔗

递归调用在实际 TreeItem 及其子项上的 method。将参数作为一个逗号分隔列表传递。

void clear_buttons() 🔗

移除该项目所有列中的所有按钮。

void clear_custom_bg_color(column: int) 🔗

重置指定列默认的背景颜色。

void clear_custom_color(column: int) 🔗

重置指定列默认的颜色。

TreeItem create_child(index: int = -1) 🔗

创建项目并添加为子项。

新建的项目会插入到索引 index 位置（默认的 -1 表示最后的位置），如果 index 比子项数量大则会作为最后一项。

void deselect(column: int) 🔗

取消选择指定列。

void erase_button(column: int, button_index: int) 🔗

删除列 column 中索引 button_index 处的按钮。

AutoTranslateMode get_auto_translate_mode(column: int) const 🔗

返回该列的自动翻译模式。

AutowrapMode get_autowrap_mode(column: int) const 🔗

返回给定列 column 的文本自动换行模式。默认为 TextServer.AUTOWRAP_OFF。

Texture2D get_button(column: int, button_index: int) const 🔗

返回在 column 列中索引为 button_index 的按钮的 Texture。

int get_button_by_id(column: int, id: int) const 🔗

如果在 column 列中存在 ID 为 id 的按钮，则返回其索引号，否则返回 -1。

Color get_button_color(column: int, id: int) const 🔗

返回列 column 中 ID 为 id 的按钮的颜色。如果指定的按钮不存在，则返回 Color.BLACK。

int get_button_count(column: int) const 🔗

返回在 column 列中按钮的数量。

int get_button_id(column: int, button_index: int) const 🔗

返回在 column 列中索引为 button_index 的按钮的 ID。

返回在 column 列中索引为 button_index 的按钮的工具提示字符串。

TreeCellMode get_cell_mode(column: int) const 🔗

返回该列的单元格模式。

TreeItem get_child(index: int) 🔗

按其 index 返回一个子项（参见 get_child_count()）。该方法通常被用于迭代一个项目的所有子项。

负索引将从最后一个访问孩子。

int get_child_count() 🔗

返回子项的数量。

Array[TreeItem] get_children() 🔗

返回引用该项目子级的数组。

Color get_custom_bg_color(column: int) const 🔗

返回列 column 的自定义背景色。

Color get_custom_color(column: int) const 🔗

返回列 column 的自定义颜色。

Callable get_custom_draw_callback(column: int) const 🔗

返回列 column 的自定义回调。

Font get_custom_font(column: int) const 🔗

返回用于在 column 列绘制文本的自定义字体。

int get_custom_font_size(column: int) const 🔗

返回用于在 column 列绘制文本的自定义字体大小。

bool get_expand_right(column: int) const 🔗

如果设置了 expand_right，则返回 true。

TreeItem get_first_child() const 🔗

返回该 TreeItem 的第一个子项。

Texture2D get_icon(column: int) const 🔗

返回给定列的图标 Texture2D。如果未设置图标，则会出错。

int get_icon_max_width(column: int) const 🔗

返回给定列 column 中图标所允许的最大宽度。

Color get_icon_modulate(column: int) const 🔗

返回调制列的图标的 Color 颜色。

Texture2D get_icon_overlay(column: int) const 🔗

返回给定列的图标覆盖 Texture2D。

Rect2 get_icon_region(column: int) const 🔗

返回图标 Texture2D 的区域，类型为 Rect2。

int get_index() 🔗

返回该节点在树中的顺序。例如对第一个子项调用时，得到的位置为 0。

String get_language(column: int) const 🔗

返回项目文本的语言代码。

Variant get_metadata(column: int) const 🔗

返回使用 set_metadata() 为指定列设置的元数据。

TreeItem get_next() const 🔗

返回树中的下一个同级 TreeItem，如果没有则返回 null 对象。

TreeItem get_next_in_tree(wrap: bool = false) 🔗

返回树中的下一个 TreeItem（按照深度优先搜索顺序），如果不存在则返回 null 对象。

如果启用了 wrap，则当在最后一个元素上调用时，该方法将绕回到树中的第一个元素，否则返回 null。

TreeItem get_next_visible(wrap: bool = false) 🔗

返回树中下一个可见的 TreeItem（按照深度优先搜索顺序），如果不存在则返回 null 对象。

如果启用了 wrap，则当在最后一个元素上调用时，该方法将绕回到树中的第一个可见元素，否则返回 null。

TreeItem get_parent() const 🔗

返回父级 TreeItem，如果没有则返回 null 对象。

TreeItem get_prev() 🔗

返回树中的前一个同级 TreeItem，如果没有则返回 null 对象。

TreeItem get_prev_in_tree(wrap: bool = false) 🔗

返回树中前一个同级 TreeItem（按照深度优先顺序搜索），如果不存在则返回 null 对象。

如果启用了 wrap，则在第一个可见元素上调用时，该方法将环绕到树中的最后一个可见元素，否则它将返回 null。

TreeItem get_prev_visible(wrap: bool = false) 🔗

返回树中前一个可见的同级 TreeItem（按照深度优先搜索顺序），如果不存在则返回 null 对象。

如果启用了 wrap，则在第一个可见元素上调用时，该方法将绕回到树中的最后一个可见元素，否则它将返回 null。

float get_range(column: int) const 🔗

返回 CELL_MODE_RANGE 列的值。

Dictionary get_range_config(column: int) 🔗

返回包含给定列的范围参数的字典。键是“min”、“max”、“step”和“expr”。

StructuredTextParser get_structured_text_bidi_override(column: int) const 🔗

返回为该单元格设置的 BiDi 算法覆盖。

Array get_structured_text_bidi_override_options(column: int) const 🔗

返回为该单元格设置的附加 BiDi 选项。

String get_suffix(column: int) const 🔗

获取显示在列值后面的后缀字符串。

String get_text(column: int) const 🔗

返回给定列的文本。

HorizontalAlignment get_text_alignment(column: int) const 🔗

返回给定列的文本对齐方式。

TextDirection get_text_direction(column: int) const 🔗

返回项目文本的基础书写方向。

OverrunBehavior get_text_overrun_behavior(column: int) const 🔗

返回当给定 column 中文本超出项目的边界矩形时的裁剪行为。默认情况下它是 TextServer.OVERRUN_TRIM_ELLIPSIS。

设置给定列的工具提示文本。

Tree get_tree() const 🔗

返回拥有此 TreeItem 的 Tree。

bool is_any_collapsed(only_visible: bool = false) 🔗

如果这个 TreeItem 或其任意子级为折叠状态，则返回 true。

如果 only_visible 为 true，则会忽略不可见的 TreeItem。

bool is_button_disabled(column: int, button_index: int) const 🔗

如果给定列 column 上索引为 button_index 的按钮被禁用，则返回 true。

bool is_checked(column: int) const 🔗

如果给定的列 column 被勾选，则返回 true。

bool is_custom_set_as_button(column: int) const 🔗

如果使用 set_custom_as_button() 将该单元格变成了按钮，则返回 true。

bool is_edit_multiline(column: int) const 🔗

如果给定的列 column 可多行编辑，则返回 true。

bool is_editable(column: int) 🔗

如果给定的列 column 可编辑，则返回 true。

bool is_indeterminate(column: int) const 🔗

如果给定的列 column 未确定，则返回 true。

bool is_selectable(column: int) const 🔗

如果给定的列 column 可选，则返回 true。

bool is_selected(column: int) 🔗

如果给定的列 column 被选中，则返回 true。

bool is_visible_in_tree() const 🔗

如果 visible 为 true 并且所有祖级项目也都可见，则返回 true。

void move_after(item: TreeItem) 🔗

将这个 TreeItem 移动至给定的 item 之后。

注意：无法移动至根部，也无法移动根部。

void move_before(item: TreeItem) 🔗

将这个 TreeItem 移动至给定的 item 之前。

注意：无法移动至根部，也无法移动根部。

void propagate_check(column: int, emit_signal: bool = true) 🔗

将该项的勾选状态传播给给定 column 的子项和父项。可以通过连接到 Tree.check_propagated_to_item 来处理受该方法调用影响的项目。受影响的项目的处理顺序如下：调用该方法的项目、该项的子项，最后是该项的父项。如果 emit_signal 为 false，则不会发出 Tree.check_propagated_to_item。

void remove_child(child: TreeItem) 🔗

将给定的子项 TreeItem 和它的所有子项从 Tree 中移除。注意，它并未从内存中释放该项，所以之后可重新使用（见 add_child()）。要完全删除 TreeItem，请使用 Object.free()。

注意：如果你想要将一个子项移动到其他 Tree 中，则不必手动先移除再添加，你可以使用 move_before() 或 move_after()。

void select(column: int) 🔗

选中 column 指定的列。

void set_auto_translate_mode(column: int, mode: AutoTranslateMode) 🔗

将给定列的自动翻译模式设为 mode。

所有列都默认使用 Node.AUTO_TRANSLATE_MODE_INHERIT，即使用与 Tree 相同的自动翻译模式。

void set_autowrap_mode(column: int, autowrap_mode: AutowrapMode) 🔗

设置给定 column 的自动换行模式。如果设置为 TextServer.AUTOWRAP_OFF 以外的值，则文本将在节点的边界矩形内换行。

void set_button(column: int, button_index: int, button: Texture2D) 🔗

将给定列中索引为 button_index 的按钮 Texture2D 设置为 button。

void set_button_color(column: int, button_index: int, color: Color) 🔗

将给定列中索引为 button_index 的按钮颜色设置为 color。

void set_button_disabled(column: int, button_index: int, disabled: bool) 🔗

如果为 true，则禁用给定列 column 中索引为 button_index 的按钮。

设置给定 column 中索引 button_index 处按钮的工具提示文本。

void set_cell_mode(column: int, mode: TreeCellMode) 🔗

将给定列的单元格模式设置为 mode。决定了单元格的显示和编辑方式。见 TreeCellMode 常量。

void set_checked(column: int, checked: bool) 🔗

如果 checked 为 true，则给定列 column 处于勾选状态。会清空该列的中间状态。

void set_collapsed_recursive(enable: bool) 🔗

折叠或展开该 TreeItem 及该项的所有子级。

void set_custom_as_button(column: int, enable: bool) 🔗

让 CELL_MODE_CUSTOM 的单元格显示为使用 StyleBox 的非扁平按钮。

void set_custom_bg_color(column: int, color: Color, just_outline: bool = false) 🔗

设置给定列的自定义背景颜色，以及是否只将其作为一个轮廓。

void set_custom_color(column: int, color: Color) 🔗

设置给定列的自定义颜色。

void set_custom_draw(column: int, object: Object, callback: StringName) 🔗

已弃用： Use set_custom_draw_callback() instead.

将给定列的自定义绘制回调设置为 object 上的 callback 方法。

名为 callback 的方法应接受两个参数：被绘制的 TreeItem 及其作为一个 Rect2 的位置和大小。

void set_custom_draw_callback(column: int, callback: Callable) 🔗

设置给定列的自定义绘制回调。使用空的 Callable（Callable()）清除自定义回调。单元格必须处于 CELL_MODE_CUSTOM 模式才能使用该功能。

名为 callback 的方法应接受两个参数：被绘制的 TreeItem 及其作为一个 Rect2 的位置和大小。

void set_custom_font(column: int, font: Font) 🔗

设置用于在给定列 column 中绘制文本的自定义字体。

void set_custom_font_size(column: int, font_size: int) 🔗

设置用于在给定列 column 中绘制文本的自定义字体大小。

void set_edit_multiline(column: int, multiline: bool) 🔗

如果 multiline 为 true，则给定的列 column 可进行多行编辑。

注意：这个选项仅影响编辑该列时所出现控件的类型（LineEdit 或 TextEdit）。即便该列不可进行多行编辑，也可以通过 set_text() 来设置多行的值。

void set_editable(column: int, enabled: bool) 🔗

如果 enabled 为 true，则给定的列 column 可编辑。

void set_expand_right(column: int, enable: bool) 🔗

如果 enable 为 true，则给定的列 column 向右扩展。

void set_icon(column: int, texture: Texture2D) 🔗

设置给定单元格的图标 Texture2D。如果单元格处于 CELL_MODE_ICON 模式，则会在单元格的中心显示图标。否则图标在单元格文本之前显示。CELL_MODE_RANGE 不显示图标。

void set_icon_max_width(column: int, width: int) 🔗

设置给定列 column 所允许的最大图标宽度。这是在图标默认大小和 Tree.icon_max_width 的基础上的限制。高度会根据图标的长宽比调整。

void set_icon_modulate(column: int, modulate: Color) 🔗

用 modulate 调制给定列的图标。

void set_icon_overlay(column: int, texture: Texture2D) 🔗

设置给定单元格的图标覆盖 Texture2D。单元格必须处于 CELL_MODE_ICON 模式且必须设置图标。覆盖项绘制在图标之上，位于左下角。

void set_icon_region(column: int, region: Rect2) 🔗

设置给定列的图标的纹理区域。

void set_indeterminate(column: int, indeterminate: bool) 🔗

如果 indeterminate 为 true，则给定列 column 被标记为未决状态。

注意：如果从 false 设置为 true，则该列的勾选状态会被清除。

void set_language(column: int, language: String) 🔗

设置项目文本的语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

void set_metadata(column: int, meta: Variant) 🔗

设置给定列的元数据，之后可用 get_metadata() 进行检索。例如，这可用于存储对原始数据的引用。

void set_range(column: int, value: float) 🔗

设置 CELL_MODE_RANGE 列的值。

void set_range_config(column: int, min: float, max: float, step: float, expr: bool = false) 🔗

设置列的可接受值的范围。该列必须处于 CELL_MODE_RANGE 模式。

如果 expr 为 true，则编辑模式滑块将使用与 Range.exp_edit 一样的指数刻度。

void set_selectable(column: int, selectable: bool) 🔗

如果 selectable 为 true，则给定列 column 可选。

void set_structured_text_bidi_override(column: int, parser: StructuredTextParser) 🔗

为结构化文本设置 BiDi 算法覆盖。对显示文本的单元格有影响。

void set_structured_text_bidi_override_options(column: int, args: Array) 🔗

设置 BiDi 覆盖的附加选项。对显示文本的单元格有效果。

void set_suffix(column: int, text: String) 🔗

设置字符串，显示在列的值之后（例如，单位的缩写）。

void set_text(column: int, text: String) 🔗

设置给定列的文本值。

void set_text_alignment(column: int, text_alignment: HorizontalAlignment) 🔗

设置给定列的文本对齐方式。可能的值见 HorizontalAlignment。

void set_text_direction(column: int, direction: TextDirection) 🔗

设置项目文本的基础书写方向。

void set_text_overrun_behavior(column: int, overrun_behavior: OverrunBehavior) 🔗

设置当文本超出给定 column 中项目的边界矩形时的裁剪行为。

设置给定列的工具提示文本。

void uncollapse_tree() 🔗

展开显示该 TreeItem 所需的所有 TreeItem，即所有祖先 TreeItem。