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

Font

繼承： Resource < RefCounted < Object

被繼承： FontFile, FontVariation, SystemFont

字形和字形變體的抽象基底類別。

說明

各種字形型別的抽象基底類別。提供了繪製文字以及內省字形字元的方法。

屬性

Array[Font]

fallbacks

[]

方法

float	draw_char(canvas_item: RID, pos: Vector2, char: int, font_size: int, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const
float	draw_char_outline(canvas_item: RID, pos: Vector2, char: int, font_size: int, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const
void	draw_multiline_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const
void	draw_multiline_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const
void	draw_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const
void	draw_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const
RID	find_variation(variation_coordinates: Dictionary, face_index: int = 0, strength: float = 0.0, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), spacing_top: int = 0, spacing_bottom: int = 0, spacing_space: int = 0, spacing_glyph: int = 0, baseline_offset: float = 0.0, palette_index: int = 0, custom_colors: PackedColorArray = PackedColorArray()) const
float	get_ascent(font_size: int = 16) const
Vector2	get_char_size(char: int, font_size: int) const
float	get_descent(font_size: int = 16) const
int	get_face_count() const
String	get_font_name() const
int	get_font_stretch() const
BitField[FontStyle]	get_font_style() const
String	get_font_style_name() const
int	get_font_weight() const
float	get_height(font_size: int = 16) const
Vector2	get_multiline_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
Dictionary	get_opentype_features() const
Dictionary	get_ot_name_strings() const
PackedColorArray	get_palette_colors(index: int) const
int	get_palette_count() const
String	get_palette_name(index: int) const
Array[RID]	get_rids() const
int	get_spacing(spacing: SpacingType) const
Vector2	get_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
String	get_supported_chars() const
Dictionary	get_supported_feature_list() const
Dictionary	get_supported_variation_list() const
float	get_underline_position(font_size: int = 16) const
float	get_underline_thickness(font_size: int = 16) const
bool	has_char(char: int) const
bool	is_language_supported(language: String) const
bool	is_script_supported(script: String) const
void	set_cache_capacity(single_line: int, multi_line: int)

---

屬性說明

Array[Font] fallbacks = [] 🔗

• void set_fallbacks(value: Array[Font])

• Array[Font] get_fallbacks()

如果在該 FontVariation 中找不到字形，則用作替代的退回 Font 陣列。如果沒有設定，則使用 FontVariation.base_font 的退回字形。

---

方法說明

float draw_char(canvas_item: RID, pos: Vector2, char: int, font_size: int, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const 🔗

Draw a single Unicode character char into a canvas item using the font, at a given position, with modulate color. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

Note: Do not use this function to draw strings character by character, use draw_string() or TextLine instead.

---

float draw_char_outline(canvas_item: RID, pos: Vector2, char: int, font_size: int, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const 🔗

Draw a single Unicode character char outline into a canvas item using the font, at a given position, with modulate color and size outline size. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

Note: Do not use this function to draw strings character by character, use draw_string() or TextLine instead.

---

void draw_multiline_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const 🔗

Breaks text into lines using rules specified by brk_flags and draws it into a canvas item using the font, at a given position, with modulate color, optionally clipping the width and aligning horizontally. pos specifies the baseline of the first line, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

See also CanvasItem.draw_multiline_string().

---

void draw_multiline_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const 🔗

Breaks text to the lines using rules specified by brk_flags and draws text outline into a canvas item using the font, at a given position, with modulate color and size outline size, optionally clipping the width and aligning horizontally. pos specifies the baseline of the first line, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

See also CanvasItem.draw_multiline_string_outline().

---

void draw_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const 🔗

Draw text into a canvas item using the font, at a given position, with modulate color, optionally clipping the width and aligning horizontally. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

See also CanvasItem.draw_string().

---

void draw_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0, oversampling: float = 0.0) const 🔗

Draw text outline into a canvas item using the font, at a given position, with modulate color and size outline size, optionally clipping the width and aligning horizontally. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

See also CanvasItem.draw_string_outline().

---

RID find_variation(variation_coordinates: Dictionary, face_index: int = 0, strength: float = 0.0, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), spacing_top: int = 0, spacing_bottom: int = 0, spacing_space: int = 0, spacing_glyph: int = 0, baseline_offset: float = 0.0, palette_index: int = 0, custom_colors: PackedColorArray = PackedColorArray()) const 🔗

返回特定變體的字形快取的 TextServer RID。

---

float get_ascent(font_size: int = 16) const 🔗

Returns the maximum font ascent (number of pixels above the baseline) of this font and all fallback fonts.

Note: Real ascent of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate (e.g. as the ascent of empty line).

---

Vector2 get_char_size(char: int, font_size: int) const 🔗

Returns the size of a character. Does not take kerning into account.

Note: Do not use this function to calculate width of the string character by character, use get_string_size() or TextLine instead. The height returned is the font height (see also get_height()) and has no relation to the glyph height.

---

float get_descent(font_size: int = 16) const 🔗

Returns the maximum font descent (number of pixels below the baseline) of this font and all fallback fonts.

Note: Real descent of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate (e.g. as the descent of empty line).

---

int get_face_count() const 🔗

返回 TrueType / OpenType 集合中的字形數。

---

String get_font_name() const 🔗

返回字形家族名稱。

---

int get_font_stretch() const 🔗

返回與正常寬度相比的字形拉伸量。一個介於 50% 和 200% 之間的百分比值。

---

BitField[FontStyle] get_font_style() const 🔗

Returns font style flags.

---

String get_font_style_name() const 🔗

返回字形樣式名稱。

---

int get_font_weight() const 🔗

返回該字形的字重（粗度）。一個在 100...999 範圍內的值，正常字形字重為 400，粗體字形字重為 700。

---

float get_height(font_size: int = 16) const 🔗

返回總的平均字形高度（上高加下深），單位為圖元。

注意：字串的實際高度取決於本文，並且可能與該函式返回的值有很大差異。僅將其用作粗略估計（例如作為空行的高度）。

---

Vector2 get_multiline_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, brk_flags: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

返回分割成行的字串的邊界框的大小，將字距調整和前進量考慮在內。

另見 draw_multiline_string()。

---

Dictionary get_opentype_features() const 🔗

返回一組 OpenType 功能標籤。更多資訊：OpenType 功能標籤。

---

Dictionary get_ot_name_strings() const 🔗

返回 OpenType 字形名稱字串的 Dictionary（當地語系化的字形名稱、版本、描述、許可資訊、範例文字等）。

---

PackedColorArray get_palette_colors(index: int) const 🔗

Returns the array in the predefined color palette at index. Palette contains all colors used to render font glyphs. Each palette has the same number of colors. Colors can be overridden using FontVariation.

---

int get_palette_count() const 🔗

Returns the number of predefined color palettes. Palette contains all colors used to render font glyphs. Each palette has the same number of colors.

---

String get_palette_name(index: int) const 🔗

Returns the name of the predefined color palette at index. Palette contains all colors used to render font glyphs. Each palette has the same number of colors.

---

Array[RID] get_rids() const 🔗

返回有效 Font RID 的 Array，可以將其傳給 TextServer 的方法。

---

int get_spacing(spacing: SpacingType) const 🔗

Returns the amount of spacing for the given spacing type.

---

Vector2 get_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

返回一個單行字串的邊界框的大小，考慮字距調整、提前量和子圖元定位。另見 get_multiline_string_size() 和 draw_string()。

例如，要獲取單行 Label 所顯示的字串大小，請使用：

GDScriptC#

var string_size = $Label.get_theme_font("font").get_string_size($Label.text, HORIZONTAL_ALIGNMENT_LEFT, -1, $Label.get_theme_font_size("font_size"))

注意：由於 get_string_size() 考慮了字距調整、提前量和子圖元定位元，因此對字串的子字串使用單獨的 get_string_size() 呼叫，然後將結果加在一起，將返回與對完整字串使用單個 get_string_size() 呼叫的返回值不同的結果 。

注意：字串的實際高度取決於本文，並且可能與 get_height() 返回的值有很大不同。

---

String get_supported_chars() const 🔗

返回一個包含字形中所有可用字元的字串。

如果給定字元被包含在多個字形資料來源中，則它在返回的字串中只出現一次。

---

Dictionary get_supported_feature_list() const 🔗

返回字形支援的 OpenType 功能列表。

---

Dictionary get_supported_variation_list() const 🔗

Returns list of supported variation coordinates, each coordinate is returned as tag: Vector3i(min_value,max_value,default_value).

Font variations allow for continuous change of glyph characteristics along some given design axis, such as weight, width or slant.

To print available variation axes of a variable font:

var fv = FontVariation.new()
fv.base_font = load("res://RobotoFlex.ttf")
var variation_list = fv.get_supported_variation_list()
for tag in variation_list:
    var name = TextServerManager.get_primary_interface().tag_to_name(tag)
    var values = variation_list[tag]
    print("variation axis: %s (%d)\n\tmin, max, default: %s" % [name, tag, values])

Note: To set and get variation coordinates of a FontVariation, use FontVariation.variation_opentype.

---

float get_underline_position(font_size: int = 16) const 🔗

返回基線下方底線的平均圖元偏移。

注意：字串的實際底線位置取決於本文，並且可能與該函式返回的值有很大不同。僅將其用作粗略估計。

---

float get_underline_thickness(font_size: int = 16) const 🔗

返回底線的平均粗細。

注意：字串的實際底線粗細取決於本文，並且可能與該函式返回的值有很大不同。僅將其用作粗略估計。

---

bool has_char(char: int) const 🔗

如果該字形中包含 Unicode 字元 char，則返回 true。

---

bool is_language_supported(language: String) const 🔗

Returns true if the font supports the given language (as a ISO 639 code).

---

bool is_script_supported(script: String) const 🔗

Returns true if the font supports the given script (as a ISO 15924 code).

---

void set_cache_capacity(single_line: int, multi_line: int) 🔗

為 draw_* 方法設定 LRU 快取容量。