字体渲染组件

ESPHome 的图形渲染引擎还具有强大的字体绘制功能，可与系统无缝集成。您可以选择使用任何 OpenType/TrueType（.ttf、.otf、.woff）字体文件的任何大小，以及固定大小的 PCF 和 BDF 位图字体。

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

要使用字体，您可以：

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

接下来，在您的配置中创建一个 font: 部分：

# 配置字体的多种方式
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", # 空格
      "\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 字体，或使用以下结构：
- type (必需, string): 可以是 local、gfonts 或 web。
本地字体:
- path (必需, string): OpenType/TrueType 或位图字体文件的路径（相对于 .yaml 文件所在位置）。
Google 字体:

每个 Google 字体只会下载一次并缓存以供将来使用。这也可以用于下载 Material Symbols 或 Icons，如上面的示例所示。
- family (必需, string): Google 字体系列的名称。
- 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 字体文件在标准键盘无法到达的代码点提供图标，对于这些图标，需要将字形的 unicode 代码点指定为用 \u 或 \U 转义的十六进制地址。

代码点最高到 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" 安装它。

字体渲染组件

字体度量

配置变量

另请参阅