在线图像组件

使用此组件，您可以定义将在运行时下载、解码和绘制的图像。

NOTE

当前支持的格式：

BMP 图像
- 1 位 / 二进制 / 黑白
- 24 位 / RGB
JPEG 图像，目前仅支持基线图像（不支持渐进式）
PNG 图像

WARNING

此组件需要相当数量的 RAM；用于下载图像和存储解码后的图像。在没有 PSRAM 的设备上可能可以工作，但不保证。

此组件依赖于 HTTP 请求；您在 http_request 组件上设置的配置选项也适用于此。

online_image:
  - url: "https://example.com/example.png"
    format: png
    id: my_online_image

配置变量

url (必需, url): 图像下载的 URL。
request_headers (可选, 映射): HTTP 头映射。值为可模板化。
id (必需, ID): 用于稍后在显示代码中引用图像的 ID。
format (必需): 图像编码的格式。
- BMP : 服务器上的图像以 BMP 格式编码。
- JPEG : 服务器上的图像以 JPEG 格式编码。
- PNG : 服务器上的图像以 PNG 格式编码。
resize (可选, 字符串): 如果设置，这将调整图像大小以适应给定的尺寸 WIDTHxHEIGHT 并保持纵横比。
placeholder (可选, ID): 在下载的图像尚未准备好时显示的图像的 ID。此占位符图像将不会被调整大小；无论 online_image 的 resize 选项值如何。
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。请参阅图像组件中关于透明度的讨论。
byte_order (可选, 字符串): 对于 RGB565 图像，像素被转换为 16 位值。默认情况下，这些值将以大端序（MSB 在前）存储，但您可以通过将 byte_order 设置为 little_endian 来覆盖此设置。选项为 big_endian（默认）和 little_endian。不适用于其他图像格式。
update_interval (可选, 整数): 当指定的时间过去后重新下载图像。默认为 never（即需要手动调用更新组件动作）。

高级选项：

buffer_size (可选, 整数): 明确指定解码时下载图像块所用的缓冲区大小。默认值（65536）对于大多数用例应该可以，但对于慢速连接，您可以尝试减小大小，以避免看门狗超时。

自动化

on_download_finished (可选, 自动化): 图像成功下载后执行的自动化。

变量 cached 是一个在 lambdas 中可用的布尔值，表示缓存状态：

true 表示图像从缓存加载（缓存命中）。
false 表示图像是新下载的（缓存未命中）。

缓存遵循标准 HTTP 机制（请参阅 HTTP 缓存），利用 Last-Modified 和 ETag 头。

例如：

online_image:
  - url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
    format: png
    id: my_online_image
    on_download_finished:
      lambda: |-
        if (cached) {
          ESP_LOGD("online_image", "Cache hit: using cached image");
        } else {
          ESP_LOGD("online_image", "Cache miss: fresh download");
        }

一个很好的例子是在下载成功后更新显示组件。

on_error (可选, 自动化): 下载或解码过程中发生错误时执行的自动化。

动作

`online_image.set_url` 动作

更改图像下载的 URL。除非 update 设置为 false，否则将自动触发重新下载。

配置变量

id (必需, ID): 要更新 URL 的图像。
url (必需, url): 下载图像的新 URL。
update (可选, 布尔值): 如果为 true，图像将在设置新 URL 后立即更新（获取）。如果为 false，URL 将被设置，但图像在您调用 update 动作之前不会更新。默认为 true

on_...:
  - online_image.set_url:
      id: my_online_image
      url: "https://www.example.com/new_image.png"
  - component.update: my_online_image

`online_image.release` 动作

释放图像当前使用的内存。可用于不同显示页面需要不同图像的情况，以避免在当前未显示的图像上浪费内存。

配置变量

id (必需, ID): 要更新 URL 的图像。

on_...:
  - online_image.release: my_online_image

示例

online_image:
  - url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
    format: png
    id: my_online_image
    on_download_finished:
      component.update: my_display

然后在代码中：

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

对于单色显示器，image 方法接受两个额外的颜色参数，可用于指定用于绘制亮像素和暗像素的颜色。在这种情况下，图像将在内部转换为灰度图像，然后根据内部定义的阈值转换为单色。

display:
  - platform: ...
    id: my_display
    # ...
    lambda: |-
      // 在位置 [x=0,y=0] 绘制图像 my_image
      // 前景色为 "OFF"，背景色为 "ON"
      it.image(0, 0, id(my_online_image), COLOR_OFF, COLOR_ON);

默认情况下，online_image 配置为不自动更新/下载图像；为了进行初始下载，您可以：

在 Wifi 组件的 on_connect: 动作中添加 component.update <image_id>。
明确设置 update_interval。
在 Interval 块中调用 component.update <image_id>。
在需要下载/更新图像的地方调用 component.update <image_id>。

wifi:
  on_connect:
    - component.update: my_online_image

在线图像组件

配置变量

自动化

动作

online_image.set_url 动作

配置变量

online_image.release 动作

配置变量

示例

另请参阅

`online_image.set_url` 动作

`online_image.release` 动作