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...
LineEdit
继承： Control < CanvasItem < Node < Object
单行文本的输入字段。
描述
LineEdit 提供了用于编辑单行文本的输入框。
通过键盘方向键聚焦 LineEdit 时只会获得焦点，不会进入编辑模式。
要进入编辑模式，请使用鼠标点击控件，另见 keep_editing_on_text_submit。
要退出编辑模式，请点击
ui_text_submit或ui_cancel（默认为 Escape）动作。
重要：
通过
ui_focus_next（默认为 Tab）、ui_focus_prev（默认为 Shift + Tab）或 Control.grab_focus() 聚焦 LineEdit 仍然会进入编辑模式（出于兼容考虑）。
LineEdit 提供了很多始终可用的内置快捷键（此处的 Ctrl 在 macOS 上会映射到 Cmd）：
Ctrl + C：复制
Ctrl + X：剪切
Ctrl + V 或 Ctrl + Y：复制/“抽取”
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，将文本光标移动到行尾
注意：上述光标移动快捷键不受 shortcut_keys_enabled 的影响。
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
focus_mode |
|
|
|
||
|
||
|
||
|
||
mouse_default_cursor_shape |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
void |
|
void |
|
void |
clear() |
void |
|
void |
delete_text(from_column: int, to_column: int) |
void |
deselect() |
void |
edit() |
get_menu() const |
|
get_scroll_offset() const |
|
get_selection_from_column() const |
|
get_selection_to_column() const |
|
has_ime_text() const |
|
has_redo() const |
|
has_selection() const |
|
has_undo() const |
|
void |
insert_text_at_caret(text: String) |
is_editing() const |
|
is_menu_visible() const |
|
void |
menu_option(option: int) |
void |
|
void |
|
void |
unedit() |
主题属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
信号
editing_toggled(toggled_on: bool) 🔗
LineEdit 进入退出编辑模式时发出。
text_change_rejected(rejected_substring: String) 🔗
当追加的文本超过了 max_length 时触发。追加后的文本会被截断以适应 max_length，超出的部分会被作为 rejected_substring 参数传递。
text_changed(new_text: String) 🔗
当文本更改时触发。
text_submitted(new_text: String) 🔗
当 LineEdit 拥有焦点时，用户按下 ui_text_submit 动作（默认为 Enter 或 Kp Enter）发出。
枚举
剪切（复制并删除）选中的文本。
复制选中的文本。
将剪贴板中的文本粘贴到选中文本之上（或者文本光标位置）。
会使用 String.strip_escapes() 自动剥离操作系统剪贴板中不可打印的转义字符。
删除 LineEdit 中的全部文本。
选中 LineEdit 中的全部文本。
撤销之前的操作。
反转最后一个撤销动作。
“文本书写方向”子菜单的 ID。
将文本方向设置为继承。
将文本方向设置为自动。
将文本方向设置为从左至右。
将文本方向设置为从右至左。
切换控制字符的显示。
“插入控制字符”子菜单的 ID。
插入从左至右标志（LRM）字符。
插入从右至左标志（LRM）字符。
插入开始从左至右嵌入（LRE）字符。
插入开始从右至左嵌入（RLE）字符。
插入开始从左至右强制（LRO）字符。
插入开始从右至左嵌入（RLE）字符。
插入退出方向格式化（PDF）字符。
插入阿拉伯字母标记（ALM）字符。
插入从左至右隔离（LRI）字符。
插入从右至左隔离（RLI）字符。
插入第一个强隔离（FSI）字符。
插入退出方向隔离（PDI）字符。
插入零宽连接符（ZWJ）字符。
插入零宽非连接符（ZWNJ）字符。
插入文字连接符（WJ）字符。
插入软连字符（SHY）字符。
打开系统 Emoji 和符号拾取器。
代表 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 枚举定义。
如果为 true，则文本光标会闪烁。
float caret_blink_interval = 0.65 🔗
文本光标的闪烁间隔（单位为秒）。
LineEdit 中光标的列位置。设置后文本可能会滚动以适应它。
bool caret_force_displayed = false 🔗
如果为 true，则该 LineEdit 会始终显示光标，即使不处于编辑模式或焦点丢失。
bool caret_mid_grapheme = false 🔗
允许在单个复合字符的组件中进行移动光标、选中、删除的操作。
注意：退格键 Backspace 始终按复合字符的组件删除。
bool clear_button_enabled = false 🔗
如果为 true，LineEdit 将在 text 非空时显示清空按钮，可以用来快速清除文本。
如果为 true，右键单击将出现上下文菜单。
bool deselect_on_focus_loss_enabled = true 🔗
如果为 true，则在丢失焦点时会取消选中文本。
bool drag_and_drop_selection_enabled = true 🔗
如果为 true，则允许拖放选中的文本。
bool draw_control_chars = false 🔗
如果为 true，则会显示控制字符。
如果为 false，则不能修改现在的文本，也不能添加新文本。
如果为 true，则启用“Emoji 和符号”菜单。
bool expand_to_text_length = false 🔗
如果为 true，则 LineEdit 宽度将增加到比 text 长。如果 text 被缩短，它将不压缩。
如果为 true，则 LineEdit 不显示装饰。
bool keep_editing_on_text_submit = false 🔗
如果为 true，则按下 ui_text_submit 动作（默认为 Enter 或 Kp Enter）提交文本时 LineEdit 不会退出编辑模式。
语言代码，用于断行和文本塑形算法。如果留空则使用当前区域设置。
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" 作为参数发出。
Text = "Hello world";
MaxLength = 5;
// `Text` 变为 "Hello"。
MaxLength = 10;
Text += " goodbye";
// `text` 变为 "Hello good"。
// `text_change_rejected` 以 "bye" 作为参数发出。
bool middle_mouse_paste_enabled = true 🔗
如果为 false，将禁用鼠标中键粘贴剪贴板。
注意：这个方法只在 Linux 上实现。
String placeholder_text = "" 🔗
当 LineEdit 为空时显示的文本。它不是 LineEdit 的默认值（见 text）。
设置 LineEdit 右端的图标，这个图标会在没有 text 时出现，如果 clear_button_enabled 为 false 则始终可见。
如果为 true，则每个字符都会被替换成密码字符（见 secret_character）。
String secret_character = "•" 🔗
用于掩盖秘密输入的字符。只能用单个字符作为秘密字符。如果长度超过一个字符，则仅使用第一个字符。如果为空，则使用空格代替。
bool select_all_on_focus = false 🔗
如果为 true，则在获得焦点时会全选文本。
bool selecting_enabled = true 🔗
如果为 false，则无法用鼠标或键盘选择文本。
bool shortcut_keys_enabled = true 🔗
为 true 时，即使上下文菜单已被禁用，也会启用该上下文菜单的快捷键。
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 覆盖的附加选项。
LineEdit 的字符串值。
注意：使用这个属性更改文本不会触发 text_changed 信号。
TextDirection text_direction = 0 🔗
void set_text_direction(value: TextDirection)
TextDirection get_text_direction()
基础文本书写方向。
bool virtual_keyboard_enabled = true 🔗
如果为 true，则在获得焦点时会在支持的平台上显示原生虚拟键盘。
VirtualKeyboardType virtual_keyboard_type = 0 🔗
void set_virtual_keyboard_type(value: VirtualKeyboardType)
VirtualKeyboardType get_virtual_keyboard_type()
指定要显示的虚拟键盘的类型。
方法说明
void apply_ime() 🔗
应用输入法编辑器中的文本，如果输入法编辑器处于打开状态，还会将其关闭。
void cancel_ime() 🔗
如果输入法编辑器处于打开状态，则会将其关闭。输入法编辑器中的文本会丢失。
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() 🔗
清除当前选择。
void edit() 🔗
允许进入编辑模式，无论 LineEdit 是否获得焦点。
另见 keep_editing_on_text_submit。
返回该 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())
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 引起的滚动偏移量，单位为字符数。
返回选择内的文本。
int get_selection_from_column() const 🔗
返回选择的开始列。
int get_selection_to_column() const 🔗
返回选择结束列。
如果用户的输入法编辑器中存在文本，则返回 true。
有“重做”动作可用时返回 true。
如果用户选中了文本，则返回 true。
有“撤销”动作可用时返回 true。
void insert_text_at_caret(text: String) 🔗
在光标处插入文本 text。如果最终值比 max_length 长，则不会发生任何事情。
返回 LineEdit 是否处于编辑状态。
返回菜单是否可见。请使用这个方法来代替 get_menu().visible，可以提高性能（因为避免了菜单的创建）。
执行 MenuItems 枚举中定义的给定操作。
void select(from: int = 0, to: int = -1) 🔗
选择 LineEdit 内介于 from 和 to 之间的字符。默认情况下，from 位于开头，to 位于结尾。
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。
void unedit() 🔗
允许退出编辑模式，保持焦点。
主题属性说明
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 minimum_character_width = 4 🔗
文本的最小水平空间（不包括清除按钮和内容边距）。这个值以“M”字符的数量来衡量（即能够在不滚动的情况下显示这么多个“M”字符）。
文字轮廓的大小。
注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。
文本使用的字体。
该 LineEdit 文本的字体大小。
“清除”按钮的纹理。见 clear_button_enabled。
LineEdit 拥有 GUI 焦点时使用的背景。focus StyleBox 显示在基础 StyleBox 之上，所以应该使用部分透明的 StyleBox，确保基础 StyleBox 仍然可见。代表轮廓或下划线的 StyleBox 可以很好地实现这个目的。要禁用聚焦的视觉效果，请指定 StyleBoxEmpty 资源。请注意，禁用聚焦的视觉效果会影响使用键盘/手柄进行导航的可用性，所以出于可访问性的原因，不建议这样做。
该 LineEdit 的默认背景。
该 LineEdit 处于只读模式时使用的背景（editable 为 false）。