图像

使用此组件在设备上存储图形图像，然后可以在兼容的显示器上绘制这些图像。

如需显示运行时下载的图像，请参阅在线图像组件。

image:
  - file: "image.png"
    type: binary
    id: my_image
    resize: 100x100

image:
  - file: mdi:alert-outline
    id: alert
    type: grayscale
    transparency: alpha_channel
    resize: 80x80

image:
  defaults:
    type: rgb565
    resize: 200x162
  images:
    - file: https://media.esphome.io/logo/logo.png
      id: esphome_logo

配置变量

file (必需, string):
- 本地文件: 图像文件的路径（相对于 .yaml 文件所在位置）。
- Material Design 图标: 以 mdi:icon-name 格式指定 Material Design 图标 ID，该图标将自动下载并添加到配置中。
- Material Design Light 图标: 以 mdil:icon-name 格式指定 Material Design Light 图标 ID，该图标将自动下载并添加到配置中。
- Memory 图标: 以 memory:icon-name 格式指定 Memory 图标 ID，该图标将自动下载并添加到配置中。
- 远程文件: 图像文件的 URL。
id (必需, ID): 用于在显示代码中引用此图像的 ID。
resize (可选, string): 如果设置，将调整图像大小以适应给定的尺寸 宽度x高度，并保持纵横比。
type (必需): 指定图像的内部编码方式。
- BINARY : 两种颜色，适用于单色显示器或彩色显示器中的双色图像。每个像素使用 1 位，每字节 8 个像素。仅支持 chroma_key 透明度。
- GRAYSCALE : 全灰度。每个像素使用 8 位，每字节 1 个像素。
- RGB565 : 有损 RGB 颜色存储。每个像素使用 2 字节，带 alpha 通道时为 3 字节。
- RGB : 完整 RGB 颜色存储。每个像素使用 3 字节，带 alpha 通道时为 4 字节。
transparency (可选): 如果设置，将考虑输入图像的 alpha 通道。可能的值有 opaque（默认）、chroma_key 和 alpha_channel。二进制图像不支持 alpha_channel。请参阅下方关于透明度的讨论。
invert_alpha (可选, 布尔值): 仅适用于二进制和灰度图像，这将反转颜色，即黑白互换。适用于电子墨水屏。默认为 false。
dither (可选): 指定用于处理图像的抖动方法，仅用于 GRAYSCALE 和 BINARY 类型图像。默认为 NONE。您可以在 Pillow 文档和维基百科中了解更多信息。
- NONE : 每个像素转换为其最接近的颜色。
- FLOYDSTEINBERG : 使用 Floyd-Steinberg 抖动来近似原始图像的亮度级别。
byte_order (可选, string): 对于 RGB565 图像，像素被转换为 16 位值。默认情况下，它们将以大端字节顺序存储（MSB 优先），但您可以通过将 byte_order 设置为 little_endian 来覆盖此设置。选项有 big_endian（默认）和 little_endian。不适用于其他图像格式。

设置默认值

对于大多数或所有图像共享相同属性的情况，您可以使用另一种架构风格来提供默认值。在这种情况下， defaults: 选项将为所有图像提供回退值。使用此格式时，images: 键接受图像定义列表。

image:
  defaults:
    type: rgb565
    transparency: opaque
    resize: 100x100
  images:
    - file: "image1.png"
      id: image1
    - file: "image2.png"
      id: image2
      resize: 200x200  # 覆盖默认的 resize 值

按类型分组图像

您可以按类型对图像进行分组以便于管理。当您有许多图像需要以相同方式编码时，这很有用，并且可以避免为每个图像重复相同的类型。可以使用 defaults: 组来指定类型以外的默认值。类型名称用作组的键。例如：

image:
  defaults:
    resize: 100x100
  grayscale:
    - file: "image1.png"
      id: image1
    - file: "image2.png"
      id: image2
    - file: "image3.png"
      id: image3

  rgb565:
    - file: "image4.png"
      id: image4
    - file: "image5.png"
      id: image5

此外，可以在类型组内通过使用透明度类型作为键来设置默认透明度类型。

image:
  rgb565:
    alpha_channel:
    - file: "image1.png"
      id: image1
    - file: "image2.png"
      id: image2
    opaque:
    - file: "image2.png"

显示图像

图像可以在需要图像的 LVGL 配置中使用。有关更多信息，请参阅 LVGL 文档。

要直接在 ESPHome 显示器上显示图像，可以在显示 lambda 中使用 image 方法。

display:
  - platform: ...
    # ...
    lambda: |-
      // 在位置 [x=0,y=0] 绘制图像 my_image
      it.image(0, 0, id(my_image));

默认情况下，ESPHome 会将图像对齐到左上角。这意味着如果您输入坐标 [0,10] 作为图像位置，图像的左上角将位于 [0,10]。如果您想在显示器右侧绘制某个图像，选择不同的图像对齐方式有时会很有用。当您输入 [0,10] 时，实际上是在告诉 ESPHome 将图像的锚点定位在 [0,10]。当使用不同的对齐方式（如 TOP_RIGHT）时，图像将定位在锚点的左侧，这样，顾名思义，锚点就位于图像的右上角。

display:
  - platform: ...
    # ...
    lambda: |-
      // 默认左对齐
      it.image(0, 0, id(my_image));

      // 右边缘对齐
      it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT);

对于二进制图像，image 方法接受两个额外的颜色参数，可用于修改用于表示开和关位的颜色。例如：

display:
  - platform: ...
    # ...
    lambda: |-
      // 在位置 [x=0,y=0] 绘制图像 my_image
      // 前景色为红色，背景色为蓝色
      it.image(0, 0, id(my_image), id(red), id(blue));

      // 右边缘对齐
      it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue));

您也可以使用此方法在双色显示器上反转图像，将 COLOR_OFF 和 COLOR_ON 作为额外参数使用。

透明度选项

默认情况下不使用透明度。如果设置了 transparency: chroma_key，则将使用特定颜色替换图像的任何透明或半透明部分。渲染图像时不会绘制此部分，从而允许背景可见。

如果设置了 transparency: alpha_channel，则图像的每个像素将被分配一个额外的透明度值字节。这主要在使用 LVGL 时很有用，因为 alpha_channel 透明度将实现透明图像与背景的平滑混合。此选项不适用于二进制图像。使用显示 lambda 图像绘制函数时，这些函数将绘制或不绘制像素，不会与背景进行混合。带有 chroma_key 透明度的 BINARY 格式实际上将图像转换为每个像素一位的 alpha 蒙版。带有透明度的 GRAYSCALE 图像仅存储 alpha 通道，仍保持每像素 1 字节。