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

如果为 trueLineEdit 将在 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_enabledfalse 则始终可见。


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

擦除 LineEdittext


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

返回该 LineEditPopupMenu。默认情况下,右键点击 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 内介于 fromto 之间的字符。默认情况下,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, 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)

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 处于只读模式时使用的背景(editablefalse)。