@kne/fastify-puppeteer 1.0.0 → 1.1.1

package/README.md

@@ -13,6 +13,54 @@
 npm i --save @kne/fastify-puppeteer
 ```
 
+
+### 概述
+
+### 项目简介
+
+fastify-puppeteer 是一个基于 Fastify 的插件，它集成了 Puppeteer 来提供强大的网页内容转换功能。该插件可以将 HTML 内容或 URL 转换为 PDF 文档或图片，支持单个转换和批量转换操作。
+
+### 主要特性
+
+- HTML 转 PDF：将 HTML 内容直接转换为 PDF 文档
+- HTML 转图片：将 HTML 内容转换为图片
+- URL 转 PDF：将指定 URL 的网页转换为 PDF 文档
+- URL 转图片：将指定 URL 的网页转换为图片
+- 批量处理：支持批量转换多个 HTML 内容或 URL
+- 并发控制：内置任务队列管理，控制最大并发任务数量
+- 缓存机制：支持文件缓存，提高转换效率
+
+### 技术架构
+
+#### 核心组件
+
+- **Fastify 插件**：提供 HTTP 接口和静态文件服务
+- **Puppeteer**：负责网页渲染和内容转换
+- **任务队列**：管理并发任务，防止系统过载
+- **文件缓存**：缓存转换结果，提高响应速度
+
+#### 工作流程
+
+1. 接收转换请求（HTML内容或URL）
+2. 通过任务队列管理器控制并发
+3. 使用 Puppeteer 打开页面并进行渲染
+4. 执行转换操作（PDF或图片）
+5. 返回转换结果
+
+### 配置选项
+
+- **maxTaskSize**：最大并发任务数，默认为 100
+- **puppeteerOptions**：Puppeteer 启动选项，用于配置浏览器行为
+- **cacheOptions**：文件缓存配置，控制缓存行为
+
+### 使用场景
+
+- 网页存档：将网页内容保存为 PDF 文档
+- 报表生成：将动态内容转换为 PDF 报表
+- 网页截图：捕获网页内容生成图片
+- 批量处理：批量转换多个网页或HTML内容
+
+
 ### 示例
 
 #### 示例代码
@@ -21,7 +69,225 @@ npm i --save @kne/fastify-puppeteer
 
 ### API
 
-| 属性名 | 说明 | 类型 | 默认值 |
-|-----|----|----|-----|
-|     |    |    |     |
+### API 接口文档
+
+本文档详细描述了 fastify-puppeteer 插件提供的所有 API 接口。
+
+#### 接口概览
+
+| 接口名称 | 请求方法 | 请求路径 | 描述 |
+|---------|---------|---------|------|
+| parseHtmlToPdf | POST | /parseHtmlToPdf | 将 HTML 内容转换为 PDF 文件 |
+| parseHtmlToPdfBatch | POST | /parseHtmlToPdfBatch | 批量将 HTML 内容转换为 PDF 文件（打包为 ZIP） |
+| parseHtmlToPhoto | POST | /parseHtmlToPhoto | 将 HTML 内容转换为图片 |
+| parseHtmlToPhotoBatch | POST | /parseHtmlToPhotoBatch | 批量将 HTML 内容转换为图片（打包为 ZIP） |
+| parseUrlToPdf | POST | /parseUrlToPdf | 将 URL 网页转换为 PDF 文件 |
+| parseUrlToPdfBatch | POST | /parseUrlToPdfBatch | 批量将 URL 网页转换为 PDF 文件（打包为 ZIP） |
+| parseUrlToPhoto | POST | /parseUrlToPhoto | 将 URL 网页转换为图片 |
+| parseUrlToPhotoBatch | POST | /parseUrlToPhotoBatch | 批量将 URL 网页转换为图片（打包为 ZIP） |
+
+#### 接口详情
+
+##### HTML 转换接口
+
+###### parseHtmlToPdf
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 将 HTML 内容转换为 PDF 文件 |
+| 请求方法 | POST |
+| 请求路径 | /parseHtmlToPdf |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| content | string | 是 | 需要转换的 HTML 内容 |
+| options | object | 否 | PDF 生成选项，参考 Puppeteer API |
+
+**响应结果：**
+- 返回生成的 PDF 文件流
+
+###### parseHtmlToPdfBatch
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 批量将 HTML 内容转换为 PDF 文件（打包为 ZIP） |
+| 请求方法 | POST |
+| 请求路径 | /parseHtmlToPdfBatch |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| contentList | array | 是 | 需要转换的 HTML 内容列表 |
+| options | object | 否 | PDF 生成选项，参考 Puppeteer API |
+
+**响应结果：**
+- 返回包含所有生成 PDF 的 ZIP 文件流
+
+###### parseHtmlToPhoto
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 将 HTML 内容转换为图片 |
+| 请求方法 | POST |
+| 请求路径 | /parseHtmlToPhoto |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| content | string | 是 | 需要转换的 HTML 内容 |
+| options | object | 否 | 图片生成选项，参考 Puppeteer API |
+
+**响应结果：**
+- 返回生成的图片文件流
+
+###### parseHtmlToPhotoBatch
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 批量将 HTML 内容转换为图片（打包为 ZIP） |
+| 请求方法 | POST |
+| 请求路径 | /parseHtmlToPhotoBatch |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| contentList | array | 是 | 需要转换的 HTML 内容列表 |
+| options | object | 否 | 图片生成选项，参考 Puppeteer API |
+
+**响应结果：**
+- 返回包含所有生成图片的 ZIP 文件流
+
+##### URL 转换接口
+
+###### parseUrlToPdf
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 将 URL 网页转换为 PDF 文件 |
+| 请求方法 | POST |
+| 请求路径 | /parseUrlToPdf |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| url | string | 是 | 需要转换的网页 URL |
+| options | object | 否 | PDF 生成选项，参考 Puppeteer API 和 URL 转换特有选项 |
+
+**响应结果：**
+- 返回生成的 PDF 文件流
+
+###### parseUrlToPdfBatch
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 批量将 URL 网页转换为 PDF 文件（打包为 ZIP） |
+| 请求方法 | POST |
+| 请求路径 | /parseUrlToPdfBatch |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| urlList | array | 是 | 需要转换的网页 URL 列表 |
+| options | object | 否 | PDF 生成选项，参考 Puppeteer API 和 URL 转换特有选项 |
+
+**响应结果：**
+- 返回包含所有生成 PDF 的 ZIP 文件流
+
+###### parseUrlToPhoto
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 将 URL 网页转换为图片 |
+| 请求方法 | POST |
+| 请求路径 | /parseUrlToPhoto |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| url | string | 是 | 需要转换的网页 URL |
+| selector | string | 否 | 页面元素选择器，指定截图区域。如果提供，将只截取该元素区域 |
+| options | object | 否 | 图片生成选项，参考 Puppeteer API 和 URL 转换特有选项 |
+
+**响应结果：**
+- 返回生成的图片文件流
+
+###### parseUrlToPhotoBatch
+
+| 项目 | 说明 |
+|------|------|
+| 接口描述 | 批量将 URL 网页转换为图片（打包为 ZIP） |
+| 请求方法 | POST |
+| 请求路径 | /parseUrlToPhotoBatch |
+| 认证方式 | 根据配置的 authenticate 函数 |
+| 请求参数 | JSON 对象 |
+
+**请求参数详情：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| urlList | array | 是 | 需要转换的网页 URL 列表 |
+| selector | string | 否 | 页面元素选择器，指定截图区域。如果提供，将只截取该元素区域 |
+| options | object | 否 | 图片生成选项，参考 Puppeteer API 和 URL 转换特有选项 |
+
+**响应结果：**
+- 返回包含所有生成图片的 ZIP 文件流
+
+### 选项参数说明
+
+#### PDF 生成选项
+
+PDF 生成选项参考 Puppeteer 的 [page.pdf()](https://pptr.dev/api/puppeteer.page.pdf) 方法参数，常用选项包括：
+
+| 选项名 | 类型 | 描述 |
+|-------|------|------|
+| format | string | 纸张格式，如 'A4', 'Letter' 等 |
+| width | string | 纸张宽度，如 '8.5in' |
+| height | string | 纸张高度，如 '11in' |
+| margin | object | 页面边距，包含 top, right, bottom, left 属性 |
+| printBackground | boolean | 是否打印背景图形 |
+| landscape | boolean | 是否使用横向打印 |
+
+#### 图片生成选项
+
+图片生成选项参考 Puppeteer 的 [page.screenshot()](https://pptr.dev/api/puppeteer.page.screenshot) 方法参数，常用选项包括：
+
+| 选项名 | 类型 | 描述 |
+|-------|------|------|
+| type | string | 图片格式，如 'png', 'jpeg' |
+| quality | number | 图片质量 (0-100)，仅适用于 JPEG |
+| fullPage | boolean | 是否捕获完整页面 |
+| clip | object | 裁剪区域，包含 x, y, width, height 属性 |
+| omitBackground | boolean | 是否隐藏默认白色背景 |
+
+#### URL 转换特有选项
+
+以下选项适用于 parseUrlToPdf、parseUrlToPdfBatch、parseUrlToPhoto 和 parseUrlToPhotoBatch 接口：
+
+| 选项名 | 类型 | 描述 |
+|-------|------|------|
+| waitForSelectors | array | 等待页面中特定元素出现的选择器数组，在继续处理前会等待这些元素加载完成 |
+| waitForVisible | boolean | 是否等待元素可见，默认为 false，仅检查元素是否存在于 DOM 中 |
+| waitForMaxTime | number | 等待元素出现的最大时间（毫秒），默认为 10000（10秒） |
 

package/index.js

@@ -1,5 +1,5 @@
 const fp = require('fastify-plugin');
-const path = require('path');
+const path = require('node:path');
 const packageJson = require('./package.json');
 const merge = require('lodash/merge');
 
@@ -11,6 +11,8 @@ module.exports = fp(
         prefix: `/api/v${packageJson.version.split('.')[0]}/puppeteer`,
         maxCacheKeys: 1000,
         maxTaskSize: 100,
+        pageWidth: 1366,
+        pageHeight: 768,
         puppeteerOptions: {},
         authenticate: []
       },
@@ -21,8 +23,10 @@ module.exports = fp(
       require('@fastify/static'),
       Object.assign({}, options.static, {
         root: options.root,
+        prefix: `${options.prefix}/static`,
         index: false,
-        list: false
+        list: false,
+        decorateReply: false
       })
     );
 

package/libs/controllers.js

@@ -1,4 +1,5 @@
 const fp = require('fastify-plugin');
+const path = require('node:path');
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify.puppeteer;
   fastify.post(
@@ -20,7 +21,7 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseHtmlToPdf({ html: request.body.content, options: request.body.options });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -51,7 +52,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.body.contentList,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -82,7 +83,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.body.contentList,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -108,7 +109,7 @@ module.exports = fp(async (fastify, options) => {
         html: request.body.content,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -131,7 +132,7 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseUrlToPdf({ url: request.body.url, options: request.body.options });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -157,7 +158,7 @@ module.exports = fp(async (fastify, options) => {
         urlList: request.body.urlList,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -180,12 +181,12 @@ module.exports = fp(async (fastify, options) => {
       }
     },
     async (request, reply) => {
-      const file = await services.parseUrlToPhoto({
+      const filename = await services.parseUrlToPhoto({
         url: request.body.url,
         selector: request.body.selector,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 
@@ -209,11 +210,11 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseUrlToPhotoBatch({
-        urlList: request.body.url,
+        urlList: request.body.urlList,
         selector: request.body.selector,
         options: request.body.options
       });
-      return reply.sendFile(filename);
+      return reply.sendFile(filename, { root: options.root });
     }
   );
 });

package/libs/core/setup.js

@@ -1,5 +1,5 @@
 const puppeteer = require('puppeteer');
-const createDeferred = require('./createDeferred');
+const createDeferred = require('@kne/create-deferred');
 
 module.exports = async options => {
   options = Object.assign({ maxTaskSize: 100 }, options);
@@ -9,7 +9,7 @@ module.exports = async options => {
     task: async callback => {
       return await deferred(async () => {
         const page = await browser.newPage();
-        await page.setViewport({ width: 1366, height: 768 });
+        await page.setViewport({ width: options.pageWidth, height: options.pageHeight });
         const output = await (async () => {
           try {
             return {

package/libs/core/setup.test.js

@@ -2,7 +2,7 @@ const setup = require('./setup');
 (async () => {
   const puppeteerPage = await setup({
     puppeteerOptions: {
-      executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+      executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
     }
   });
 

package/libs/services.js

@@ -73,11 +73,19 @@ module.exports = fp(async (fastify, options) => {
     });
   });
 
-  const parseUrlToPdf = memoCache('parseUrlToPdf', async ({ url, options }) => {
+  const parseUrlToPdf = memoCache('parseUrlToPdf', async ({ url, options = {} }) => {
     return await puppeteerPage.task(async ({ page }) => {
       await page.goto(url, {
         waitUntil: 'networkidle2'
       });
+      await Promise.all(
+        (options.waitForSelectors || []).map(waitForSelector => {
+          return page.waitForSelector(waitForSelector, {
+            visible: options.waitForVisible || false,
+            timeout: options.waitForMaxTime || 10000
+          });
+        })
+      );
       return await page.pdf(
         Object.assign(
           {},
@@ -98,11 +106,19 @@ module.exports = fp(async (fastify, options) => {
     });
   });
 
-  const parseUrlToPhoto = memoCache('parseUrlToPhoto', async ({ url, selector, options }) => {
+  const parseUrlToPhoto = memoCache('parseUrlToPhoto', async ({ url, selector, options = {} }) => {
     return await puppeteerPage.task(async ({ page }) => {
       await page.goto(url, {
         waitUntil: 'networkidle2'
       });
+      await Promise.all(
+        (options.waitForSelectors || []).map(waitForSelector => {
+          return page.waitForSelector(waitForSelector, {
+            visible: options.waitForVisible || false,
+            timeout: options.waitForMaxTime || 10000
+          });
+        })
+      );
       if (selector) {
         await page.locator(selector).wait();
         const element = await page.$(selector);

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@kne/fastify-puppeteer",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "用于操作无头浏览器截图保存pdf等",
   "main": "index.js",
   "scripts": {
     "init": "husky",
     "dev": "nodemon ./tests/server.js",
     "start": "node ./index.js",
-    "doc": "node ./open-api.js",
     "build:md": "npx @kne/md-doc",
     "start:md": "npx @kne/md-doc --watch",
     "prettier": "prettier --config .prettierrc --write '{libs/**/*,index}.{js,jsx,ts,tsx,json,css,scss}'",
@@ -37,12 +36,14 @@
     "url": "https://github.com/kne-union/fastify-puppeteer/issues"
   },
   "homepage": "https://github.com/kne-union/fastify-puppeteer#readme",
+  "peerDependencies": {
+    "@kne/fastify-namespace": "*",
+    "fastify-plugin": ">=5"
+  },
   "dependencies": {
-    "@fastify/static": "^7.0.4",
-    "@kne/fastify-namespace": "^0.1.1",
+    "@fastify/static": "^8.2.0",
+    "@kne/create-deferred": "^0.1.1",
     "compressing": "^1.10.1",
-    "fastify": "^4.27.0",
-    "fastify-plugin": "^4.5.1",
     "file-type": "^16.5.4",
     "fs-extra": "^11.2.0",
     "lodash": "^4.17.21",
@@ -53,11 +54,12 @@
     "uuid": "^10.0.0"
   },
   "devDependencies": {
-    "@fastify/swagger": "^8.14.0",
+    "@kne/fastify-namespace": "^1.1.2",
+    "fastify": "^5.4.0",
+    "fastify-plugin": "^5.0.1",
     "husky": "^9.0.11",
     "nodemon": "^3.1.3",
     "prettier": "^3.2.5",
-    "qs": "^6.12.1",
-    "sqlite3": "^5.1.7"
+    "qs": "^6.14.0"
   }
 }

package/libs/core/createDeferred.js

@@ -1,30 +0,0 @@
-const createDeferred = size => {
-  const queue = [];
-  let runningCount = 0;
-  const checkRun = () => {
-    if (queue.length === 0) {
-      runningCount = 0;
-      return;
-    }
-    if (runningCount < size) {
-      const callback = queue.shift();
-      runningCount += 1;
-      callback().finally(() => {
-        runningCount -= 1;
-        checkRun();
-      });
-    }
-  };
-  return callback => {
-    return new Promise(resolve => {
-      queue.push(() => {
-        const promise = Promise.resolve().then(() => callback());
-        resolve(promise);
-        return promise;
-      });
-      checkRun();
-    });
-  };
-};
-
-module.exports = createDeferred;