TreeItem

继承： Object

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

描述

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

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

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

属性

方法

枚举

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_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 处的按钮。

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。

String get_button_tooltip_text(column: int, button_index: int) const 🔗

返回在 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 颜色。

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，如果没有，则返回一个空对象。

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，如果没有，则返回一个空对象。

TreeItem get_prev() 🔗

返回树中的前一个兄弟 TreeItem，如果没有，则返回一个空对象。

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。

String get_tooltip_text(column: int) const 🔗

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

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_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 的按钮。

void set_button_tooltip_text(column: int, button_index: int, tooltip: String) 🔗

设置给定 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 模式。

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_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 set_tooltip_text(column: int, tooltip: String) 🔗

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

void uncollapse_tree() 🔗

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