:github_url: hide .. meta:: :keywords: select, dropdown .. _class_OptionButton: OptionButton ============ **继承：** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` 按下时弹出下拉菜单的按钮。 .. rst-class:: classref-introduction-group 描述 ---- **OptionButton** 是一种按下时弹出下拉菜单的按钮。选中的菜单项会成为“当前”菜单项，作为按钮文本显示。 另见 :ref:`BaseButton`\ ，其中包含与此节点相关联的通用属性和方法。 \ **注意：**\ 菜单项的 ID 限制为带符号 32 位整数，并不是完整的 64 位 :ref:`int`\ 。取值范围为 ``-2^31`` 到 ``2^31 - 1``\ ，即 ``-2147483648`` 到 ``2147483647``\ 。 \ **注意：**\ :ref:`Button.text` 和 :ref:`Button.icon` 属性会根据当前所选菜单项自动设置。不应该手动更改。 .. rst-class:: classref-reftable-group 属性 ---- .. table:: :widths: auto +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`ActionMode` | action_mode | ``0`` (overrides :ref:`BaseButton`) | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`HorizontalAlignment` | alignment | ``0`` (overrides :ref:`Button`) | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`allow_reselect` | ``false`` | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`fit_to_longest_item` | ``true`` | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`int` | :ref:`item_count` | ``0`` | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`int` | :ref:`selected` | ``-1`` | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | +-------------------------------------------------------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_icon_item`\ (\ texture\: :ref:`Texture2D`, label\: :ref:`String`, id\: :ref:`int` = -1\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_item`\ (\ label\: :ref:`String`, id\: :ref:`int` = -1\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_separator`\ (\ text\: :ref:`String` = ""\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`clear`\ (\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AutoTranslateMode` | :ref:`get_item_auto_translate_mode`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Texture2D` | :ref:`get_item_icon`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_item_id`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_item_index`\ (\ id\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_item_metadata`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_item_text`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_item_tooltip`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PopupMenu` | :ref:`get_popup`\ (\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_selectable_item`\ (\ from_last\: :ref:`bool` = false\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_selected_id`\ (\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_selected_metadata`\ (\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_selectable_items`\ (\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_disabled`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_separator`\ (\ idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_item`\ (\ idx\: :ref:`int`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`select`\ (\ idx\: :ref:`int`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_disable_shortcuts`\ (\ disabled\: :ref:`bool`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_auto_translate_mode`\ (\ idx\: :ref:`int`, mode\: :ref:`AutoTranslateMode`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_disabled`\ (\ idx\: :ref:`int`, disabled\: :ref:`bool`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_icon`\ (\ idx\: :ref:`int`, texture\: :ref:`Texture2D`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_id`\ (\ idx\: :ref:`int`, id\: :ref:`int`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_metadata`\ (\ idx\: :ref:`int`, metadata\: :ref:`Variant`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_text`\ (\ idx\: :ref:`int`, text\: :ref:`String`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_item_tooltip`\ (\ idx\: :ref:`int`, tooltip\: :ref:`String`\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`show_popup`\ (\ ) | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group 主题属性 -------- .. table:: :widths: auto +-----------------------------------+-------------------------------------------------------------------------+-------+ | :ref:`int` | :ref:`arrow_margin` | ``4`` | +-----------------------------------+-------------------------------------------------------------------------+-------+ | :ref:`int` | :ref:`modulate_arrow` | ``0`` | +-----------------------------------+-------------------------------------------------------------------------+-------+ | :ref:`Texture2D` | :ref:`arrow` | | +-----------------------------------+-------------------------------------------------------------------------+-------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 信号 ---- .. _class_OptionButton_signal_item_focused: .. rst-class:: classref-signal **item_focused**\ (\ index\: :ref:`int`\ ) :ref:`🔗` 当用户使用 :ref:`ProjectSettings.input/ui_up` 或 :ref:`ProjectSettings.input/ui_down` 输入动作导航到某个项目时发出。所选项目的索引将作为参数传递。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_signal_item_selected: .. rst-class:: classref-signal **item_selected**\ (\ index\: :ref:`int`\ ) :ref:`🔗` 当用户更改当前项时触发。所选项目的索引作为参数传递。 必须启用 :ref:`allow_reselect` 才能重新选中项目。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 属性说明 -------- .. _class_OptionButton_property_allow_reselect: .. rst-class:: classref-property :ref:`bool` **allow_reselect** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_allow_reselect**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_allow_reselect**\ (\ ) 如果为 ``true``\ ，则可以再次选择当前选中的项目。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_property_fit_to_longest_item: .. rst-class:: classref-property :ref:`bool` **fit_to_longest_item** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_fit_to_longest_item**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_fit_to_longest_item**\ (\ ) 如果为 ``true``\ ，最小尺寸将由最长项目的文本确定，而不是当前选定的文本。 \ **注意：**\ 出于性能原因，在添加、移除或修改项目时，最小尺寸不会立即更新。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_property_item_count: .. rst-class:: classref-property :ref:`int` **item_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_item_count**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_item_count**\ (\ ) 可供挑选的菜单项的数量。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_property_selected: .. rst-class:: classref-property :ref:`int` **selected** = ``-1`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`int` **get_selected**\ (\ ) 当前选定项的索引，如果没有选定项，则为\ ``-1``\ 。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法说明 -------- .. _class_OptionButton_method_add_icon_item: .. rst-class:: classref-method |void| **add_icon_item**\ (\ texture\: :ref:`Texture2D`, label\: :ref:`String`, id\: :ref:`int` = -1\ ) :ref:`🔗` 添加一个菜单项，图标为 ``texture``\ ，文本为 ``label``\ ，（可选）ID 为 ``id``\ 。如果没有传入 ``id``\ ，则会将菜单项的索引用作 ID。新菜单项会追加到末尾。 \ **注意：**\ 没有其他菜单项时会选中该菜单项。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_add_item: .. rst-class:: classref-method |void| **add_item**\ (\ label\: :ref:`String`, id\: :ref:`int` = -1\ ) :ref:`🔗` 添加一个菜单项，文本为 ``label``\ ，（可选）ID 为 ``id``\ 。如果没有传入 ``id``\ ，则会将菜单项的索引用作 ID。新菜单项会追加到末尾。 \ **注意：**\ 没有其他菜单项时会选中该菜单项。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_add_separator: .. rst-class:: classref-method |void| **add_separator**\ (\ text\: :ref:`String` = ""\ ) :ref:`🔗` 在菜单项列表中添加分隔符。分隔符可以用来对菜单项进行分组，还可以给出标题文本 ``text``\ 。分隔符也设有索引，会追加到菜单项列表的末尾。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_clear: .. rst-class:: classref-method |void| **clear**\ (\ ) :ref:`🔗` 清除\ **OptionButton**\ 中的所有项目。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_auto_translate_mode: .. rst-class:: classref-method :ref:`AutoTranslateMode` **get_item_auto_translate_mode**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 返回索引为 ``idx`` 的菜单项的自动翻译模式。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_icon: .. rst-class:: classref-method :ref:`Texture2D` **get_item_icon**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 返回索引为 ``idx`` 的菜单项的图标。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_id: .. rst-class:: classref-method :ref:`int` **get_item_id**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 返回索引为 ``idx`` 的菜单项的 ID。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_index: .. rst-class:: classref-method :ref:`int` **get_item_index**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` 返回 ID 为 ``id`` 的菜单项的索引。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_metadata: .. rst-class:: classref-method :ref:`Variant` **get_item_metadata**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 检索项的元数据。元数据可以是任何类型，并可用于存储关于项的额外信息，如外部字符串ID。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_text: .. rst-class:: classref-method :ref:`String` **get_item_text**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 返回索引为 ``idx`` 的菜单项的文本。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_item_tooltip: .. rst-class:: classref-method :ref:`String` **get_item_tooltip**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 返回索引为 ``idx`` 的菜单项的工具提示。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_popup: .. rst-class:: classref-method :ref:`PopupMenu` **get_popup**\ (\ ) |const| :ref:`🔗` 返回这个按钮中包含的 :ref:`PopupMenu`\ 。 \ **警告：**\ 这是一个必需的内部节点，移除和释放它可能会导致崩溃。如果你想隐藏它或它的任何子节点，请使用其 :ref:`Window.visible` 属性。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_selectable_item: .. rst-class:: classref-method :ref:`int` **get_selectable_item**\ (\ from_last\: :ref:`bool` = false\ ) |const| :ref:`🔗` 返回第一个处于非禁用状态或被标记为分隔符的菜单项的索引。如果 ``from_last`` 为 ``true``\ ，则会逆序搜索菜单项。 如果没有找到则返回 ``-1``\ 。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_selected_id: .. rst-class:: classref-method :ref:`int` **get_selected_id**\ (\ ) |const| :ref:`🔗` 返回所选项目的 ID，如果没有选择项目，则返回 ``-1``\ 。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_get_selected_metadata: .. rst-class:: classref-method :ref:`Variant` **get_selected_metadata**\ (\ ) |const| :ref:`🔗` 获取选定项的元数据。可以使用 :ref:`set_item_metadata()` 设置项的元数据。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_has_selectable_items: .. rst-class:: classref-method :ref:`bool` **has_selectable_items**\ (\ ) |const| :ref:`🔗` 如果这个按钮至少包含一个未禁用或被标记为分隔符的菜单项，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_is_item_disabled: .. rst-class:: classref-method :ref:`bool` **is_item_disabled**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 如果索引为 ``idx`` 的菜单项被禁用，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_is_item_separator: .. rst-class:: classref-method :ref:`bool` **is_item_separator**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` 如果索引为 ``idx`` 的菜单项被标记为分隔符，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_remove_item: .. rst-class:: classref-method |void| **remove_item**\ (\ idx\: :ref:`int`\ ) :ref:`🔗` 移除索引为 ``idx`` 的菜单项。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_select: .. rst-class:: classref-method |void| **select**\ (\ idx\: :ref:`int`\ ) :ref:`🔗` 按索引选择项并使其为当前选中项。即使该项是禁用的，这也将起作用。 将 ``-1`` 作为索引传入会取消选中任何当前选中的项目。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_disable_shortcuts: .. rst-class:: classref-method |void| **set_disable_shortcuts**\ (\ disabled\: :ref:`bool`\ ) :ref:`🔗` 如果为 ``true``\ ，快捷方式将被禁用，无法用于触发按钮。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_auto_translate_mode: .. rst-class:: classref-method |void| **set_item_auto_translate_mode**\ (\ idx\: :ref:`int`, mode\: :ref:`AutoTranslateMode`\ ) :ref:`🔗` 设置索引为 ``idx`` 的菜单项的自动翻译模式。 菜单项使用 :ref:`Node.AUTO_TRANSLATE_MODE_INHERIT`\ ，表示使用与 **OptionButton** 相同的自动翻译模式。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_disabled: .. rst-class:: classref-method |void| **set_item_disabled**\ (\ idx\: :ref:`int`, disabled\: :ref:`bool`\ ) :ref:`🔗` 设置是否禁用索引为 ``idx`` 的菜单项。 处于禁用状态的菜单项在下拉列表中绘制的方式不同，用户无法选中这个菜单项。如果将当前选中的菜单项设为了禁用，则仍然会处于选中状态。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_icon: .. rst-class:: classref-method |void| **set_item_icon**\ (\ idx\: :ref:`int`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` 设置索引为 ``idx`` 的菜单项的图标。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_id: .. rst-class:: classref-method |void| **set_item_id**\ (\ idx\: :ref:`int`, id\: :ref:`int`\ ) :ref:`🔗` 设置索引为 ``idx`` 的菜单项的 ID。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_metadata: .. rst-class:: classref-method |void| **set_item_metadata**\ (\ idx\: :ref:`int`, metadata\: :ref:`Variant`\ ) :ref:`🔗` 设置项的元数据。元数据可以是任何类型，可以用来存储关于项目的额外信息，比如外部字符串ID。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_text: .. rst-class:: classref-method |void| **set_item_text**\ (\ idx\: :ref:`int`, text\: :ref:`String`\ ) :ref:`🔗` 设置索引为 ``idx`` 的菜单项的文本。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_set_item_tooltip: .. rst-class:: classref-method |void| **set_item_tooltip**\ (\ idx\: :ref:`int`, tooltip\: :ref:`String`\ ) :ref:`🔗` 设置索引为 ``idx`` 的菜单项的工具提示。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_method_show_popup: .. rst-class:: classref-method |void| **show_popup**\ (\ ) :ref:`🔗` 调整 **OptionButton** 弹出项的位置和大小，然后显示 :ref:`PopupMenu`\ 。请优先使用这个方法，而不是 ``get_popup().popup()``\ 。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 主题属性说明 ------------ .. _class_OptionButton_theme_constant_arrow_margin: .. rst-class:: classref-themeproperty :ref:`int` **arrow_margin** = ``4`` :ref:`🔗` 箭头图标和按钮的右边缘之间的水平空间。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_theme_constant_modulate_arrow: .. rst-class:: classref-themeproperty :ref:`int` **modulate_arrow** = ``0`` :ref:`🔗` 如果不为 ``0``\ ，箭头图标会与字体颜色进行调制。 .. rst-class:: classref-item-separator ---- .. _class_OptionButton_theme_icon_arrow: .. rst-class:: classref-themeproperty :ref:`Texture2D` **arrow** :ref:`🔗` 要绘制在按钮右侧的箭头图标。 .. |virtual| replace:: :abbr:`virtual (本方法通常需要用户覆盖才能生效。)` .. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |const| replace:: :abbr:`const (本方法无副作用，不会修改该实例的任何成员变量。)` .. |vararg| replace:: :abbr:`vararg (本方法除了能接受在此处描述的参数外，还能够继续接受任意数量的参数。)` .. |constructor| replace:: :abbr:`constructor (本方法用于构造某个类型。)` .. |static| replace:: :abbr:`static (调用本方法无需实例，可直接使用类名进行调用。)` .. |operator| replace:: :abbr:`operator (本方法描述的是使用本类型作为左操作数的有效运算符。)` .. |bitfield| replace:: :abbr:`BitField (这个值是由下列位标志构成位掩码的整数。)` .. |void| replace:: :abbr:`void (无返回值。)`