Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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，将文本光标移动到行尾

属性

HorizontalAlignment

alignment

0

bool

caret_blink

false

float

caret_blink_interval

0.65

int

caret_column

0

bool

caret_force_displayed

false

bool

caret_mid_grapheme

false

bool

clear_button_enabled

false

bool

context_menu_enabled

true

bool

deselect_on_focus_loss_enabled

true

bool

drag_and_drop_selection_enabled

true

bool

draw_control_chars

false

bool

editable

true

bool

expand_to_text_length

false

bool

flat

false

FocusMode

focus_mode

2 (overrides Control)

String

language

""

int

max_length

0

bool

middle_mouse_paste_enabled

true

CursorShape

mouse_default_cursor_shape

1 (overrides Control)

String

placeholder_text

""

Texture2D

right_icon

bool

secret

false

String

secret_character

"•"

bool

select_all_on_focus

false

bool

selecting_enabled

true

bool

shortcut_keys_enabled

true

StructuredTextParser

structured_text_bidi_override

0

Array

structured_text_bidi_override_options

[]

String

text

""

TextDirection

text_direction

0

bool

virtual_keyboard_enabled

true

VirtualKeyboardType

virtual_keyboard_type

0

方法

void

clear ( )

void

delete_char_at_caret ( )

void

delete_text ( int from_column, int to_column )

void

deselect ( )

PopupMenu

get_menu ( ) const

float

get_scroll_offset ( ) const

String

get_selected_text ( )

int

get_selection_from_column ( ) const

int

get_selection_to_column ( ) const

bool

has_selection ( ) const

void

insert_text_at_caret ( String text )

bool

is_menu_visible ( ) const

void

menu_option ( int option )

void

select ( int from=0, int to=-1 )

void

select_all ( )

主题属性

Color

caret_color

Color(0.95, 0.95, 0.95, 1)

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(1, 1, 1, 1)

Color

font_placeholder_color

Color(0.875, 0.875, 0.875, 0.6)

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

int

outline_size

0

Font

font

int

font_size

Texture2D

clear

StyleBox

focus

StyleBox

normal

StyleBox

read_only

信号

text_change_rejected ( String rejected_substring )

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

text_changed ( String new_text )

当文本更改时触发。

text_submitted ( String new_text )

当用户在 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

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

  • void set_caret_blink_enabled ( bool value )

  • bool is_caret_blink_enabled ( )

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

  • void set_caret_blink_interval ( float value )

  • float get_caret_blink_interval ( )

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

int caret_column = 0

  • void set_caret_column ( int value )

  • int get_caret_column ( )

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

bool caret_force_displayed = false

  • void set_caret_force_displayed ( bool value )

  • bool is_caret_force_displayed ( )

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

bool caret_mid_grapheme = false

  • void set_caret_mid_grapheme_enabled ( bool value )

  • bool is_caret_mid_grapheme_enabled ( )

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

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

bool clear_button_enabled = false

  • void set_clear_button_enabled ( bool value )

  • bool is_clear_button_enabled ( )

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

bool context_menu_enabled = true

  • void set_context_menu_enabled ( bool value )

  • bool is_context_menu_enabled ( )

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

bool deselect_on_focus_loss_enabled = true

  • void set_deselect_on_focus_loss_enabled ( bool value )

  • bool is_deselect_on_focus_loss_enabled ( )

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

bool drag_and_drop_selection_enabled = true

  • void set_drag_and_drop_selection_enabled ( bool value )

  • bool is_drag_and_drop_selection_enabled ( )

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

bool draw_control_chars = false

  • void set_draw_control_chars ( bool value )

  • bool get_draw_control_chars ( )

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

bool editable = true

  • void set_editable ( bool value )

  • bool is_editable ( )

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

bool expand_to_text_length = false

  • void set_expand_to_text_length_enabled ( bool value )

  • bool is_expand_to_text_length_enabled ( )

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

bool flat = false

  • void set_flat ( bool value )

  • bool is_flat ( )

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

String language = ""

  • void set_language ( String value )

  • String get_language ( )

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

int max_length = 0

  • void set_max_length ( int value )

  • int get_max_length ( )

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

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

示例：

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

bool middle_mouse_paste_enabled = true

  • void set_middle_mouse_paste_enabled ( bool value )

  • bool is_middle_mouse_paste_enabled ( )

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

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

String placeholder_text = ""

  • void set_placeholder ( String value )

  • String get_placeholder ( )

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

Texture2D right_icon

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

bool secret = false

  • void set_secret ( bool value )

  • bool is_secret ( )

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

String secret_character = "•"

  • void set_secret_character ( String value )

  • String get_secret_character ( )

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

bool select_all_on_focus = false

  • void set_select_all_on_focus ( bool value )

  • bool is_select_all_on_focus ( )

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

bool selecting_enabled = true

  • void set_selecting_enabled ( bool value )

  • bool is_selecting_enabled ( )

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

bool shortcut_keys_enabled = true

  • void set_shortcut_keys_enabled ( bool value )

  • bool is_shortcut_keys_enabled ( )

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

StructuredTextParser structured_text_bidi_override = 0

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

Array structured_text_bidi_override_options = []

  • void set_structured_text_bidi_override_options ( Array value )

  • Array get_structured_text_bidi_override_options ( )

设置 BiDi 覆盖的附加选项。

String text = ""

LineEdit 的字符串值。

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

TextDirection text_direction = 0

基础文本书写方向。

bool virtual_keyboard_enabled = true

  • void set_virtual_keyboard_enabled ( bool value )

  • bool is_virtual_keyboard_enabled ( )

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

VirtualKeyboardType virtual_keyboard_type = 0

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

方法说明

void clear ( )

擦除 LineEdit 的 text。

void delete_char_at_caret ( )

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

void delete_text ( int from_column, int to_column )

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

void deselect ( )

清除当前选择。

PopupMenu get_menu ( ) const

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

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

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())

警告：这是一个必需的内部节点，移除和释放它可能会导致崩溃。如果希望隐藏它或它的任何子节点，请使用它们的 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 ( String text )

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

bool is_menu_visible ( ) const

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

void menu_option ( int option )

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

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

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

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,