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...
OptionButton
继承： Button < BaseButton < Control < CanvasItem < Node < Object
按下时弹出下拉菜单的按钮。
描述
OptionButton 是一种按下时弹出下拉菜单的按钮。选中的菜单项会成为“当前”菜单项，作为按钮文本显示。
另见 BaseButton，其中包含与此节点相关联的通用属性和方法。
注意：菜单项的 ID 限制为带符号 32 位整数，并不是完整的 64 位 int。取值范围为 -2^31 到 2^31 - 1，即 -2147483648 到 2147483647。
注意：Button.text 和 Button.icon 属性会根据当前所选菜单项自动设置。不应该手动更改。
属性
action_mode |
|
|
alignment |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
toggle_mode |
|
方法
void |
add_icon_item(texture: Texture2D, label: String, id: int = -1) |
void |
|
void |
add_separator(text: String = "") |
void |
clear() |
get_item_auto_translate_mode(idx: int) const |
|
get_item_icon(idx: int) const |
|
get_item_id(idx: int) const |
|
get_item_index(id: int) const |
|
get_item_metadata(idx: int) const |
|
get_item_text(idx: int) const |
|
get_item_tooltip(idx: int) const |
|
get_popup() const |
|
get_selectable_item(from_last: bool = false) const |
|
get_selected_id() const |
|
get_selected_metadata() const |
|
has_selectable_items() const |
|
is_item_disabled(idx: int) const |
|
is_item_separator(idx: int) const |
|
void |
remove_item(idx: int) |
void |
|
void |
set_disable_shortcuts(disabled: bool) |
void |
set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode) |
void |
set_item_disabled(idx: int, disabled: bool) |
void |
set_item_icon(idx: int, texture: Texture2D) |
void |
set_item_id(idx: int, id: int) |
void |
set_item_metadata(idx: int, metadata: Variant) |
void |
set_item_text(idx: int, text: String) |
void |
set_item_tooltip(idx: int, tooltip: String) |
void |
主题属性
|
||
|
||
信号
当用户通过 ProjectSettings.input/ui_up（向上）或 ProjectSettings.input/ui_down（向下）输入动作导航到某个项目时，会触发（发射）此信号。被聚焦的项目的索引（index）会作为参数传递进来。
当用户更改当前项时触发。所选项目的索引作为参数传递。
必须启用 allow_reselect 才能重新选中项目。
属性说明
如果为 true，则可以再次选择当前选中的项目。
bool fit_to_longest_item = true 🔗
如果为 true，最小尺寸将由最长项目的文本确定，而不是当前选定的文本。
注意：出于性能原因，在添加、移除或修改项目时，最小尺寸不会立即更新。
可供挑选的菜单项的数量。
bool popup/item_{index}/disabled = false 🔗
如果为 true，则禁用位于 index 处的项目。
注意： index 的取值范围为 0 .. item_count - 1。
Texture2D popup/item_{index}/icon 🔗
位于 index 处的项目的图标。
注意： index 的取值范围为 0 .. item_count - 1。
int popup/item_{index}/id = 0 🔗
索引为 index 的菜单项的 ID。
注意： index 的取值必须在 0 .. item_count - 1 范围内。
bool popup/item_{index}/separator = false 🔗
如果为 true，则索引为 index 的菜单项是一个分隔符。
注意： index 的取值必须在 0 .. item_count - 1 范围内。
String popup/item_{index}/text = "" 🔗
位于 index 处的项目的文本。
注意： index 的取值范围为 0 .. item_count - 1。
bool search_bar_enabled = false 🔗
如果为 true，则在 PopupMenu 顶部显示一个用于筛选项目的搜索栏。请参阅 search_bar_min_item_count，以了解基于项目数量动态控制其可见性的方法。
bool search_bar_fuzzy_search_enabled = true 🔗
如果为 true，则在 PopupMenu 的搜索栏中启用模糊搜索。这允许搜索结果包含与搜索查询几乎匹配的条目，以及那些单独字符与搜索查询匹配但不按顺序排列的条目。
请使用 search_bar_fuzzy_search_max_misses 来设置搜索结果中允许的最大不匹配数量。
int search_bar_fuzzy_search_max_misses = 2 🔗
void set_search_bar_fuzzy_search_max_misses(value: int)
int get_search_bar_fuzzy_search_max_misses()
设置为 PopupMenu 的搜索栏启用模糊搜索时，每个搜索结果中允许的最大不匹配数量。任何超过该数量的菜单项都将从搜索结果中被隐藏。
int search_bar_min_item_count = 0 🔗
设置让 PopupMenu（弹出菜单）的搜索栏显示出来所需的最少项目数量。search_bar_enabled 必须为 true，这个设置才会生效。
int get_selected()
当前选定项的索引，如果没有选定项，则为-1。
方法说明
void add_icon_item(texture: Texture2D, label: String, id: int = -1) 🔗
添加一个菜单项，图标为 texture，文本为 label，（可选）ID 为 id。如果没有传入 id，则会将菜单项的索引用作 ID。新菜单项会追加到末尾。
注意：没有其他菜单项时会选中该菜单项。
void add_item(label: String, id: int = -1) 🔗
添加一个菜单项，文本为 label，（可选）ID 为 id。如果没有传入 id，则会将菜单项的索引用作 ID。新菜单项会追加到末尾。
注意：没有其他菜单项时会选中该菜单项。
void add_separator(text: String = "") 🔗
在菜单项列表中添加分隔符。分隔符可以用来对菜单项进行分组，还可以给出标题文本 text。分隔符也设有索引，会追加到菜单项列表的末尾。
void clear() 🔗
清除OptionButton中的所有项目。
AutoTranslateMode get_item_auto_translate_mode(idx: int) const 🔗
返回索引为 idx 的菜单项的自动翻译模式。
Texture2D get_item_icon(idx: int) const 🔗
返回索引为 idx 的菜单项的图标。
int get_item_id(idx: int) const 🔗
返回索引为 idx 的菜单项的 ID。
int get_item_index(id: int) const 🔗
返回具有指定 id 的项目的索引。
Variant get_item_metadata(idx: int) const 🔗
检索项的元数据。元数据可以是任何类型，并可用于存储关于项的额外信息，如外部字符串ID。
String get_item_text(idx: int) const 🔗
返回索引为 idx 的菜单项的文本。
String get_item_tooltip(idx: int) const 🔗
返回索引为 idx 的菜单项的工具提示。
返回这个按钮中包含的 PopupMenu。
警告：这是一个必需的内部节点，移除和释放它可能会导致崩溃。如果你想隐藏它或它的任何子节点，请使用其 Window.visible 属性。
int get_selectable_item(from_last: bool = false) const 🔗
返回第一个处于非禁用状态或被标记为分隔符的菜单项的索引。如果 from_last 为 true，则会逆序搜索菜单项。
如果没有找到则返回 -1。
返回所选项目的 ID，如果没有选择项目，则返回 -1。
Variant get_selected_metadata() const 🔗
获取选定项的元数据。可以使用 set_item_metadata() 设置项的元数据。
bool has_selectable_items() const 🔗
如果这个按钮至少包含一个未禁用或被标记为分隔符的菜单项，则返回 true。
bool is_item_disabled(idx: int) const 🔗
如果索引为 idx 的菜单项被禁用，则返回 true。
bool is_item_separator(idx: int) const 🔗
如果索引为 idx 的菜单项被标记为分隔符，则返回 true。
移除索引为 idx 的菜单项。
按索引选择项并使其为当前选中项。即使该项是禁用的，这也将起作用。
将 -1 作为索引传入会取消选中任何当前选中的项目。
void set_disable_shortcuts(disabled: bool) 🔗
如果为 true，快捷方式将被禁用，无法用于触发按钮。
void set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode) 🔗
设置索引为 idx 的菜单项的自动翻译模式。
菜单项使用 Node.AUTO_TRANSLATE_MODE_INHERIT，表示使用与 OptionButton 相同的自动翻译模式。
void set_item_disabled(idx: int, disabled: bool) 🔗
设置是否禁用索引为 idx 的菜单项。
处于禁用状态的菜单项在下拉列表中绘制的方式不同，用户无法选中这个菜单项。如果将当前选中的菜单项设为了禁用，则仍然会处于选中状态。
void set_item_icon(idx: int, texture: Texture2D) 🔗
设置索引为 idx 的菜单项的图标。
void set_item_id(idx: int, id: int) 🔗
设置索引为 idx 的菜单项的 ID。
void set_item_metadata(idx: int, metadata: Variant) 🔗
设置项的元数据。元数据可以是任何类型，可以用来存储关于项目的额外信息，比如外部字符串ID。
void set_item_text(idx: int, text: String) 🔗
设置索引为 idx 的菜单项的文本。
void set_item_tooltip(idx: int, tooltip: String) 🔗
设置索引为 idx 的菜单项的工具提示。
void show_popup() 🔗
调整 OptionButton 弹出项的位置和大小，然后显示 PopupMenu。请优先使用这个方法，而不是 get_popup().popup()。
主题属性说明
箭头图标和按钮的右边缘之间的水平空间。
如果不为 0，箭头图标会与字体颜色进行调制。
要绘制在按钮右侧的箭头图标。