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

回退 Font 数组，会在这个当前 Font 中无法找到某个字形时用作替换。

如果 FontVariation 中的这个数组为空，则会改用 FontVariation.base_font 的回退字体。

方法说明

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

使用该字体将单个 Unicode 字符 char 绘制在画布项目中的给定的位置，颜色为 modulate。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

注意：请勿使用这个方法进行逐字符的绘制，请改用 draw_string() 或 TextLine。

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

使用该字体将单个 Unicode 字符 char 的轮廓绘制在画布项目中的给定的位置，颜色为 modulate。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

注意：请勿使用这个方法进行逐字符的绘制，请改用 draw_string() 或 TextLine。

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) const 🔗

使用 brk_flags 指定的规则对 text 进行断行，并使用该字体将其绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

另见 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) const 🔗

使用 brk_flags 指定的规则对 text 进行断行，并使用该字体将其轮廓绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

另见 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) const 🔗

使用该字体将 text 绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

另见 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) const 🔗

使用该字体将 text 的轮廓绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。

另见 CanvasItem.draw_string()。

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) const 🔗

返回特定变体的字体缓存的 TextServer RID。

float get_ascent(font_size: int = 16) const 🔗

返回平均上高（基线以上的像素数）。

注意：字符串的实际上高是上下文相关的，并且可能与该函数返回的值有很大不同。仅将其用作粗略估计（例如作为空行的上高）。

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

返回字符的大小。不考虑字偶距。

注意：不要使用这个函数逐个字符地计算字符串的宽度，而是使用 get_string_size() 或 TextLine。返回的高度是字体高度（另见 get_height()）并且与字形高度无关。

float get_descent(font_size: int = 16) const 🔗

返回平均下深（基线以下的像素数）。

注意：字符串的真实下深是依赖于上下文的，并且可能与此函数返回的值有很大不同。仅将其用作粗略估计（例如作为空行的下深）。

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 🔗

返回字体样式标志，见 FontStyle。

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（本地化的字体名称、版本、描述、许可信息、示例文本等）。

Array[RID] get_rids() const 🔗

返回有效 Font RID 的 Array，可以将其传给 TextServer 的方法。

int get_spacing(spacing: SpacingType) const 🔗

返回给定 type 的间距（请参阅 SpacingType）。

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 所显示的字符串大小，请使用：

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

Label label = GetNode<Label>("Label");
Vector2 stringSize = label.GetThemeFont("font").GetStringSize(label.Text, HorizontalAlignment.Left, -1, label.GetThemeFontSize("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 🔗

返回支持的变体坐标列表，坐标以 tag: Vector3i(min_value,max_value,default_value) 的形式返回。

字体变体能够沿着某个给定的设计轴对字形的特性进行连续的变化，例如字重、宽度、斜度。

要输出可变字体的可用变体轴：

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("变体轴：%s (%d)\n\t最小值、最大值、默认值：%s" % [name, tag, values])

注意：FontVariation 变体坐标的设置和获取请使用 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 🔗

如果该字体支持给定的语言（ISO 639 代码），则返回 true。

bool is_script_supported(script: String) const 🔗

如果该字体支持给定的文字（ISO 15924 代码），则返回 true。

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

为 draw_* 方法设置 LRU 缓存容量。