# htmlToImage

**Repository Path**: gitzzr/html-to-image

## Basic Information

- **Project Name**: htmlToImage
- **Description**: 使用Puppeteer将HTML转换为图片的工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-02
- **Last Updated**: 2025-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTML转图片工具

这是一个使用Puppeteer将HTML页面转换为图片的工具项目。该项目包含完整的Node.js命令行工具和PHP集成类，让您可以轻松将HTML转换为各种格式的图片。

## 项目特点

- 使用Puppeteer自动控制Chromium浏览器
- 支持动态JavaScript内容渲染
- 捕获整个页面和特定元素的截图
- 支持透明背景图片生成
- 支持模板数据动态注入
- 支持PNG和PDF输出
- 提供多种预设HTML海报模板
- 可配置输出图片类型
- 支持简化命令
- 提供完整的PHP集成类
- 强化的数据传递方式，解决跨平台兼容问题

## 项目结构

- `html2image.js`: 使用Puppeteer将HTML转换为图片的主脚本
- `HtmlToImageService.php`: PHP集成类，用于在PHP项目中调用Node.js工具
- `templates/`: 预设HTML海报模板目录
  - `basic-poster.html`: 基础海报模板
  - `product-poster.html`: 商品海报模板
  - `event-poster.html`: 活动海报模板
  - `member-poster.html`: 会员邀请海报模板
- `scripts/`: 辅助脚本目录
  - `clean-output.js`: 清理输出目录的脚本
  - `batch-generate.js`: 批量生成海报的脚本
- `examples/`: 示例代码目录
  - `template-usage.php`: PHP调用示例，展示如何使用模板生成海报
  - `batch-config.json`: 批量生成海报的配置示例
- `output/`: 输出目录，存放生成的图片和PDF文件

## 安装依赖

确保已安装Node.js和PHP，然后运行：

```bash
npm install
```

## 系统依赖

Puppeteer需要一些系统依赖才能正常运行Chrome浏览器。在不同的Linux发行版上，可能需要安装以下依赖：

### CentOS / TencentOS

```bash
# 安装Puppeteer所需的基本依赖
sudo yum install -y atk at-spi2-atk at-spi2-core pango libXcomposite libXcursor libXdamage libXext libXi libXtst cups-libs libXScrnSaver libXrandr alsa-lib libXrender mesa-libgbm
```

### Ubuntu / Debian

```bash
# 安装Puppeteer所需的基本依赖
sudo apt-get update
sudo apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2 libpango-1.0-0 libcairo2
```

如果遇到Chrome启动失败的错误，请检查错误信息中提到的缺少的库文件，并安装相应的依赖包。

通常，错误信息会类似于：
```
Error: Failed to launch the browser process!
/path/to/chrome: error while loading shared libraries: libXXX.so.X: cannot open shared object file: No such file or directory
```

## 命令行工具使用

### 基本用法

```bash
node html2image.js <HTML文件> [选项]
```

选项说明:
- `--output, -o`: 输出文件前缀
- `--transparent, -t`: 使用透明背景 (默认: true)
- `--data, -d`: 模板数据 (JSON/JSON5格式字符串)
- `--dataFile`: 从文件加载模板数据 (支持.js或.json文件)
- `--options`: 输出选项 (JSON/JSON5格式字符串)
- `--optionsFile`: 从文件加载输出选项 (支持.js或.json文件)

例如：

```bash
# 基本使用
node html2image.js test.html --output member_poster

# 指定透明背景选项
node html2image.js test.html --output test_poster --transparent false

# 使用JSON字符串作为模板数据
node html2image.js templates/member-poster.html --output custom_poster --data '{
  "userName": "小明",
  "shopName": "明亮智能店铺",
  "avatar": "https://robohash.org/xiaoming?set=set4&size=150x150",
  "storeLogo": "https://dummyimage.com/200x80/0066cc/ffffff&text=明亮店铺",
  "qrCode": "https://api.qrserver.com/v1/create-qr-code/?size=180x180&data=https://example.com/test",
  "template": 2,
  "background": "",
  "text": "诚邀您加入我们的VIP会员俱乐部，享受专属优惠与服务！",
  "isShopInfo": true,
  "isStoreLogo": true,
  "domain": "https://example.com"
} '

# 使用JSON文件作为模板数据
node html2image.js templates/member-poster.html --output custom_poster --dataFile data/templates/member-poster.json

# 使用JS文件作为模板数据
node html2image.js templates/member-poster.html --output custom_poster --dataFile data/templates/member-poster.js

# 使用JSON字符串设置输出选项
node html2image.js templates/member-poster.html --output member_poster --options '{"fullPage":false,"element":true,"elementWithBg":true,"pdf":false}'

# 使用JSON文件设置输出选项
node html2image.js templates/member-poster.html --output member_poster --optionsFile data/output-options.json

# 显示帮助信息
node html2image.js --help
```

### 预设命令

支持以下预设命令，方便快速使用：

```bash
# 只生成元素截图和带背景的元素截图
node html2image.js elements templates/member-poster.html [--output 输出文件前缀]

# 只生成元素截图
node html2image.js element-only templates/member-poster.html [--output 输出文件前缀]

# 生成所有类型输出
node html2image.js full templates/member-poster.html [--output 输出文件前缀]

# 只生成PDF
node html2image.js pdf-only templates/member-poster.html [--output 输出文件前缀]

# 显示帮助信息
node html2image.js --help
```

### 使用npm脚本

项目提供了简洁的npm脚本命令：

```bash
# 基本转换
npm run convert -- templates/member-poster.html --output poster   # 运行基本的转换命令

# 预设命令
npm run elements -- templates/member-poster.html --output <输出前缀>   # 只生成元素截图和带背景截图
npm run element-only -- templates/member-poster.html --output <输出前缀>  # 只生成元素截图
npm run full -- templates/member-poster.html --output <输出前缀>  # 生成所有输出格式
npm run pdf-only -- templates/member-poster.html --output <输出前缀>  # 只生成PDF

# 运行PHP示例
npm run example

# 批量生成和清理
npm run batch -- [配置文件路径]   # 批量生成多个海报图片
npm run clean         # 清空output目录中的所有文件（跨平台兼容）
```

## 配置输出选项

项目默认只生成元素截图和带背景的元素截图，你可以通过`outputOptions`参数控制生成哪些类型的图片。配置选项：

```json
{
  "fullPage": false,     // 是否输出完整页面截图 (默认: false)
  "element": true,       // 是否输出带透明背景的元素截图 (默认: true)
  "elementWithBg": true, // 是否输出带背景的元素截图 (默认: true)
  "pdf": false          // 是否输出PDF文件 (默认: false)
}
```

## 域名配置

在使用海报模板时，可能需要动态设置域名，特别是在不同的环境（开发、测试、生产）中使用同一套代码时。项目支持三种设置域名的方式：

### 1. 在构造函数中设置默认域名

```php
// 创建实例时设置默认域名
$htmlToImage = new HtmlToImageService(
    'node',                      // Node.js可执行文件路径
    null,                        // 使用默认脚本路径
    null,                        // 使用默认输出目录
    false,                       // 是否启用调试模式
    'https://dev.example.com'    // 设置默认域名
);
```

### 2. 使用setter方法修改默认域名

```php
// 创建实例
$htmlToImage = new HtmlToImageService();

// 设置默认域名
$htmlToImage->setDefaultDomain('https://test.example.com');
```

### 3. 在生成海报时动态传入域名

```php
// 生成海报时通过options参数指定域名
$result = $htmlToImage->generatePoster(
    'templates/member-poster.html',  // HTML模板文件
    $templateData,                   // 模板数据
    [
        'outputPrefix' => 'domain_example',    // 输出文件前缀
        'domain' => 'https://prod.example.com' // 生产环境域名
    ]
);
```

完整的域名配置示例参见 `/examples/use-domain.php`。

## 预设模板说明

项目提供了多种预设HTML模板，可以直接使用：

### 1. 基础海报模板 (basic-poster.html)

一个通用的海报模板，包含标题、副标题、正文、图片和底部信息等元素。

支持的模板数据：
```json
{
  "title": "海报标题",
  "subtitle": "海报副标题",
  "text": "海报正文内容",
  "price": "¥99.00",
  "background": "https://placehold.co/800x600?text=背景图片",
  "mainImage": "https://placehold.co/400x300?text=主图",
  "qrcode": "https://placehold.co/180x180?text=二维码",
  "tips": "扫码说明文字",
  "shopName": "店铺名称",
  "shopDesc": "店铺描述",
  "shopLogo": "https://placehold.co/200x100?text=店铺Logo",
  "isShowPrice": true,
  "isShowShopInfo": true
}
```

### 2. 商品海报模板 (product-poster.html)

专为商品展示设计的海报模板，包含商品图片、标题、描述、价格、折扣等信息。

支持的模板数据：
```json
{
  "title": "商品名称",
  "description": "商品描述",
  "price": "¥299",
  "originalPrice": "¥399",
  "discount": "7.5折",
  "productImage": "https://placehold.co/300x400?text=商品图片",
  "shopName": "店铺名称",
  "shopLogo": "https://placehold.co/200x100?text=店铺Logo",
  "qrcode": "https://placehold.co/180x180?text=二维码",
  "showDiscount": true
}
```

### 3. 活动海报模板 (event-poster.html)

为促销活动设计的海报模板，包含活动标题、日期、折扣信息等。

支持的模板数据：
```json
{
  "title": "活动标题",
  "date": "活动日期",
  "discountValue": "折扣力度",
  "discountDescription": "折扣描述",
  "description": "活动详情描述",
  "shopName": "店铺名称",
  "shopAddress": "店铺地址",
  "shopLogo": "https://placehold.co/200x100?text=店铺Logo",
  "qrcode": "https://placehold.co/180x180?text=二维码",
  "qrcodeText": "二维码说明",
  "limitedTimeTag": "限时标签文字",
  "showLimitedTimeTag": true,
  "backgroundColor": "背景颜色或渐变"
}
```

### 4. 会员邀请海报模板 (member-poster.html)

专为会员邀请设计的海报模板，有两种不同样式。

支持的模板数据：
```json
{
  "template": 1,  // 样式选择：1或2
  "background": "https://placehold.co/800x600?text=背景图片",
  "text": "邀请文案",
  "isShopInfo": 1,  // 是否显示店铺信息：0或1
  "isStoreLogo": 1  // 是否显示店铺Logo：0或1
}
```

## PHP集成

项目提供了完整的PHP集成类`HtmlToImageService.php`，可以轻松地在PHP项目中使用。该类已针对新增的`--dataFile`和`--optionsFile`参数进行了优化，确保PHP和Node.js之间的数据传递更可靠，特别是在Windows环境下。

### 基本用法

```php
<?php
// 引入服务类
require_once 'HtmlToImageService.php';

// 创建实例
$htmlToImage = new HtmlToImageService();

// 从HTML文件生成海报
$result = $htmlToImage->generatePoster('templates/basic-poster.html');

if ($result['success']) {
  echo "海报生成成功！\n";
  print_r($result['files']);
} else {
  echo "生成失败: " . $result['error'] . "\n";
}
?>
```

### 使用模板数据

```php
<?php
// 引入服务类
require_once 'HtmlToImageService.php';

// 创建实例
$htmlToImage = new HtmlToImageService();

// 准备模板数据
$templateData = [
  'title' => '限时特惠活动',
  'subtitle' => '只在本周末',
  'text' => '这是一个超值促销活动，全场商品8折起!',
  'price' => '¥199.00',
  'shopName' => '优品商城',
  'shopDesc' => '品质生活从这里开始'
];

// 设置输出选项
$outputOptions = [
  'fullPage' => false,
  'element' => true,
  'elementWithBg' => true,
  'pdf' => false
];

// 生成海报
$result = $htmlToImage->generateFromTemplate(
  'templates/basic-poster.html',
  'special_offer',
  $templateData,
  true,
  $outputOptions
);

if ($result['success']) {
  echo "海报生成成功！\n";
  foreach ($result['files'] as $type => $path) {
    if ($path) {
      echo "- {$type}: {$path}\n";
    }
  }
} else {
  echo "生成失败: " . $result['error'] . "\n";
}
?>
```

### 跨平台兼容

`HtmlToImageService`类处理了不同操作系统下命令行参数的差异，无论是在Linux/macOS还是Windows环境下，都能正确传递复杂的JSON数据。类内部实现了自动检测操作系统并使用最佳的参数传递方式：

1. 在Windows环境中，使用临时JSON文件传递数据，避免命令行参数中的引号和转义问题
2. 通过新增的`--dataFile`和`--optionsFile`参数，从文件中加载模板数据和输出选项
3. 自动清理临时文件，避免文件系统占用

### 调试模式

如果在使用过程中遇到问题，可以开启调试模式查看详细的执行信息：

```php
// 方法1：在创建实例时开启调试模式
$htmlToImage = new HtmlToImageService('node', null, null, true);

// 方法2：通过方法开启调试模式
$htmlToImage = new HtmlToImageService();
$htmlToImage->setDebug(true);
```

调试模式将输出以下信息：
- 创建的临时文件路径
- 执行的命令行
- 命令执行结果
- 命令返回代码
- 错误信息（如果有）
- 清理过程

这些信息对于排查跨平台使用中的问题特别有帮助。

### 批量生成海报

```php
<?php
// 引入服务类
require_once 'HtmlToImageService.php';

// 创建实例
$htmlToImage = new HtmlToImageService();

// 模拟商品数据列表
$products = [
  [
    'title' => '商品1',
    'description' => '商品1的描述',
    'price' => '¥299',
    'originalPrice' => '¥399'
  ],
  [
    'title' => '商品2',
    'description' => '商品2的描述',
    'price' => '¥199',
    'originalPrice' => '¥299'
  ]
];

// 批量生成海报
foreach ($products as $index => $productData) {
  $result = $htmlToImage->generateFromTemplate(
    'templates/product-poster.html',
    "product_{$index}",
    $productData,
    true
  );
  
  if ($result['success']) {
    echo "商品 '{$productData['title']}' 海报生成成功！\n";
  }
}
?>
```

更多示例请参考`examples/template-usage.php`文件。

## 输出文件

脚本执行后，将在`output`目录中生成以下文件：

- `<前缀>_full.png`: 页面完整截图
- `<前缀>_element.png`: 仅海报元素区域的截图（透明背景，如果启用）
- `<前缀>_element_with_bg.png`: 带白色背景的海报元素截图（仅当启用透明背景时生成）
- `<前缀>.pdf`: 整个页面的PDF版本

## 许可证

ISC 

## 批量生成海报

项目支持通过JSON配置文件批量生成多个海报图片。

### 配置文件格式

配置文件应包含一个数组，每个元素代表一个海报生成任务：

```json
[
  {
    "template": "templates/basic-poster.html",  // 模板文件路径
    "output": "basic_poster_1",                 // 输出文件前缀
    "data": {                                   // 模板数据(内联)
      "title": "海报标题",
      "subtitle": "海报副标题",
      "text": "海报内容"
    },
    "dataFile": "data/poster1.json",           // 也可使用数据文件(二选一)
    "transparent": true,                        // 是否使用透明背景
    "options": {                                // 输出选项(内联)
      "fullPage": false,
      "element": true,
      "elementWithBg": true,
      "pdf": false
    },
    "optionsFile": "config/options.json"       // 也可使用选项文件(二选一)
  },
  // 更多任务...
]
```

注意：
- 如果同时指定了`data`和`dataFile`，将优先使用`dataFile`
- 如果同时指定了`options`和`optionsFile`，将优先使用`optionsFile`
- 数据文件支持JSON文件和JS模块文件

### 使用方法

```bash
# 使用默认配置文件
npm run batch examples/batch-config.json

# 或直接运行脚本
node scripts/batch-generate.js examples/batch-config.json
```

### 示例配置

项目提供了一个示例配置文件：`examples/batch-config.json`，包含了所有模板的使用示例。

### 示例数据文件

项目提供了预设的数据文件示例，位于`data/templates`目录：

**会员海报JSON数据 (member-poster.json):**
```json
{
  "userName": "小明",
  "shopName": "明亮智能店铺",
  "template": 1,
  "text": "诚邀您加入我们的VIP会员俱乐部，享受专属优惠与服务！",
  "isShopInfo": true,
  "isStoreLogo": true
  // ...其他属性
}
```

**会员海报JS模块数据 (member-poster.js):**
```javascript
// 会员海报数据 - JS模块方式
module.exports = {
  userName: "张小姐",
  shopName: "张氏精品店",
  template: 2,
  text: "诚邀您成为我们的贵宾会员，专享VIP折扣与一对一贴心服务！",
  // ...其他属性
};
```

**输出选项文件 (output-options.json):**
```json
{
  "fullPage": false,
  "element": true,
  "elementWithBg": true,
  "pdf": true
}
```

## 免责声明

**重要提示：关于图片资源的版权问题**

本项目示例中使用的图片资源URL均为占位图片，仅供功能演示之用。在实际应用中，请注意：

1. 请确保您使用的所有图片资源（如背景图、Logo、二维码等）拥有合法的使用权或授权
2. 商业用途时，建议使用：
   - 您自己创建的原创图片
   - 您已购买授权的商业图片
   - 提供合适商业许可的免费图库（如Unsplash、Pexels等）
3. 在项目开发阶段，可以使用以下占位图服务进行测试：
   - https://placehold.co/
   - https://placeholder.com/
   - https://dummyimage.com/

请勿直接使用未经授权的第三方图片资源，以避免潜在的版权纠纷。

## 常见问题

### 1. Puppeteer启动失败

如果遇到类似以下错误：

```
Error: Failed to launch the browser process!
/root/.cache/puppeteer/chrome/linux-127.0.6533.88/chrome-linux64/chrome: error while loading shared libraries: libatk-bridge-2.0.so.0: cannot open shared object file: No such file or directory
```

这表明系统缺少Puppeteer运行Chrome所需的依赖库。请按照"系统依赖"部分安装相应的依赖包。

常见缺失的库文件及对应的包：

- `libatk-bridge-2.0.so.0` - 安装 `at-spi2-atk`
- `libgbm.so.1` - 安装 `mesa-libgbm`
- `libXcomposite.so.1` - 安装 `libXcomposite`
- `libXdamage.so.1` - 安装 `libXdamage`
- `libXrandr.so.2` - 安装 `libXrandr`

在安装依赖后，重新运行命令应能正常工作。

### 2. Windows环境下JSON参数问题

在Windows环境下使用命令行传递JSON数据时，可能会遇到引号转义问题。建议使用以下方法之一：

- 使用`--dataFile`和`--optionsFile`参数从文件加载数据
- 使用PHP集成类`HtmlToImageService`，它会自动处理跨平台兼容问题
- 如果必须在命令行中传递JSON，注意Windows中的双引号转义规则