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 provides an input field for editing a single line of text.
When the LineEdit control is focused using the keyboard arrow keys, it will only gain focus and not enter edit mode.
To enter edit mode, click on the control with the mouse, see also keep_editing_on_text_submit.
To exit edit mode, press
ui_text_submitorui_cancel(by default Escape) actions.Check edit(), unedit(), is_editing(), and editing_toggled for more information.
While entering text, it is possible to insert special characters using Unicode, OEM or Windows alt codes:
To enter Unicode codepoints, hold Alt and type the codepoint on the numpad. For example, to enter the character
á(U+00E1), hold Alt and type +E1 on the numpad (the leading zeroes can be omitted).To enter OEM codepoints, hold Alt and type the code on the numpad. For example, to enter the character
á(OEM 160), hold Alt and type160on the numpad.To enter Windows codepoints, hold Alt and type the code on the numpad. For example, to enter the character
á(Windows 0225), hold Alt and type 0, 2, 2, 5 on the numpad. The leading zero here must not be omitted, as this is how Windows codepoints are distinguished from OEM codepoints.
Important:
Focusing the LineEdit with
ui_focus_next(by default Tab) orui_focus_prev(by default Shift + Tab) or Control.grab_focus() still enters edit mode (for compatibility).
LineEdit features many built-in shortcuts that are always available (Ctrl here maps to Cmd on macOS):
Ctrl + C: Copy
Ctrl + X: Cut
Ctrl + V or Ctrl + Y: Paste/"yank"
Ctrl + Z: Undo
Ctrl + ~: Swap input direction.
Ctrl + Shift + Z: Redo
Ctrl + U: Delete text from the caret position to the beginning of the line
Ctrl + K: Delete text from the caret position to the end of the line
Ctrl + A: Select all text
Up Arrow/Down Arrow: Move the caret to the beginning/end of the line
On macOS, some extra keyboard shortcuts are available:
Cmd + F: Same as Right Arrow, move the caret one character right
Cmd + B: Same as Left Arrow, move the caret one character left
Cmd + P: Same as Up Arrow, move the caret to the previous line
Cmd + N: Same as Down Arrow, move the caret to the next line
Cmd + D: Same as Delete, delete the character on the right side of caret
Cmd + H: Same as Backspace, delete the character on the left side of the caret
Cmd + A: Same as Home, move the caret to the beginning of the line
Cmd + E: Same as End, move the caret to the end of the line
Cmd + Left Arrow: Same as Home, move the caret to the beginning of the line
Cmd + Right Arrow: Same as End, move the caret to the end of the line
Note: Caret movement shortcuts listed above are not affected by 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 |
|
get_menu() const |
|
get_next_composite_character_column(column: int) const |
|
get_previous_composite_character_column(column: int) 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) 🔗
Emitted when the LineEdit switches in or out of edit mode.
text_change_rejected(rejected_substring: String) 🔗
當追加的文字超過了 max_length 時觸發。追加後的文字會被截斷以適應 max_length，超出的部分會被作為 rejected_substring 參數傳遞。
text_changed(new_text: String) 🔗
當文字更改時觸發。
text_submitted(new_text: String) 🔗
Emitted when the user presses the ui_text_submit action (by default: Enter or Kp Enter) while the LineEdit has focus.
列舉
剪切（複製並刪除）選中的文字。
複製選中的文字。
將剪貼板中的文字貼上到選中文字之上（或者文字游標位置）。
會使用 String.strip_escapes() 自動剝離作業系統剪貼板中不可列印的轉義字符。
刪除 LineEdit 中的全部文字。
選中 LineEdit 中的全部文字。
撤銷之前的操作。
反轉最後一個撤銷動作。
“文字書寫方向”子功能表的 ID。
將文字方向設定為繼承。
將文字方向設定為自動。
將文字方向設定為從左至右。
將文字方向設定為從右至左。
切換控制字元的顯示。
“插入控制字元”子功能表的 ID。
插入從左至右旗標（LRM）字元。
插入從右至左旗標（LRM）字元。
插入開始從左至右嵌入（LRE）字元。
插入開始從右至左嵌入（RLE）字元。
插入開始從左至右強制（LRO）字元。
插入開始從右至左嵌入（RLE）字元。
插入退出方向格式化（PDF）字元。
插入阿拉伯字母標記（ALM）字元。
插入從左至右隔離（LRI）字元。
插入從右至左隔離（RLI）字元。
插入第一個強隔離（FSI）字元。
插入退出方向隔離（PDI）字元。
插入零寬連接子（ZWJ）字元。
插入零寬非連接子（ZWNJ）字元。
插入文字連接子（WJ）字元。
插入軟連字號（SHY）字元。
Opens system emoji and symbol picker.
代表 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。
enum ExpandMode: 🔗
ExpandMode EXPAND_MODE_ORIGINAL_SIZE = 0
Use the original size for the right icon.
ExpandMode EXPAND_MODE_FIT_TO_TEXT = 1
Scale the right icon's size to match the size of the text.
ExpandMode EXPAND_MODE_FIT_TO_LINE_EDIT = 2
Scale the right icon to fit the LineEdit.
屬性說明
HorizontalAlignment alignment = 0 🔗
void set_horizontal_alignment(value: HorizontalAlignment)
HorizontalAlignment get_horizontal_alignment()
The text's horizontal alignment.
bool backspace_deletes_composite_character_enabled = false 🔗
void set_backspace_deletes_composite_character_enabled(value: bool)
bool is_backspace_deletes_composite_character_enabled()
If true and caret_mid_grapheme is false, backspace deletes an entire composite character such as ❤️🩹, instead of deleting part of the composite character.
如果為 true，則文字游標會閃爍。
float caret_blink_interval = 0.65 🔗
文字游標的閃爍間隔（單位為秒）。
LineEdit 中游標的列位置。設定後文字可能會滾動以適應它。
bool caret_force_displayed = false 🔗
If true, the LineEdit will always show the caret, even if not editing or focus is lost.
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，則不能修改現在的文字，也不能新增新文字。
If true, "Emoji and Symbols" menu is enabled.
bool expand_to_text_length = false 🔗
如果為 true，則 LineEdit 寬度將增加到比 text 長。如果 text 被縮短，它將不壓縮。
如果為 true，則 LineEdit 不顯示裝飾。
ExpandMode icon_expand_mode = 0 🔗
void set_icon_expand_mode(value: ExpandMode)
ExpandMode get_icon_expand_mode()
Define the scaling behavior of the right_icon.
bool keep_editing_on_text_submit = false 🔗
If true, the LineEdit will not exit edit mode when text is submitted by pressing ui_text_submit action (by default: Enter or Kp Enter).
Language code used for line-breaking and text shaping algorithms. If left empty, the current locale is used instead.
Maximum number of characters that can be entered inside the LineEdit. If 0, there is no limit.
When a limit is defined, characters that would exceed max_length are truncated. This happens both for existing text contents when setting the max length, or for new text inserted in the LineEdit, including pasting.
If any input text is truncated, the text_change_rejected signal is emitted with the truncated substring as a parameter:
text = "Hello world"
max_length = 5
# `text` becomes "Hello".
max_length = 10
text += " goodbye"
# `text` becomes "Hello good".
# `text_change_rejected` is emitted with "bye" as a parameter.
Text = "Hello world";
MaxLength = 5;
// `Text` becomes "Hello".
MaxLength = 10;
Text += " goodbye";
// `Text` becomes "Hello good".
// `text_change_rejected` is emitted with "bye" as a parameter.
bool middle_mouse_paste_enabled = true 🔗
如果為 false，將禁用滑鼠中鍵貼上剪貼板。
注意：這個方法只在 Linux 上實作。
String placeholder_text = "" 🔗
當 LineEdit 為空時顯示的文字。它不是 LineEdit 的預設值（見 text）。
設定 LineEdit 右端的圖示，這個圖示會在沒有 text 時出現，如果 clear_button_enabled 為 false 則始終可見。
float right_icon_scale = 1.0 🔗
Scale ratio of the icon when icon_expand_mode is set to EXPAND_MODE_FIT_TO_LINE_EDIT.
如果為 true，則每個字元都會被替換成密碼字元（見 secret_character）。
String secret_character = "•" 🔗
The character to use to mask secret input. Only a single character can be used as the secret character. If it is longer than one character, only the first one will be used. If it is empty, a space will be used instead.
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 🔗
If true, the native virtual keyboard is enabled on platforms that support it.
bool virtual_keyboard_show_on_focus = true 🔗
If true, the native virtual keyboard is shown on focus events on platforms that support it.
VirtualKeyboardType virtual_keyboard_type = 0 🔗
void set_virtual_keyboard_type(value: VirtualKeyboardType)
VirtualKeyboardType get_virtual_keyboard_type()
指定要顯示的虛擬鍵盤的型別。
方法說明
void apply_ime() 🔗
Applies text from the Input Method Editor (IME) and closes the IME if it is open.
void cancel_ime() 🔗
Closes the Input Method Editor (IME) if it is open. Any text in the IME will be lost.
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(hide_focus: bool = false) 🔗
Allows entering edit mode whether the LineEdit is focused or not. If hide_focus is true, the focused state will not be shown (see Control.grab_focus()).
See also 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 屬性。
int get_next_composite_character_column(column: int) const 🔗
Returns the correct column at the end of a composite character like ❤️🩹 (mending heart; Unicode: U+2764 U+FE0F U+200D U+1FA79) which is comprised of more than one Unicode code point, if the caret is at the start of the composite character. Also returns the correct column with the caret at mid grapheme and for non-composite characters.
Note: To check at caret location use get_next_composite_character_column(get_caret_column())
int get_previous_composite_character_column(column: int) const 🔗
Returns the correct column at the start of a composite character like ❤️🩹 (mending heart; Unicode: U+2764 U+FE0F U+200D U+1FA79) which is comprised of more than one Unicode code point, if the caret is at the end of the composite character. Also returns the correct column with the caret at mid grapheme and for non-composite characters.
Note: To check at caret location use get_previous_composite_character_column(get_caret_column())
float get_scroll_offset() const 🔗
返回 caret_column 引起的滾動偏移量，單位為字元數。
返回選擇內的文字。
int get_selection_from_column() const 🔗
返回選擇的開始列。
int get_selection_to_column() const 🔗
返回選擇結束列。
Returns true if the user has text in the Input Method Editor (IME).
有“重做”動作可用時返回 true。
如果使用者選中了文字，則返回 true。
有“撤銷”動作可用時返回 true。
void insert_text_at_caret(text: String) 🔗
在游標處插入文字 text。如果最終值比 max_length 長，則不會發生任何事情。
Returns whether the LineEdit is being edited.
返回選單是否可見。請使用這個方法來代替 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() 🔗
Allows exiting edit mode while preserving focus.
主題屬性說明
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）。