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...

Форматований текст GDScript

Godot пропонує кілька способів динамічної зміни вмісту рядків:

Формат рядків: var string = "I have %s cats." % "3"
Метод String.format(): var string = "У мене є {0} котів.".format([3])
Конкатенація рядків: var string = "I have " + str(3) + " cats."

На цій сторінці пояснюється, як використовувати рядки форматування, а також коротко пояснюється метод format() і конкатенація рядків.

Формат рядків

Формат рядків — це спосіб повторного використання текстових шаблонів для стислого створення різних, але схожих рядків.

Рядки форматування схожі на звичайні рядки, за винятком того, що вони містять певні послідовності символів-заповнювачів, наприклад %s. Потім ці заповнювачі можна замінити параметрами, переданими до рядка формату.

Ознайомтеся з цим конкретним прикладом GDScript:

# Define a format string with placeholder '%s'
var format_string = "We're waiting for %s."

# Using the '%' operator, the placeholder is replaced with the desired value
var actual_string = format_string % "Godot"

print(actual_string)
# Output: "We're waiting for Godot."

Заповнювачі завжди починаються з символу %, але наступний символ, або символи, специфікатор формату, вони визначають, як задане значення перетворюється на текст.

%s, який ми бачили у прикладі вище, є найпростішим заповнювачем і працює для більшості випадків використання: він перетворює значення тим самим методом, за допомогою якого неявне перетворення рядка або str() перетворило б його. Рядки залишаються незмінними, логічні значення перетворюються на "True" або "False", int або float стають десятковими, а інші типи зазвичай повертають свої дані у зрозумілому для людини рядку.

Існують інші специфікатори формату.

Кілька заповнювачів

Форматований текст може містити кілька заповнювачів. У такому випадку значення передаються у вигляді масиву, одне значення на заповнювач (якщо не використовується специфікатор формату з *, див. dynamic padding):

var format_string = "%s was reluctant to learn %s, but now he enjoys it."
var actual_string = format_string % ["Estragon", "GDScript"]

print(actual_string)
# Output: "Estragon was reluctant to learn GDScript, but now he enjoys it."

Запримітьте, що значення вставляються по порядку. Пам'ятайте, що всі заповнювачі повинні бути замінені відразу, тому повинно бути відповідне число значень.

Специфікатори формату

Окрім s існують інші специфікатори формату, які можна використовувати в заповнювачах. Вони складаються з одного, або кількох символів. Деякі з них працюють так само, як s, деякі з’являються перед іншими символами, деякі працюють лише з певними значеннями, або символами.

Типи заповнювачів

Один, і тільки один, з них завжди повинен відображатися як останній символ у специфікаторі формату. Крім s, для них потрібні певні типи параметрів.

`s`	Просте перетворення в String (текст, строку) тим самим методом, що і неявне перетворення.
`c`	Один символ Юнікоду. Приймає кодову точку Юнікоду (ціле число) або односимвольний рядок. Підтримує значення понад 255.
`d`	десяткове ціле число. Очікує ціле чи дійсне число (буде наповнено).
`o`	Вісімкове ціле число. Очікує ціле або дійсне число (буде наповнено).
`x`	Шістнадцяткове ціле число з маленькими літерами. Очікує ціле або дійсне число (буде наповнено).
`X`	Шістнадцяткове ціле число з великими літерами. Очікує ціле чи дійсне число (буде наповнено).
`f`	Десяткове дійсне число. Очікує ціле чи дійсне число.
`v`	Вектор. Очікує будь-який векторний об’єкт на основі float або int ( `Vector2`, `Vector3`, `Vector4`, `Vector2i`, `Vector3i` або `Vector4i`). Буде відображати векторні координати в дужках, форматуючи кожну координату так, ніби це `%f`, і використовуючи ті самі модифікатори.

Модифікатори заповнювачів

Ці символи з'являються раніше. Деякі з них працюють лише за певних умов.

`+`	У числових специфікаторах показувати знак +, якщо число додатне.
Integer (ціле)	Встановіть padding. Доповнюється пробілами або нулями, якщо ціле число починається з `0` у заповнювачі цілого чи дійсного числа. Початковий `0` ігнорується, якщо `-` присутній. Якщо використовується після `.`, див. `.`.
`.`	Перед `f` або `v` встановіть precision до 0 знаків після коми. Можна супроводжувати цифрами для зміни. Доповнено нулями.
`-`	Заповнення справа (Pad to the right), а не зліва.
`*`	Динамічний відступ, очікує додатковий цілочисельний параметр для встановлення відступу або точності після `.`, див. динамічне доповнення.

Заповнення

Символи . (крапка), * (зірочка), - (мінус) і цифри (0-9) використовуються для відступів. Це дозволяє надрукувати декілька значень, вирівняних вертикально, як у стовпчику, за умови використання шрифту фіксованої ширини.

Щоб заповнити рядок до мінімальної довжини додайте ціле число до специфікатора:

print("%10d" % 12345)
# output: "     12345"
# 5 leading spaces for a total length of 10

Якщо ціле число починається з 0, цілі значення доповнюються нулями замість пробілу:

print("%010d" % 12345)
# output: "0000012345"

Для дійсних чисел можна вказати точність, додавши . (точку) з цілим числом після нього. Без цілого числа після . використовується точність 0, округлення до цілих значень. Перед крапкою має стояти ціле число, яке буде використано для заповнення.

# Pad to minimum length of 10, round to 3 decimal places
print("%10.3f" % 10000.5555)
# Output: " 10000.556"
# 1 leading space

Символ - буде викликати відступи справа , а не зліва, корисний для правильного вирівнювання тексту:

print("%-10d" % 12345678)
# Output: "12345678  "
# 2 trailing spaces

Динамічний відступ

За допомогою символу * (зірочки), можна встановити відступ або точність, не змінюючи рядок форматування. Він використовується замість цілого числа у специфікаторі формату. Потім при форматуванні передаються значення для заповнення та точності:

var format_string = "%*.*f"
# Pad to length of 7, round to 3 decimal places:
print(format_string % [7, 3, 8.8888])
# Output: "  8.889"
# 2 leading spaces

Все ще можна заповнити нулями в цілочисельних заповнювачах, додавши 0 перед *:

print("%0*d" % [2, 3])
# Output: "03"

Керуюча (Escape) послідовність

Щоб вставити символ % у форматований рядок, його потрібно приховати, щоб він перестав читатися як заповнювач. Це робиться шляхом подвоєння символа:

var health = 56
print("Remaining health: %d%%" % health)
# Output: "Remaining health: 56%"

Метод рядкового форматування

Існує також інший спосіб форматування тексту в GDScript, а саме метод String.format(). Він замінює всі входження ключа в рядку відповідним значенням. Метод може обробляти масиви або словники для пар ключ/значення.

Масиви можна використовувати як ключ, індекс, або змішаний стиль (див. Приклади нижче). Порядок має значення лише тоді, коли використовується індекс, або змішаний стиль масиву.

Короткий приклад у GDScript:

# Define a format string
var format_string = "We're waiting for {str}"

# Using the 'format' method, replace the 'str' placeholder
var actual_string = format_string.format({"str": "Godot"})

print(actual_string)
# Output: "We're waiting for Godot"

Приклади методів форматування

Нижче наведено кілька прикладів того, як використовувати різні виклики методу String.format().

Тип	Стиль	Приклад	Результат
Словник	ключ	`"Привіт, {name} {version}!".format({"name":"Godette", "version":"3.0"})`	Привіт, Godette 3.0!
Словник	індекс	`"Привіт, {0} {1}!".format({"0":"Godette", "1":"3.0"})`	Привіт, Godette 3.0!
Словник	суміш	`"Привіт, {0} {version}!".format({"0":"Godette", "version":"3.0"})`	Привіт, Godette 3.0!
Масив	ключ	`"Привіт, {name} {version}!".format([["version","3.0"], ["name","Godette"]])`	Привіт, Godette 3.0!
Масив	індекс	`"Привіт, {0} {1}!".format(["Godette","3.0"])`	Привіт, Godette 3.0!
Масив	суміш	`"Hi, {name} v{0}!".format(["3.0", ["name","Godette"]])`	Привіт, Godette 3.0!
Масив	без індекса	`"Hi, {} v{}!".format(["Godette", "3.0"], "{}")`	Привіт, Godette 3.0!

Заповнювачі також можуть бути налаштовані при використанні String.format. Далі кілька прикладів цього функціоналу.

Тип	Приклад	Результат
Інфікс (за замовчанням)	`"Привіт, {0} {1}".format(["Godette", "3.0"], "{_}")`	Привіт, Godette v3.0
Постфікс	`"Привіт, 0% 1%".format(["Godette", "3.0"], "_%")`	Привіт, Godette v3.0
Префікс	`"Привіт, %0 %1".format(["Godette", "3.0"], "%_")`	Привіт, Godette v3.0

Поєднання методу String.format та оператора % може бути корисним, оскільки String.format не має способу маніпулювати представленням чисел.

Приклад	Результат
`"Привіт, {0} {version}".format({0:"Godette", "version":"%0.2f" % 3.114})`	Привіт, Godette v3.11

Конкатенація рядків

Ви також можете комбінувати рядки, конкатенуючи їх разом, використовуючи оператор +.

# Define a base string
var base_string = "We're waiting for "

# Concatenate the string
var actual_string = base_string + "Godot"

print(actual_string)
# Output: "We're waiting for Godot"

Під час використання конкатенації рядків значення, які не є рядками, необхідно конвертувати за допомогою функції str(). Немає способу вказати формат рядка для конвертованих значень.

var name_string = "Godette"
var version = 3.0
var actual_string = "Hi, " + name_string + " v" + str(version) + "!"

print(actual_string)
# Output: "Hi, Godette v3!"

Через ці обмеження рядки форматування або метод format() часто є кращим вибором. У багатьох випадках конкатенація рядків також є менш читабельною.

Примітка

У коді Godot C++ до рядків формату GDScript можна отримати доступ за допомогою допоміжної функції vformat() у заголовку Variant.