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

回退 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), oversampling: float = 0.0) const 🔗

使用该字体将单个 Unicode 字符 char 绘制在画布项目中的给定的位置，颜色为 modulate。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。如果 oversampling 大于零，则会将其用作字体过采样系统，否则会使用视口的过采样设置。

注意：请勿使用这个方法进行逐字符的绘制，请改用 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), oversampling: float = 0.0) const 🔗

使用该字体将单个 Unicode 字符 char 的轮廓绘制在画布项目中的给定的位置，颜色为 modulate。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。如果 oversampling 大于零，则会将其用作字体过采样系统，否则会使用视口的过采样设置。

注意：请勿使用这个方法进行逐字符的绘制，请改用 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, oversampling: float = 0.0) const 🔗

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

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

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

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

使用该字体将 text 绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。如果 oversampling 大于零，则会将其用作字体过采样系统，否则会使用视口的过采样设置。

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

使用该字体将 text 的轮廓绘制在画布项目中的给定位置，颜色为 modulate，也可以指定裁剪宽度并进行水平对齐。pos 指定的是基线位置而不是顶部。如果要按顶部位置绘制，则必须在 Y 轴中加入升部。如果 oversampling 大于零，则会将其用作字体过采样系统，否则会使用视口的过采样设置。

另见 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, palette_index: int = 0, custom_colors: PackedColorArray = PackedColorArray()) const 🔗

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

float get_ascent(font_size: int = 16) const 🔗

返回该字体及其所有备用字体（fallback fonts）的最大上升高度（即基线以上的像素数）。

注意： 字符串的实际上升高度是取决于具体上下文（具体文字内容）的，可能会与该函数返回的值有显著差异。请仅将其作为粗略的估算值使用（例如，用于估算空行的上升高度）。

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

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

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

float get_descent(font_size: int = 16) const 🔗

返回该字体及其所有备用字体（fallback fonts）的最大下降高度（即基线以下的像素数）。

注意： 字符串的实际下降高度是取决于具体上下文（具体文字内容）的，可能会与该函数返回的值有显著差异。请仅将其作为粗略的估算值使用（例如，用于估算空行的下降高度）。

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 🔗

返回字体样式标志。

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 🔗

返回 index 处预定义颜色调色板中的数组。调色板包含用于渲染字体字形的所有颜色。每个调色板的颜色数量相同。可以使用 FontVariation 覆盖颜色。

int get_palette_count() const 🔗

返回预定义颜色调色板的数量。调色板包含用于渲染字体字形的所有颜色。每个调色板的颜色数量相同。

String get_palette_name(index: int) const 🔗

返回 index 处预定义颜色调色板的名称。调色板包含用于渲染字体字形的所有颜色。每个调色板的颜色数量相同。

Array[RID] get_rids() const 🔗

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

int get_spacing(spacing: SpacingType) const 🔗

返回间隔类型 spacing 的间距。

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 缓存容量。