Online Image 组件

image 组件的 online_image 平台允许你定义在运行时下载、解码和绘制的图像。

NOTE

当前支持的格式：

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

WARNING

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

此组件依赖于 Http Request；你对 http_request 组件设置的配置选项在此同样适用。

image:
  - platform: online_image
    url: "https://example.com/example.png"
    format: PNG
    type: RGB565
    id: my_online_image

配置变量

url (必填, url)：下载图像的 URL。
request_headers (可选, mapping)：HTTP 标头映射。值支持 templatable。
id (必填, ID)：以后在 display 代码中引用图像的 ID。
format (必填)：图像编码的格式。
- AUTO：从下载的图像内容自动检测格式。
- BMP：服务器上的图像采用 BMP 格式编码。
- JPEG：服务器上的图像采用 JPEG 格式编码。
- PNG：服务器上的图像采用 PNG 格式编码。
resize (可选, string)：如果设置，这将把图像缩放到适合给定尺寸 WIDTHxHEIGHT 并保留宽高比。
placeholder (可选, ID)：另一个 image 的 ID，在下载图像尚未准备好时显示。此占位图像不会被缩放；无论 online_image 的 resize 选项值如何。
type (必填)：指定内部图像编码方式。
- BINARY：两种颜色，适用于 1 色显示器或色彩显示器中的 2 色图像。每像素使用 1 位，每字节 8 像素。仅支持 chroma_key 透明度。
- GRAYSCALE：全范围灰度。每像素使用 8 位，每字节 1 像素。
- RGB565：有损 RGB 颜色存储。每像素使用 2 字节，带 alpha 通道时为 3 字节。
- RGB：完整 RGB 颜色存储。每像素使用 3 字节，带 alpha 通道时为 4 字节。
transparency (可选)：如果设置，将考虑输入图像的 alpha 通道。可选值为 opaque（默认）、chroma_key 和 alpha_channel。参见 image 组件中关于透明度的讨论。
byte_order (可选, string)：对于 RGB565 图像，像素被转换为 16 位值。默认情况下它们将以小端字节序（低位优先）存储，但你可以通过将 byte_order 设置为 big_endian 来覆盖此设置。可选值为 little_endian（默认）和 big_endian。不适用于其他图像格式。
update_interval (可选, Time)：经过指定时间后重新下载图像。默认为 never（即需要手动调用更新组件操作）。

高级选项：

buffer_size (可选, int)：显式指定在下载图像数据块并解码时使用的缓冲区大小。默认值（65536）对大多数用例应该没问题，但对于慢速连接，你可以尝试减小大小以避免看门狗超时。

自动化

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

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

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

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

例如：

image:
  - platform: 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
    type: RGB565
    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 (可选, Automation)：在下载或解码期间发生错误时执行的自动化。

操作

`online_image.set_url` 操作

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

配置变量

id (必填, ID)：要更新 URL 的图像。
url (必填, url, templatable)：下载图像的新 URL。
update (可选, bool, templatable)：如果为 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

示例

image:
  - platform: 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
    type: RGB565
    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 组件

配置变量

自动化

操作

online_image.set_url 操作

配置变量

online_image.release 操作

配置变量

示例

参见

`online_image.set_url` 操作

`online_image.release` 操作