字体渲染组件

ESPHome 的图形渲染引擎还包含一个功能强大的字体绘制器，可与系统无缝集成。你可以使用任意 OpenType/TrueType（.ttf、.otf、.woff ）字体文件以及任意尺寸，也可以使用固定尺寸的 PCF 和 BDF 位图字体。

这些字体可在 ESPHome 的自有渲染引擎或 LVGL 图形组件中使用。

要使用字体，你可以：

从网上某处获取一个 .ttf、.otf、.woff、.pcf 或 .bdf 文件，例如将其放在配置文件旁边的 fonts 文件夹中。
使用 gfonts:// 简写形式直接调用 Google Fonts。
在构建时直接从 URL 加载字体。

接着，在你的配置中创建一个 font: 段落：

# Various ways to configure fonts
font:
  - file: "fonts/Comic Sans MS.ttf"
    id: my_font
    size: 20
    bpp: 2

  - file: "fonts/tom-thumb.bdf"
    id: tomthumb

    # gfonts://family[@weight]
  - file: "gfonts://Roboto"
    id: roboto_20
    size: 20

  - file:
      type: gfonts
      family: Roboto
      weight: 900
    id: roboto_16
    size: 16

  - file: "gfonts://Material+Symbols+Outlined"
    id: icons_50
    size: 50
    glyphs: ["\U0000e425"] # mdi-timer

  - file: "fonts/RobotoCondensed-Regular.ttf"
    id: roboto_special_28
    size: 28
    bpp: 4
    glyphs: [
      0123456789aAáÁeEéÉ,
      (,),+,-,_,.,°,•,µ,
      "\u0020", # space
      "\u002C", # ,
      "\u0021", # !
      "\u0022", # "
      "\u0027", # '
      ]

  - file: "fonts/RobotoCondensed-Regular.ttf"
    id: my_font_with_icons
    size: 20
    bpp: 4
    extras:
      - file: "fonts/materialdesignicons-webfont.ttf"
        glyphs: [
          "\U000F02D1", # mdi-heart
          "\U000F05D4", # mdi-airplane-landing
          ]

  - file:
      type: gfonts
      family: Roboto
    id: roboto_european_core
    size: 16
    glyphsets:
      - GF_Latin_Core
      - GF_Greek_Core
      - GF_Cyrillic_Core

  - file: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
    id: web_font
    size: 20
  - file:
      url: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
      type: web
    id: web_font2
    size: 24

display:
  # ...

字体度量

该组件提供了一些有用的字体度量信息，包括：

ascender（get_ascender() ）：字形在基线上方的最大高度（目前返回的值与 get_baseline() 相同）。
capheight（get_capheight() ）：以 X 字形测得的大写字母高度。
xheight（get_xheight() ）：以 x 字形测得的小写字母高度。
baseline（get_baseline() ）：所有字符所在的虚拟线。
descender（get_descender() ）：字形在基线下方的最大高度。
linegap（get_linegap() ）：两行文字之间的间距。
height（get_height() ）：字体的行高，从基线到基线测量。

NOTE

capheight 和 xheight 值通常使用顶部平坦的字形计算得出。圆角字符可能会稍微超出该值，使其在视觉上看起来大小一致。对于像 Material Design Icons 这样不含任何字母的特殊字体，这两个度量值将被设为 0。

以下代码片段生成了下图。请注意，代码中的行与图中从上到下的顺序对应。对于此字体，descender 和 height 之间仅相差一个像素。

it.print(0, 0, id(my_font), "EspHome");

int ascender = id(my_font).get_baseline() - id(my_font).get_ascender();
int capheight = id(my_font).get_baseline() - id(my_font).get_capheight();
int xheight = id(my_font).get_baseline() - id(my_font).get_xheight();
int baseline = id(my_font).get_baseline();
int descender = id(my_font).get_baseline() + id(my_font).get_descender();
int height = id(my_font).get_height();

it.horizontal_line(0, ascender, it.get_width());
it.horizontal_line(0, capheight, it.get_width());
it.horizontal_line(0, xheight, it.get_width());
it.horizontal_line(0, baseline, it.get_width());
it.horizontal_line(0, descender, it.get_width());
it.horizontal_line(0, height, it.get_width());

配置变量

file（必选，string）：字体文件的路径（相对于 .yaml 文件所在位置）。你也可以使用 gfonts:// 简写形式来调用 Google Fonts，或使用以下结构：
- type（必选，string）：可以是 local、gfonts 或 web。
本地字体：
- path（必选，string）：OpenType/TrueType 或位图字体文件的路径（相对于 .yaml 文件所在位置）。
Google Fonts：

每个 Google Font 都会被下载一次并缓存供将来使用。这也可用于下载 Material Symbols 或 Icons（如上例所示）。
- family（必选，string）：Google Font 系列的名称。
- italic（可选，boolean）：字体是否使用斜体。
- weight（可选，enum）：字体的字重。可以是文本名称或整数值：
  - thin：100
  - extra-light：200
  - light：300
  - regular：400（默认值）
  - medium：500
  - semi-bold：600
  - bold：700
  - extra-bold：800
  - black：900
网络字体：
- url（必选，string）：TrueType 或位图字体文件的 URL。
id（必选，ID）：你将在显示代码中用来引用该字体的 ID。
size（可选，int）：字体的目标尺寸。这将是字体渲染时的尺寸（高度，以像素为单位）。如果想在不同尺寸下使用同一字体，请创建两个字体对象。默认值为可变字体的 20，位图字体则为第一个可用的尺寸。请求位图字体中不存在的尺寸将导致错误。
bpp（可选，int）：从 OpenType/TrueType 渲染字体的位深度，用于抗锯齿。可以是 1、2、4、8。默认值为 1。如果设为 1，并且字体在请求尺寸下有位图版本，则将使用位图版本；否则将从矢量表示中渲染字体。
glyphsets（可选，list）：你计划使用的字形集合列表。默认值为 GF_Latin_Kernel，包含基本字符以及英语所需的标点和符号。 GF_Latin_Core 是一个更扩展的集合，包含欧洲和美洲主要语言的字形（使用人数超过 500 万）。其他选项包括 GF_Arabic_Core、GF_Cyrillic_Core、GF_Greek_Core、它们的 Plus 变体，以及 GF_Latin_African、GF_Latin_PriAfrican 和 GF_Latin_Vietnamese。请参阅Google Fonts Glyphset 文档，了解所有可用集合的完整列表，包括名称和各集合支持的语言。注意 GF_Latin_Kernel 可能需要包含在内，以便提供数字（0-9）和空格等基本字符的字形。
glyphs（可选，list）：你计划使用的字符列表，用于补充上方 glyphsets 选项中定义的字符。如果你需要某些特殊字符，或者由于不打算使用某些字形而希望减小二进制文件的大小，请调整此列表。单个字符（a, b, c ）或字符串（abc, def ）都是可接受的选项。你也可以通过字形码点来指定字形（见下文）。
ignore_missing_glyphs（可选，boolean）：默认情况下，对于包含在已定义 glyphsets 中但在所配置字体中不存在的任何字形，都会产生警告。使用此设置可抑制这些警告。请注意，任何手动定义的字形（通过 glyphs 选项指定）的缺失将始终被视为错误，不受此设置影响。
extras（可选，enum）：一个字体字形配置列表，用于将该字体从其他 OpenType/TrueType 文件中包含进来（例如来自其他字体的图标，但尺寸与主字体相同）：
- file（必选，string）：包含额外字形字体的文件路径。
- glyphs（必选，list）：你希望包含的字形列表。不能重复声明上方已使用的相同字形码点。

NOTE

OpenType/TrueType 字体文件提供的图标位于远离标准键盘可及范围的码点处，对于这些图标，需要以 \u 或 \U 转义的十六进制地址形式指定字形的 unicode 码点。

0xFFFF 及以下码点编码为 \uE6E8。使用小写 \u 和正好 4 位十六进制数字。
0xFFFF 以上码点编码为 \U0001F5E9。使用大写 \U 和正好 8 位十六进制数字。

extras 段仅支持 OpenType/TrueType 文件，size 和 bpp 将与上级保持一致。这将允许在同一字符串中打印图标与字符，例如 I \uF004 You \uF001。

大量字体尺寸以及高比特深度下的多个字形将显著增大二进制文件的大小。请谨慎选择。

NOTE

要使用字体，你需要安装 Python 的 pillow 包，因为 ESPHome 使用该包将 OpenType/TrueType 和位图字体文件转换为内部格式。如果你将其作为 Home Assistant 应用运行，或使用官方 ESPHome docker 镜像，它应该已经安装好了。否则你需要使用 pip install "pillow==10.4.0" 进行安装。

字体渲染组件

字体度量

配置变量

参见