Font

继承： Resource < RefCounted < Object

派生： FontFile, FontVariation, SystemFont

字体和字体变体的抽象基类。

描述

各种字体类型的抽象基类。提供了绘制文本以及内省字体字符的方法。

属性

方法

属性说明

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

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

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