html-to-image-render

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML 转图片

HTML to Image

当任务是把本地

.html

文件通过远端

html2image

API 渲染成图片时，使用这个 skill。

When the task is to render local

.html

files into images via the remote

html2image

API, use this skill.

工作流

Workflow

从磁盘读取 HTML 文件内容。
如有必要，先查看
```
references/html-to-image-api.md
```
中的接口约定。
运行
```
scripts/render-html-to-image.ts
```
，传入输入 HTML 路径和输出图片路径。
确认生成的图片文件已经落到目标位置。

Read the content of the HTML file from disk.
If necessary, check the interface conventions in
```
references/html-to-image-api.md
```
first.
Run
```
scripts/render-html-to-image.ts
```
, passing in the input HTML path and output image path.
Confirm that the generated image file has been saved to the target location.

脚本说明

Script Description

内置脚本会完成这些事情：

以 UTF-8 读取 HTML 文件

调用

POST https://html2image.hanfangyuan.cn/api/html2image

解码返回的
```
image_base64
```
把图片写入本地磁盘

示例：

bash

npx -y tsx skills/html-to-image-render/scripts/render-html-to-image.ts \
  --input ./demo/card.html \
  --output ./out/card.png \
  --element-id card \
  --image-type png

执行这个脚本依赖本机可用的

npx

，并通过

npx -y tsx

临时执行 TypeScript 文件。首次运行时通常会下载

tsx

。

The built-in script will complete the following tasks:

Read HTML files in UTF-8 encoding

Call

POST https://html2image.hanfangyuan.cn/api/html2image

Decode the returned
```
image_base64
```
Write the image to local disk

Example:

bash

npx -y tsx skills/html-to-image-render/scripts/render-html-to-image.ts \
  --input ./demo/card.html \
  --output ./out/card.png \
  --element-id card \
  --image-type png

Running this script depends on the availability of

npx

on the local machine, and temporarily executes TypeScript files via

npx -y tsx

tsx

is usually downloaded on the first run.

参数说明

Parameter Description

必选参数

Required Parameters

```
--input
```
：输入的本地 HTML 文件路径。
```
--output
```
：输出图片文件路径。

```
--input
```
: Path of the input local HTML file.
```
--output
```
: Path of the output image file.

可选参数

Optional Parameters

```
--element-id
```
：要截图的元素 id，传原始 id 值，不要带
```
#
```
。
```
--image-type
```
：支持
```
png
```
和
```
jpeg
```
。
```
--device-scale-factor
```
：设备像素比，越大越清晰，但图片通常也更大。
```
--viewport-width
```
/
```
--viewport-height
```
：渲染视口尺寸。
```
--render-wait-ms
```
：截图前额外等待时间，适合等待字体、图片等异步资源。
```
--element-padding
```
：当指定
```
--element-id
```
时，为截图区域额外增加的边距，默认值为
```
0
```
。

```
--element-id
```
: The id of the element to be captured, pass the original id value without
```
#
```
.
```
--image-type
```
: Supports
```
png
```
and
```
jpeg
```
.
```
--device-scale-factor
```
: Device pixel ratio, the higher the value, the clearer the image, but the larger the image size usually is.
```
--viewport-width
```
/
```
--viewport-height
```
: Render viewport size.
```
--render-wait-ms
```
: Extra waiting time before taking a screenshot, suitable for waiting for asynchronous resources such as fonts and images.
```
--element-padding
```
: When
```
--element-id
```
is specified, the extra margin added to the screenshot area, the default value is
```
0
```
.

注意事项

Notes

运行环境需要可用的
```
npx
```
。
如果 HTML 中使用图片资源，需要使用公网可访问的图片链接，不支持本地图片路径。
输出文件扩展名应与
```
--image-type
```
保持一致。
要注意实际截图区域的尺寸是否能完整容纳目标 HTML。尤其当卡片宽高大于默认视口时，必须显式调整
```
--viewport-width
```
和
```
--viewport-height
```
，避免截图被裁切或图片不完整。
只有在默认渲染结果不满足需求时，再调整视口和等待时间参数；但如果 HTML 的设计尺寸本身就大于默认视口，应该优先先把视口调到不小于目标元素尺寸。
如果接口返回
```
400
```
，通常是
```
element_id
```
对应元素不存在。
如果接口返回
```
422
```
，通常是参数范围不合法。

The running environment requires available
```
npx
```
.
If image resources are used in HTML, publicly accessible image links are required, and local image paths are not supported.
The output file extension should be consistent with
```
--image-type
```
.
Pay attention to whether the size of the actual screenshot area can fully accommodate the target HTML. Especially when the width and height of the card are larger than the default viewport, you must explicitly adjust
```
--viewport-width
```
and
```
--viewport-height
```
to avoid cropped or incomplete screenshots.
Adjust the viewport and waiting time parameters only when the default rendering result does not meet the requirements; but if the design size of the HTML itself is larger than the default viewport, you should first adjust the viewport to be no smaller than the size of the target element.
If the interface returns
```
400
```
, usually the element corresponding to
```
element_id
```
does not exist.
If the interface returns
```
422
```
, usually the parameter range is invalid.