Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Font

继承: Resource < RefCounted < Object

派生: FontFile, FontVariation, SystemFont

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

描述

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

属性

Font[]

fallbacks

[]

方法

float

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

float

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

void

draw_multiline_string ( RID canvas_item, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

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

void

draw_string ( RID canvas_item, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

draw_string_outline ( RID canvas_item, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

RID

find_variation ( Dictionary variation_coordinates, int face_index=0, float strength=0.0, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), int spacing_top=0, int spacing_bottom=0, int spacing_space=0, int spacing_glyph=0 ) const

float

get_ascent ( int font_size=16 ) const

Vector2

get_char_size ( int char, int font_size ) const

float

get_descent ( int font_size=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 ( int font_size=16 ) const

Vector2

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

Dictionary

get_opentype_features ( ) const

Dictionary

get_ot_name_strings ( ) const

RID[]

get_rids ( ) const

int

get_spacing ( SpacingType spacing ) const

Vector2

get_string_size ( String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, BitField<JustificationFlag> justification_flags=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 ( int font_size=16 ) const

float

get_underline_thickness ( int font_size=16 ) const

bool

has_char ( int char ) const

bool

is_language_supported ( String language ) const

bool

is_script_supported ( String script ) const

void

set_cache_capacity ( int single_line, int multi_line )


属性说明

Font[] fallbacks = []

  • void set_fallbacks ( Font[] value )

  • Font[] get_fallbacks ( )

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

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


方法说明

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

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

注意:请勿使用这个方法进行逐字符的绘制,请改用 draw_stringTextLine


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

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

注意:请勿使用这个方法进行逐字符的绘制,请改用 draw_stringTextLine


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

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

另见 CanvasItem.draw_multiline_string


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

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

另见 CanvasItem.draw_multiline_string_outline


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

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

另见 CanvasItem.draw_string


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

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

另见 CanvasItem.draw_string


RID find_variation ( Dictionary variation_coordinates, int face_index=0, float strength=0.0, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), int spacing_top=0, int spacing_bottom=0, int spacing_space=0, int spacing_glyph=0 ) const

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


float get_ascent ( int font_size=16 ) const

返回平均上高(基线以上的像素数)。

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


Vector2 get_char_size ( int char, int font_size ) const

返回字符的大小,如果提供了下一个字符,则可以选择考虑字距调整。

注意:不要使用这个函数逐个字符地计算字符串的宽度,而是使用 get_string_sizeTextLine。返回的高度是字体高度(另见 get_height)并且与字形高度无关。


float get_descent ( int font_size=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 ( int font_size=16 ) const

返回总的平均字体高度(上高加下深),单位为像素。

注意:字符串的实际高度取决于上下文,并且可能与该函数返回的值有很大差异。仅将其用作粗略估计(例如作为空行的高度)。


Vector2 get_multiline_string_size ( String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=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(本地化的字体名称、版本、描述、许可信息、示例文本等)。


RID[] get_rids ( ) const

返回有效 Font RIDArray,可以将其传给 TextServer 的方法。


int get_spacing ( SpacingType spacing ) const

返回给定 type 的间距(请参阅 SpacingType)。


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

返回一个单行字符串的边界框的大小,考虑字距调整、提前量和子像素定位。另见 get_multiline_string_sizedraw_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"))

注意:由于 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 ( int font_size=16 ) const

返回基线下方下划线的平均像素偏移。

注意:字符串的实际下划线位置取决于上下文,并且可能与该函数返回的值有很大不同。仅将其用作粗略估计。


float get_underline_thickness ( int font_size=16 ) const

返回下划线的平均粗细。

注意:字符串的实际下划线粗细取决于上下文,并且可能与该函数返回的值有很大不同。仅将其用作粗略估计。


bool has_char ( int char ) const

如果该字体中包含 Unicode 字符 char,则返回 true


bool is_language_supported ( String language ) const

如果该字体支持给定的语言(ISO 639 代码),则返回 true


bool is_script_supported ( String script ) const

如果该字体支持给定的文字(ISO 15924 代码),则返回 true


void set_cache_capacity ( int single_line, int multi_line )

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