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...

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）是一种位图或形状，用于根据上下文绘制一个或多个字符。字形索引绑定的是某个字体数据源。

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

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

教程

属性

bool

allow_system_fallback

true

FontAntialiasing

antialiasing

1

PackedByteArray

data

PackedByteArray()

bool

disable_embedded_bitmaps

true

int

fixed_size

0

FixedSizeScaleMode

fixed_size_scale_mode

0

String

font_name

""

int

font_stretch

100

BitField[FontStyle]

font_style

0

int

font_weight

400

bool

force_autohinter

false

bool

generate_mipmaps

false

Hinting

hinting

1

bool

keep_rounding_remainders

true

int

msdf_pixel_range

16

int

msdf_size

48

bool

multichannel_signed_distance_field

false

Dictionary

opentype_feature_overrides

{}

float

oversampling

0.0

String

style_name

""

SubpixelPositioning

subpixel_positioning

1

方法

void

clear_cache()

void

clear_glyphs(cache_index: int, size: Vector2i)

void

clear_kerning_map(cache_index: int, size: int)

void

clear_size_cache(cache_index: int)

void

clear_textures(cache_index: int, size: Vector2i)

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

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

int

get_face_index(cache_index: int) const

Vector2

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

int

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

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

PackedStringArray

get_language_support_overrides() const

bool

get_script_support_override(script: String) const

PackedStringArray

get_script_support_overrides() const

Array[Vector2i]

get_size_cache_list(cache_index: int) const

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

Dictionary

get_variation_coordinates(cache_index: int) const

Error

load_bitmap_font(path: String)

Error

load_dynamic_font(path: String)

void

remove_cache(cache_index: int)

void

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

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)

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)

void

set_face_index(cache_index: int, face_index: int)

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)

void

set_script_support_override(script: String, supported: bool)

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)

void

set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary)

属性说明

bool allow_system_fallback = true 🔗

  • void set_allow_system_fallback(value: bool)

  • bool is_allow_system_fallback()

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

FontAntialiasing antialiasing = 1 🔗

字体抗锯齿模式。

PackedByteArray data = PackedByteArray() 🔗

动态字体源文件的内容。

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 🔗

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

String font_name = "" 🔗

字体家族名称。

int font_stretch = 100 🔗

  • void set_font_stretch(value: int)

  • int get_font_stretch()

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

BitField[FontStyle] font_style = 0 🔗

字体样式标志，见 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 🔗

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

bool keep_rounding_remainders = true 🔗

  • void set_keep_rounding_remainders(value: bool)

  • bool get_keep_rounding_remainders()

如果设置为 true，则将字形与像素边界对齐时会累积舍入余数，确保字形的分布更加均匀。如果启用了次像素定位则该设置无效。

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 🔗

字体字形的子像素定位模式。子像素定位为较小的字体提供了更清晰的文本和更好的字距调整，但代价是更高的内存占用和更低的字体光栅化速度。使用 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()。