LineEdit

继承： Control < CanvasItem < Node < Object

单行文本的输入字段。

描述

LineEdit 提供了一个单行文本的输入字段，提供了许多始终可用的内置快捷键（此处的 Ctrl 在 macOS 上会映射到 Cmd）：

• Ctrl + C：复制

• Ctrl + X：剪切

• Ctrl + V 或 Ctrl + Y：粘贴/“拉扯”n

• Ctrl + Z：撤销

• Ctrl + ~：交换输入方向

• Ctrl + Shift + Z：重做

• Ctrl + U：删除从文本光标位置到行首的文本

• Ctrl + K：删除从文本光标位置到行尾的文本

• Ctrl + A：选择所有文本

• Up Arrow/Down Arrow：将文本光标移动到行首/行尾

在 macOS 上，有一些额外的键盘快捷键可用：

• Ctrl + F：同 Right Arrow，将文本光标向右移动一个字符

• Ctrl + B：同 Left Arrow，将文本光标向左移动一个字符

• Ctrl + P：同 Up Arrow，将文本光标移动到上一行

• Ctrl + N：同 Down Arrow，将文本光标移动到下一行

• Ctrl + D：同 Delete，删除文本光标右侧的字符

• Ctrl + H：同 Backspace，删除文本光标左侧的字符

• Ctrl + A：同 Home，将文本光标移动到行首

• Ctrl + E：同 End，将文本光标移动到行首尾

• Cmd + Left Arrow：同 Home，将文本光标移动到行首

• Cmd + Right Arrow：同 End，将文本光标移动到行尾

属性

方法

主题属性

信号

text_change_rejected(rejected_substring: String) 🔗

当追加的文本超过了 max_length 时触发。追加后的文本会被截断以适应 max_length，超出的部分会被作为 rejected_substring 参数传递。

text_changed(new_text: String) 🔗

当文本更改时触发。

text_submitted(new_text: String) 🔗

当用户在 LineEdit 上按 @GlobalScope.KEY_ENTER 时触发。

枚举

enum MenuItems: 🔗

MenuItems MENU_CUT = 0

剪切（复制并删除）选中的文本。

MenuItems MENU_COPY = 1

复制选中的文本。

MenuItems MENU_PASTE = 2

将剪贴板中的文本粘贴到选中文本之上（或者文本光标位置）。

会使用 String.strip_escapes 自动剥离操作系统剪贴板中不可打印的转义字符。

MenuItems MENU_CLEAR = 3

删除 LineEdit 中的全部文本。

MenuItems MENU_SELECT_ALL = 4

选中 LineEdit 中的全部文本。

MenuItems MENU_UNDO = 5

撤销之前的操作。

MenuItems MENU_REDO = 6

反转最后一个撤销动作。

MenuItems MENU_SUBMENU_TEXT_DIR = 7

“文本书写方向”子菜单的 ID。

MenuItems MENU_DIR_INHERITED = 8

将文本方向设置为继承。

MenuItems MENU_DIR_AUTO = 9

将文本方向设置为自动。

MenuItems MENU_DIR_LTR = 10

将文本方向设置为从左至右。

MenuItems MENU_DIR_RTL = 11

将文本方向设置为从右至左。

MenuItems MENU_DISPLAY_UCC = 12

切换控制字符的显示。

MenuItems MENU_SUBMENU_INSERT_UCC = 13

“插入控制字符”子菜单的 ID。

MenuItems MENU_INSERT_LRM = 14

插入从左至右标志（LRM）字符。

MenuItems MENU_INSERT_RLM = 15

插入从右至左标志（LRM）字符。

MenuItems MENU_INSERT_LRE = 16

插入开始从左至右嵌入（LRE）字符。

MenuItems MENU_INSERT_RLE = 17

插入开始从右至左嵌入（RLE）字符。

MenuItems MENU_INSERT_LRO = 18

插入开始从左至右强制（LRO）字符。

MenuItems MENU_INSERT_RLO = 19

插入开始从右至左嵌入（RLE）字符。

MenuItems MENU_INSERT_PDF = 20

插入退出方向格式化（PDF）字符。

MenuItems MENU_INSERT_ALM = 21

插入阿拉伯字母标记（ALM）字符。

MenuItems MENU_INSERT_LRI = 22

插入从左至右隔离（LRI）字符。

MenuItems MENU_INSERT_RLI = 23

插入从右至左隔离（RLI）字符。

MenuItems MENU_INSERT_FSI = 24

插入第一个强隔离（FSI）字符。

MenuItems MENU_INSERT_PDI = 25

插入退出方向隔离（PDI）字符。

MenuItems MENU_INSERT_ZWJ = 26

插入零宽连接符（ZWJ）字符。

MenuItems MENU_INSERT_ZWNJ = 27

插入零宽非连接符（ZWNJ）字符。

MenuItems MENU_INSERT_WJ = 28

插入文字连接符（WJ）字符。

MenuItems MENU_INSERT_SHY = 29

插入软连字符（SHY）字符。

MenuItems MENU_MAX = 30

代表 MenuItems 枚举的大小。

enum VirtualKeyboardType: 🔗

VirtualKeyboardType KEYBOARD_TYPE_DEFAULT = 0

默认文本虚拟键盘。

VirtualKeyboardType KEYBOARD_TYPE_MULTILINE = 1

多行虚拟键盘。

VirtualKeyboardType KEYBOARD_TYPE_NUMBER = 2

虚拟数字键盘，可用于 PIN 输入。

VirtualKeyboardType KEYBOARD_TYPE_NUMBER_DECIMAL = 3

虚拟数字键盘，可用于输入小数。

VirtualKeyboardType KEYBOARD_TYPE_PHONE = 4

虚拟手机号码键盘。

VirtualKeyboardType KEYBOARD_TYPE_EMAIL_ADDRESS = 5

带有附加键的虚拟键盘，可帮助输入电子邮件地址。

VirtualKeyboardType KEYBOARD_TYPE_PASSWORD = 6

用于输入密码的虚拟键盘。在大多数平台上，这应该会禁用自动完成和自动首字母大写功能。

注意：Web 平台不支持。与 KEYBOARD_TYPE_DEFAULT 的行为相同。

VirtualKeyboardType KEYBOARD_TYPE_URL = 7

带有附加键的虚拟键盘，可帮助输入 URL。

属性说明

HorizontalAlignment alignment = 0 🔗

• void set_horizontal_alignment(value: HorizontalAlignment)

• HorizontalAlignment get_horizontal_alignment()

文本对齐方式，由 HorizontalAlignment 枚举定义。

bool caret_blink = false 🔗

• void set_caret_blink_enabled(value: bool)

• bool is_caret_blink_enabled()

如果为 true，则文本光标会闪烁。

float caret_blink_interval = 0.65 🔗

• void set_caret_blink_interval(value: float)

• float get_caret_blink_interval()

文本光标的闪烁间隔（单位为秒）。

int caret_column = 0 🔗

• void set_caret_column(value: int)

• int get_caret_column()

LineEdit 中光标的列位置。设置后文本可能会滚动以适应它。

bool caret_force_displayed = false 🔗

• void set_caret_force_displayed(value: bool)

• bool is_caret_force_displayed()

如果为 true，则该 LineEdit 会始终显示光标，即使焦点丢失。

bool caret_mid_grapheme = false 🔗

• void set_caret_mid_grapheme_enabled(value: bool)

• bool is_caret_mid_grapheme_enabled()

允许在单个复合字符的组件中进行移动光标、选中、删除的操作。

注意：退格键 Backspace 始终按复合字符的组件删除。

bool clear_button_enabled = false 🔗

• void set_clear_button_enabled(value: bool)

• bool is_clear_button_enabled()

如果为 true，LineEdit 将在 text 非空时显示清空按钮，可以用来快速清除文本。

bool context_menu_enabled = true 🔗

• void set_context_menu_enabled(value: bool)

• bool is_context_menu_enabled()

如果为 true，右键单击将出现上下文菜单。

bool deselect_on_focus_loss_enabled = true 🔗

• void set_deselect_on_focus_loss_enabled(value: bool)

• bool is_deselect_on_focus_loss_enabled()

如果为 true，则在丢失焦点时会取消选中文本。

bool drag_and_drop_selection_enabled = true 🔗

• void set_drag_and_drop_selection_enabled(value: bool)

• bool is_drag_and_drop_selection_enabled()

如果为 true，则允许拖放选中的文本。

bool draw_control_chars = false 🔗

• void set_draw_control_chars(value: bool)

• bool get_draw_control_chars()

如果为 true，则会显示控制字符。

bool editable = true 🔗

• void set_editable(value: bool)

• bool is_editable()

如果为 false，则不能修改现在的文本，也不能添加新文本。

bool expand_to_text_length = false 🔗

• void set_expand_to_text_length_enabled(value: bool)

• bool is_expand_to_text_length_enabled()

如果为 true，则 LineEdit 宽度将增加到比 text 长。如果 text 被缩短，它将不压缩。

bool flat = false 🔗

• void set_flat(value: bool)

• bool is_flat()

如果为 true，则 LineEdit 不显示装饰。

String language = "" 🔗

• void set_language(value: String)

• String get_language()

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

int max_length = 0 🔗

• void set_max_length(value: int)

• int get_max_length()

LineEdit 中可以输入的最大字符数。如果为 0，则没有限制。

定义限制后，将截断超过 max_length 的字符。在设置最大长度时，将适用于现有的 text 内容，以及在 LineEdit 中插入、包括粘贴进来的新文本。如果任何输入文本被截断，text_change_rejected 信号将以截断的子字符串作为参数发出。

示例：

GDScriptC#

text = "Hello world"
max_length = 5
# `text` 变为 "Hello"。
max_length = 10
text += " goodbye"
# `text` 变为 "Hello good"。
# `text_change_rejected` 以 "bye" 作为参数发出。

Text = "Hello world";
MaxLength = 5;
// `Text` 变为 "Hello"。
MaxLength = 10;
Text += " goodbye";
// `text` 变为 "Hello good"。
// `text_change_rejected` 以 "bye" 作为参数发出。

bool middle_mouse_paste_enabled = true 🔗

• void set_middle_mouse_paste_enabled(value: bool)

• bool is_middle_mouse_paste_enabled()

如果为 false，将禁用鼠标中键粘贴剪贴板。

注意：这个方法只在 Linux 上实现。

String placeholder_text = "" 🔗

• void set_placeholder(value: String)

• String get_placeholder()

当 LineEdit 为空时显示的文本。它不是 LineEdit 的默认值（见 text）。

Texture2D right_icon 🔗

• void set_right_icon(value: Texture2D)

• Texture2D get_right_icon()

设置 LineEdit 右端的图标，这个图标会在没有 text 时出现，如果 clear_button_enabled 为 false 则始终可见。

bool secret = false 🔗

• void set_secret(value: bool)

• bool is_secret()

如果为 true，则每个字符都会被替换成密码字符（见 secret_character）。

String secret_character = "•" 🔗

• void set_secret_character(value: String)

• String get_secret_character()

用于掩盖秘密输入的字符。只能用单个字符作为秘密字符。如果长度超过一个字符，则仅使用第一个字符。如果为空，则使用空格代替。

bool select_all_on_focus = false 🔗

• void set_select_all_on_focus(value: bool)

• bool is_select_all_on_focus()

如果为 true，则在获得焦点时会全选文本。

bool selecting_enabled = true 🔗

• void set_selecting_enabled(value: bool)

• bool is_selecting_enabled()

如果为 false，则无法用鼠标或键盘选择文本。

bool shortcut_keys_enabled = true 🔗

• void set_shortcut_keys_enabled(value: bool)

• bool is_shortcut_keys_enabled()

如果为 false，快捷键将被禁用。

StructuredTextParser structured_text_bidi_override = 0 🔗

• void set_structured_text_bidi_override(value: StructuredTextParser)

• StructuredTextParser get_structured_text_bidi_override()

为结构化文本设置 BiDi 算法覆盖。

Array structured_text_bidi_override_options = [] 🔗

• void set_structured_text_bidi_override_options(value: Array)

• Array get_structured_text_bidi_override_options()

设置 BiDi 覆盖的附加选项。

String text = "" 🔗

• void set_text(value: String)

• String get_text()

LineEdit 的字符串值。

注意：使用这个属性更改文本不会触发 text_changed 信号。

TextDirection text_direction = 0 🔗

• void set_text_direction(value: TextDirection)

• TextDirection get_text_direction()

基础文本书写方向。

bool virtual_keyboard_enabled = true 🔗

• void set_virtual_keyboard_enabled(value: bool)

• bool is_virtual_keyboard_enabled()

如果为 true，则在获得焦点时会在支持的平台上显示原生虚拟键盘。

VirtualKeyboardType virtual_keyboard_type = 0 🔗

• void set_virtual_keyboard_type(value: VirtualKeyboardType)

• VirtualKeyboardType get_virtual_keyboard_type()

指定要显示的虚拟键盘的类型。

方法说明

void clear() 🔗

擦除 LineEdit 的 text。

void delete_char_at_caret() 🔗

删除光标当前位置处的一个字符（相当于按 Delete）。

void delete_text(from_column: int, to_column: int) 🔗

删除 text 中从起始列 from_column 到结束列 to_column 的部分。两个参数都应该在文本的长度之内。

void deselect() 🔗

清除当前选择。

PopupMenu get_menu() const 🔗

返回该 LineEdit 的 PopupMenu。默认情况下，右键点击 LineEdit 会显示该菜单。

可以添加自定义菜单项或移除标准菜单项。确保你的 ID 不与标准 ID 冲突（请参阅 MenuItems）。例如：

GDScriptC#

func _ready():
    var menu = get_menu()
    # 在“重做”之后移除所有项目。
    menu.item_count = menu.get_item_index(MENU_REDO) + 1
    # 添加自定义项目。
    menu.add_separator()
    menu.add_item("Insert Date", MENU_MAX + 1)
    # 连接回调。
    menu.id_pressed.connect(_on_item_pressed)
func _on_item_pressed(id):
    if id == MENU_MAX + 1:
        insert_text_at_caret(Time.get_date_string_from_system())

public override void _Ready()
{
    var menu = GetMenu();
    // 在“重做”之后移除所有项目。
    menu.ItemCount = menu.GetItemIndex(LineEdit.MenuItems.Redo) + 1;
    // 添加自定义项目。
    menu.AddSeparator();
    menu.AddItem("Insert Date", LineEdit.MenuItems.Max + 1);
    // 添加事件处理器。
    menu.IdPressed += OnItemPressed;
}
public void OnItemPressed(int id)
{
    if (id == LineEdit.MenuItems.Max + 1)
    {
        InsertTextAtCaret(Time.GetDateStringFromSystem());
    }
}

警告：这是一个必需的内部节点，移除和释放它可能会导致崩溃。如果希望隐藏它或它的任何子节点，请使用它们的 Window.visible 属性。

float get_scroll_offset() const 🔗

返回 caret_column 引起的滚动偏移量，单位为字符数。

String get_selected_text() 🔗

返回选择内的文本。

int get_selection_from_column() const 🔗

返回选择的开始列。

int get_selection_to_column() const 🔗

返回选择结束列。

bool has_selection() const 🔗

如果用户选中了文本，则返回 true。

void insert_text_at_caret(text: String) 🔗

在光标处插入文本 text。如果最终值比 max_length 长，则不会发生任何事情。

bool is_menu_visible() const 🔗

返回菜单是否可见。请使用这个方法来代替 get_menu().visible，可以提高性能（因为避免了菜单的创建）。

void menu_option(option: int) 🔗

执行 MenuItems 枚举中定义的给定操作。

void select(from: int = 0, to: int = -1) 🔗

选择 LineEdit 内介于 from 和 to 之间的字符。默认情况下，from 位于开头，to 位于结尾。

GDScriptC#

text = "Welcome"
select() # 将选择“Welcome”。
select(4) # 将选择“ome”。
select(2, 5) # 将选择“lco”。

Text = "Welcome";
Select(); // 将选择“Welcome”。
Select(4); // 将选择“ome”。
Select(2, 5); // 将选择“lco”。

void select_all() 🔗

选中整个 String。

主题属性说明

Color caret_color = Color(0.95, 0.95, 0.95, 1) 🔗

LineEdit 的插入符号（文本光标）的颜色。可以设置为完全透明的颜色，从而完全隐藏光标。

Color clear_button_color = Color(0.875, 0.875, 0.875, 1) 🔗

用作清除按钮默认色调的颜色。

Color clear_button_color_pressed = Color(1, 1, 1, 1) 🔗

按下清除按钮时使用的颜色。

Color font_color = Color(0.875, 0.875, 0.875, 1) 🔗

默认字体颜色。

Color font_outline_color = Color(0, 0, 0, 1) 🔗

LineEdit 文本轮廓的色调。

Color font_placeholder_color = Color(0.875, 0.875, 0.875, 0.6) 🔗

placeholder_text 的字体颜色。

Color font_selected_color = Color(1, 1, 1, 1) 🔗

选定文本的字体颜色（在选择矩形内）。

Color font_uneditable_color = Color(0.875, 0.875, 0.875, 0.5) 🔗

禁用编辑时的字体颜色。

Color selection_color = Color(0.5, 0.5, 0.5, 1) 🔗

选择矩形的颜色。

int caret_width = 1 🔗

文本光标的像素宽度。使用较大的数值可以提高可访问性，使文本光标更加显眼，或者确保文本与较大字体尺寸的一致性。

int minimum_character_width = 4 🔗

文本的最小水平空间（不包括清除按钮和内容边距）。这个值以“M”字符的数量来衡量（即能够在不滚动的情况下显示这么多个“M”字符）。

int outline_size = 0 🔗

文字轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

Font font 🔗

文本使用的字体。

int font_size 🔗

该 LineEdit 文本的字体大小。

Texture2D clear 🔗

“清除”按钮的纹理。见 clear_button_enabled。

StyleBox focus 🔗

LineEdit 拥有 GUI 焦点时使用的背景。focus StyleBox 显示在基础 StyleBox 之上，所以应该使用部分透明的 StyleBox，确保基础 StyleBox 仍然可见。代表轮廓或下划线的 StyleBox 可以很好地实现这个目的。要禁用聚焦的视觉效果，请指定 StyleBoxEmpty 资源。请注意，禁用聚焦的视觉效果会影响使用键盘/手柄进行导航的可用性，所以出于可访问性的原因，不建议这样做。

StyleBox normal 🔗

该 LineEdit 的默认背景。

StyleBox read_only 🔗

该 LineEdit 处于只读模式时使用的背景（editable 为 false）。