FontFile

继承： Font < Resource < RefCounted < Object

存放字体源数据和预渲染字形的缓存，从动态字体或位图字体导入。

描述

FontFile 包含了一组字形，代表从字体文件中导入的 Unicode 字符，还包含了光栅化字形的缓存，以及一组备用的回退 Font。

要访问字体的 OpenType 变体，创建模拟的粗体/斜体版本，或者绘制文本行，请使用 FontVariation。

要进行更复杂的文本处理，请将 FontVariation 与 TextLine 或 TextParagraph 结合使用。

支持的字体格式：

• 动态字体导入器：TrueType（.ttf）、TrueType 合集（.ttc）、OpenType（.otf）、OpenType 合集（.otc）、WOFF（.woff）、WOFF2（.woff2）、Type 1（.pfb，.pfm）。

• 位图字体导入器：AngelCode BMFont（.fnt，.font），支持文本和二进制（版本 3）格式变体。

• 等宽图像字体导入器：所有支持的图像格式。

注意：字符（character）是一种表示某个项目（字母、数字等）的抽象符号。

注意：字形（glphy）是一种位图或形状，用于根据上下文绘制一个或多个字符。字形索引绑定的是某个字体数据源。

注意：如果所有字体数据源都不包含字符串中某个字符的字形，那么该字符就会被替换为一个中间是对应十六进制码的方框。

GDScriptC#

var f = load("res://BarlowCondensed-Bold.ttf")
$Label.add_theme_font_override("font", f)
$Label.add_theme_font_size_override("font_size", 64)

var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf");
GetNode("Label").AddThemeFontOverride("font", f);
GetNode("Label").AddThemeFontSizeOverride("font_size", 64);

教程

• 运行时文件加载与保存

属性

方法

属性说明

bool allow_system_fallback = true 🔗

• void set_allow_system_fallback(value: bool)

• bool is_allow_system_fallback()

如果设置为 true，则可以自动将系统字体作为回退使用。

FontAntialiasing antialiasing = 1 🔗

• void set_antialiasing(value: FontAntialiasing)

• FontAntialiasing get_antialiasing()

字体抗锯齿模式。

PackedByteArray data = PackedByteArray() 🔗

• void set_data(value: PackedByteArray)

• PackedByteArray get_data()

动态字体源文件的内容。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

bool disable_embedded_bitmaps = true 🔗

• void set_disable_embedded_bitmaps(value: bool)

• bool get_disable_embedded_bitmaps()

如果为 true，则会禁用内嵌字体位图的加载（仅包含位图的字体以及彩色字体会禁用该属性）。

int fixed_size = 0 🔗

• void set_fixed_size(value: int)

• int get_fixed_size()

字体大小，仅用于位图字体。

FixedSizeScaleMode fixed_size_scale_mode = 0 🔗

• void set_fixed_size_scale_mode(value: FixedSizeScaleMode)

• FixedSizeScaleMode get_fixed_size_scale_mode()

缩放模式，只有 fixed_size 大于零的位图字体会使用。

String font_name = "" 🔗

• void set_font_name(value: String)

• String get_font_name()

字体家族名称。

int font_stretch = 100 🔗

• void set_font_stretch(value: int)

• int get_font_stretch()

与正常宽度相比的字体的拉伸量。 一个介于 50% 和 200% 之间的百分比值。

BitField[FontStyle] font_style = 0 🔗

• void set_font_style(value: BitField[FontStyle])

• BitField[FontStyle] get_font_style()

字体样式标志，见 FontStyle。

int font_weight = 400 🔗

• void set_font_weight(value: int)

• int get_font_weight()

该字体的字重（粗度）。一个在 100...999 范围内的值，正常字体字重为 400，粗体字体字重为 700。

bool force_autohinter = false 🔗

• void set_force_autohinter(value: bool)

• bool is_force_autohinter()

如果设置为 true，则支持自动提示并且优先于字体内置提示。仅由动态字体使用（MSDF 字体不支持提示）。

bool generate_mipmaps = false 🔗

• void set_generate_mipmaps(value: bool)

• bool get_generate_mipmaps()

如果设置为 true，则为字体纹理生成 mipmap。

Hinting hinting = 1 🔗

• void set_hinting(value: Hinting)

• Hinting get_hinting()

字体微调模式。仅由动态字体使用。

int msdf_pixel_range = 16 🔗

• void set_msdf_pixel_range(value: int)

• int get_msdf_pixel_range()

最小和最大可表示的有符号距离之间的形状周围的范围宽度。如果使用字体轮廓，msdf_pixel_range 必须至少设置为最大字体轮廓大小的两倍。msdf_pixel_range 的默认值为 16，允许大小最大到 8 的轮廓看起来正确。

int msdf_size = 48 🔗

• void set_msdf_size(value: int)

• int get_msdf_size()

用于生成 MSDF 纹理的源字体大小。较高的值允许更高的精度，但渲染速度较慢并且需要更多内存。只有当注意到字形渲染中明显缺乏精度时，才增加该属性的值。

bool multichannel_signed_distance_field = false 🔗

• void set_multichannel_signed_distance_field(value: bool)

• bool is_multichannel_signed_distance_field()

如果被设置为 true，则所有大小的字形进行渲染时，都使用从动态字体矢量数据中生成的单个多通道带符号距离场（MSDF）。由于这种方法不依赖于在每次字体大小发生变化时，对字体进行栅格化，因此可以实时调整字体大小而不会造成任何性能损失。对于按比例缩小的 Control（或从远距离查看的 Label3D），文本也不会看起来有颗粒感。有一个缺点，MSDF 不提供字体提示。缺少字体提示可能会导致大小较小的字体的清晰度和可读性较差。

注意：如果使用字体轮廓，msdf_pixel_range 必须至少设置为最大字体轮廓大小的两倍。

注意：MSDF 字体渲染不能正确渲染具有重叠形状的字形。根据 OpenType 标准，重叠形状是无效的，但在许多字体文件中仍然很常见，尤其是那些由 Google 字体转换的字体文件。为避免字形重叠的问题，请考虑直接从字体开发公司下载字体文件，而不是依赖 Google 字体。

Dictionary opentype_feature_overrides = {} 🔗

• void set_opentype_feature_overrides(value: Dictionary)

• Dictionary get_opentype_feature_overrides()

字体 OpenType 特性集覆盖。

float oversampling = 0.0 🔗

• void set_oversampling(value: float)

• float get_oversampling()

字体过采样系数。如果设置为 0.0 ，则使用全局过采样系数。仅由动态字体使用（MSDF 字体忽略过采样）。

String style_name = "" 🔗

• void set_font_style_name(value: String)

• String get_font_style_name()

字体样式名称。

SubpixelPositioning subpixel_positioning = 1 🔗

• void set_subpixel_positioning(value: SubpixelPositioning)

• SubpixelPositioning get_subpixel_positioning()

字体字形的子像素定位模式。子像素定位为较小的字体提供了更清晰的文本和更好的字距调整，但代价是更高的内存占用和更低的字体光栅化速度。使用 TextServer.SUBPIXEL_POSITIONING_AUTO 来根据字体大小自动启用它。

方法说明

void clear_cache() 🔗

移除所有字体缓存条目。

void clear_glyphs(cache_index: int, size: Vector2i) 🔗

从字体缓存条目中，移除所有渲染的字形信息。

注意：该函数不会移除与字形相关的纹理，请使用 remove_texture 手动移除它们。

void clear_kerning_map(cache_index: int, size: int) 🔗

移除所有字距调整覆盖。

void clear_size_cache(cache_index: int) 🔗

从缓存条目中移除所有字体大小

void clear_textures(cache_index: int, size: Vector2i) 🔗

从字体缓存条目中，移除所有纹理。

注意：该函数不会移除与纹理相关的字形，请使用 remove_glyph 手动移除它们。

float get_cache_ascent(cache_index: int, size: int) const 🔗

返回字体的上升幅度（超出基线的像素数）。

int get_cache_count() const 🔗

返回字体缓存条目的数量。

float get_cache_descent(cache_index: int, size: int) const 🔗

返回字体的减少量（低于基线的像素数）。

float get_cache_scale(cache_index: int, size: int) const 🔗

返回颜色位图字体的缩放系数。

float get_cache_underline_position(cache_index: int, size: int) const 🔗

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

float get_cache_underline_thickness(cache_index: int, size: int) const 🔗

返回下划线的粗细度，单位为像素。

int get_char_from_glyph_index(size: int, glyph_index: int) const 🔗

返回与 glyph_index 关联的字符代码，如果 glyph_index 无效则返回 0。见 get_glyph_index。

float get_embolden(cache_index: int) const 🔗

返回加粗强度，如果不等于零，则加粗字体轮廓。负值会减小轮廓粗细。

float get_extra_baseline_offset(cache_index: int) const 🔗

返回额外的基线偏移（作为字体高度的一部分）。

int get_extra_spacing(cache_index: int, spacing: SpacingType) const 🔗

返回 spacing 的间距（见 SpacingType），单位为像素（与字体大小无关）。

int get_face_index(cache_index: int) const 🔗

返回 TrueType / OpenType 集合中的活动字体索引。

Vector2 get_glyph_advance(cache_index: int, size: int, glyph: int) const 🔗

返回字形前进量（下一个字形的偏移量）。

注意：字形轮廓的前进量，与基础字形的前进量相同，不会被保存。

int get_glyph_index(size: int, char: int, variation_selector: int) const 🔗

返回 char 的字形索引，可以用 variation_selector 修改。

PackedInt32Array get_glyph_list(cache_index: int, size: Vector2i) const 🔗

返回缓存条目中的已渲染字形列表。

Vector2 get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回字形的基线偏移量。

Vector2 get_glyph_size(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回字形大小。

int get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回包含该字形的缓存纹理的索引。

Rect2 get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回包含该字形的缓存纹理中的矩形。

Vector2 get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) const 🔗

返回字形对的字距调整。

Array[Vector2i] get_kerning_list(cache_index: int, size: int) const 🔗

返回字距调整覆盖的列表。

bool get_language_support_override(language: String) const 🔗

如果为 language 启用了支持覆盖，则返回 true。

PackedStringArray get_language_support_overrides() const 🔗

返回语言支持覆盖的列表。

bool get_script_support_override(script: String) const 🔗

如果为 script 启用了支持覆盖，则返回 true。

PackedStringArray get_script_support_overrides() const 🔗

返回文字支持覆盖的列表。

Array[Vector2i] get_size_cache_list(cache_index: int) const 🔗

返回缓存中字体大小的列表。每个大小都是由字体大小和轮廓大小组成的 Vector2i。

int get_texture_count(cache_index: int, size: Vector2i) const 🔗

返回字体缓存条目所使用的纹理数。

Image get_texture_image(cache_index: int, size: Vector2i, texture_index: int) const 🔗

返回字体缓存纹理图像的副本。

PackedInt32Array get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) const 🔗

返回包含字形打包数据的数组副本。

Transform2D get_transform(cache_index: int) const 🔗

返回应用于字体轮廓的 2D 变换，可用于倾斜、翻转和旋转字形。

Dictionary get_variation_coordinates(cache_index: int) const 🔗

返回指定字体缓存条目的变体坐标。有关详细信息，请参阅 Font.get_supported_variation_list。

Error load_bitmap_font(path: String) 🔗

从文件 path 中加载一个 AngelCode BMFont (.fnt, .font) 位图字体。

警告：该方法只能在编辑器中或需要在运行时加载外部字体的情况下使用，例如位于 user:// 目录的字体。

Error load_dynamic_font(path: String) 🔗

从文件 path 中加载 TrueType（.ttf）、OpenType（.otf）、WOFF（.woff）、WOFF2（.woff2）或 Type 1（.pfb、.pfm）动态字体。

警告：该方法只能在编辑器中或需要在运行时加载外部字体的情况下使用，例如位于 user:// 目录的字体。

void remove_cache(cache_index: int) 🔗

删除指定的字体缓存条目。

void remove_glyph(cache_index: int, size: Vector2i, glyph: int) 🔗

从缓存条目中移除指定的渲染的字形信息。

注意：该函数不会移除与字形相关的纹理，请使用 remove_texture 手动移除它们。

void remove_kerning(cache_index: int, size: int, glyph_pair: Vector2i) 🔗

移除字形对的字距调整覆盖。

void remove_language_support_override(language: String) 🔗

移除语言支持覆盖。

void remove_script_support_override(script: String) 🔗

移除文字支持覆盖。

void remove_size_cache(cache_index: int, size: Vector2i) 🔗

从缓存条目中移除指定的字体大小。

void remove_texture(cache_index: int, size: Vector2i, texture_index: int) 🔗

从缓存条目中移除指定的纹理。

注意：该函数不会移除与纹理相关的字形，请使用 remove_glyph 手动移除它们。

void render_glyph(cache_index: int, size: Vector2i, index: int) 🔗

将指定的字符渲染到字体缓存纹理。

void render_range(cache_index: int, size: Vector2i, start: int, end: int) 🔗

将范围内的字符渲染到字体缓存纹理。

void set_cache_ascent(cache_index: int, size: int, ascent: float) 🔗

设置字体的升部（基线上方的像素数）。

void set_cache_descent(cache_index: int, size: int, descent: float) 🔗

设置字体的降部（基线下方的像素数）。

void set_cache_scale(cache_index: int, size: int, scale: float) 🔗

设置彩色位图字体的缩放系数。

void set_cache_underline_position(cache_index: int, size: int, underline_position: float) 🔗

设置基线下方下划线的像素偏移。

void set_cache_underline_thickness(cache_index: int, size: int, underline_thickness: float) 🔗

设置下划线的粗细度，单位为像素。

void set_embolden(cache_index: int, strength: float) 🔗

设置加粗强度，如果不等于零，则会加粗字体的轮廓。负值会减小轮廓的厚度。

void set_extra_baseline_offset(cache_index: int, baseline_offset: float) 🔗

设置额外的基线偏移（作为字体高度的一部分）。

void set_extra_spacing(cache_index: int, spacing: SpacingType, value: int) 🔗

将 spacing 的间距（见 SpacingType）设置为 value，单位为像素（与字体大小无关）。

void set_face_index(cache_index: int, face_index: int) 🔗

在 TrueType / OpenType 集合中设置活动字体索引。

void set_glyph_advance(cache_index: int, size: int, glyph: int, advance: Vector2) 🔗

设置字形前进量（下一个字形的偏移量）。

注意：字形轮廓的前进量与基础字形的前进量相同，不会被保存。

void set_glyph_offset(cache_index: int, size: Vector2i, glyph: int, offset: Vector2) 🔗

设置字形相对于基线的偏移量。

void set_glyph_size(cache_index: int, size: Vector2i, glyph: int, gl_size: Vector2) 🔗

设置字形大小。

void set_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int, texture_idx: int) 🔗

设置包含该字形的缓存纹理的索引。

void set_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int, uv_rect: Rect2) 🔗

设置包含该字形的缓存纹理中，该字形的矩形区域。

void set_kerning(cache_index: int, size: int, glyph_pair: Vector2i, kerning: Vector2) 🔗

设置字形对的字距调整。

void set_language_support_override(language: String, supported: bool) 🔗

为 Font.is_language_supported 添加覆盖。

void set_script_support_override(script: String, supported: bool) 🔗

为 Font.is_script_supported 添加覆盖。

void set_texture_image(cache_index: int, size: Vector2i, texture_index: int, image: Image) 🔗

设置字体缓存纹理图像。

void set_texture_offsets(cache_index: int, size: Vector2i, texture_index: int, offset: PackedInt32Array) 🔗

设置包含字形打包数据的数组。

void set_transform(cache_index: int, transform: Transform2D) 🔗

设置应用于字体轮廓的 2D 变换，可用于倾斜、翻转、旋转字形。

void set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary) 🔗

为指定的字体缓存条目设置变体坐标。有关详细信息，请参阅 Font.get_supported_variation_list。