@kne/fastify-puppeteer 1.1.7 → 1.1.8

package/libs/controllers.js

@@ -1,7 +1,9 @@
 const fp = require('fastify-plugin');
 const { decode } = require('plantuml-encoder');
+
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify.puppeteer;
+  const { photoSchema, pdfSchema } = services;
   fastify.post(
     `${options.prefix}/parseHtmlToPdf`,
     {
@@ -13,7 +15,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['content'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             content: { type: 'string' }
           }
         }
@@ -21,6 +23,7 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseHtmlToPdf({ html: request.body.content, options: request.body.options });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -33,13 +36,14 @@ module.exports = fp(async (fastify, options) => {
         type: 'object',
         required: ['content'],
         properties: {
-          options: { type: 'object' },
+          options: pdfSchema,
           content: { type: 'string' }
         }
       }
     },
     async (request, reply) => {
       const filename = await services.parseHtmlToPdf({ html: decode(request.query.content), options: request.query.options });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -55,7 +59,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['contentList'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             contentList: {
               type: 'array',
               items: {
@@ -71,6 +75,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.body.contentList,
         options: request.body.options
       });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -86,7 +91,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['contentList'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             contentList: {
               type: 'array',
               items: {
@@ -102,6 +107,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.query.contentList.map(item => decode(item)),
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -117,7 +123,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['contentList'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             contentList: {
               type: 'array',
               items: {
@@ -133,6 +139,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.body.contentList,
         options: request.body.options
       });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -148,7 +155,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['contentList'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             contentList: {
               type: 'array',
               items: {
@@ -164,6 +171,7 @@ module.exports = fp(async (fastify, options) => {
         htmlList: request.query.contentList.map(item => decode(item)),
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -179,7 +187,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['content'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             content: { type: 'string' }
           }
         }
@@ -190,6 +198,7 @@ module.exports = fp(async (fastify, options) => {
         html: request.body.content,
         options: request.body.options
       });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -205,7 +214,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['content'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             content: { type: 'string' }
           }
         }
@@ -216,6 +225,7 @@ module.exports = fp(async (fastify, options) => {
         html: decode(request.query.content),
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -231,7 +241,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['url'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             url: { type: 'string' }
           }
         }
@@ -239,6 +249,7 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseUrlToPdf({ url: request.body.url, options: request.body.options });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -254,7 +265,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['url'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             url: { type: 'string' }
           }
         }
@@ -262,6 +273,7 @@ module.exports = fp(async (fastify, options) => {
     },
     async (request, reply) => {
       const filename = await services.parseUrlToPdf({ url: request.query.url, options: request.query.options });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -277,7 +289,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['urlList'],
           properties: {
-            options: { type: 'object' },
+            options: pdfSchema,
             urlList: { type: 'array', items: { type: 'string' } }
           }
         }
@@ -288,6 +300,7 @@ module.exports = fp(async (fastify, options) => {
         urlList: request.query.urlList,
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -303,7 +316,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['url'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             url: { type: 'string' },
             selector: { type: 'string' }
           }
@@ -316,6 +329,7 @@ module.exports = fp(async (fastify, options) => {
         selector: request.body.selector,
         options: request.body.options
       });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -331,7 +345,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['url'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             url: { type: 'string' },
             selector: { type: 'string' }
           }
@@ -344,6 +358,7 @@ module.exports = fp(async (fastify, options) => {
         selector: request.query.selector,
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -359,7 +374,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['urlList'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             urlList: { type: 'array', items: { type: 'string' } },
             selector: { type: 'string' }
           }
@@ -372,6 +387,7 @@ module.exports = fp(async (fastify, options) => {
         selector: request.body.selector,
         options: request.body.options
       });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );
@@ -387,7 +403,7 @@ module.exports = fp(async (fastify, options) => {
           type: 'object',
           required: ['urlList'],
           properties: {
-            options: { type: 'object' },
+            options: photoSchema,
             urlList: { type: 'array', items: { type: 'string' } },
             selector: { type: 'string' }
           }
@@ -400,6 +416,7 @@ module.exports = fp(async (fastify, options) => {
         selector: request.query.selector,
         options: request.query.options
       });
+      request.query.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.query.filename)}`);
       return reply.sendFile(filename, { root: options.root });
     }
   );

package/libs/services.js

@@ -5,6 +5,181 @@ const compressing = require('compressing');
 const path = require('node:path');
 const createDeferred = require('@kne/create-deferred');
 
+const pdfSchema = {
+  type: 'object',
+  properties: {
+    scale: {
+      type: 'number',
+      description: '缩放比例（0.1-2.0）',
+      default: 1.0,
+      minimum: 0.1,
+      maximum: 2.0
+    },
+    displayHeaderFooter: {
+      type: 'boolean',
+      description: '显示页眉页脚（需配合 headerTemplate/footerTemplate）',
+      default: false
+    },
+    headerTemplate: {
+      type: 'string',
+      description: 'HTML 格式的页眉模板（需启用 displayHeaderFooter）',
+      default: ''
+    },
+    footerTemplate: {
+      type: 'string',
+      description: 'HTML 格式的页脚模板（需启用 displayHeaderFooter）',
+      default: ''
+    },
+    printBackground: {
+      type: 'boolean',
+      description: '打印背景图形和 CSS 颜色',
+      default: true
+    },
+    landscape: {
+      type: 'boolean',
+      description: '横向布局',
+      default: false
+    },
+    pageRanges: {
+      type: 'string',
+      description: "页面范围（如 '1-5, 8, 11-13'）",
+      default: ''
+    },
+    format: {
+      type: 'string',
+      description: "纸张格式（如 'A4', 'Letter'）",
+      enum: ['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6'],
+      default: 'A4'
+    },
+    width: {
+      type: ['string', 'number'],
+      description: "自定义宽度（如 '8.5in', '200px', 200）"
+    },
+    height: {
+      type: ['string', 'number'],
+      description: "自定义高度（如 '11in', '300px', 300）"
+    },
+    margin: {
+      type: 'object',
+      properties: {
+        top: {
+          type: ['string', 'number'],
+          description: "上边距（如 '1in', '20px'）",
+          default: '0.4in'
+        },
+        right: {
+          type: ['string', 'number'],
+          description: '右边距',
+          default: '0.4in'
+        },
+        bottom: {
+          type: ['string', 'number'],
+          description: '下边距',
+          default: '0.4in'
+        },
+        left: {
+          type: ['string', 'number'],
+          description: '左边距',
+          default: '0.4in'
+        }
+      },
+      additionalProperties: false
+    },
+    preferCSSPageSize: {
+      type: 'boolean',
+      description: '优先使用 CSS 定义的 @page 尺寸',
+      default: false
+    },
+    omitBackground: {
+      type: 'boolean',
+      description: '隐藏默认白色背景（需配合 printBackground: true）',
+      default: false
+    },
+    timeout: {
+      type: 'number',
+      description: '超时时间（毫秒）',
+      default: 30000
+    },
+    tagged: {
+      type: 'boolean',
+      description: '生成带标签的 PDF（增强可访问性）',
+      default: false
+    },
+    waitForMaxTime: { type: 'number' },
+    waitForVisible: { type: 'boolean' },
+    waitForSelector: {
+      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }]
+    }
+  },
+  additionalProperties: false
+};
+
+const photoSchema = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['png', 'jpeg', 'webp'],
+      description: '截图图片格式',
+      default: 'png'
+    },
+    quality: {
+      type: 'integer',
+      description: '图片质量（仅适用于 jpeg 和 webp），取值 0-100',
+      minimum: 0,
+      maximum: 100
+    },
+    fullPage: {
+      type: 'boolean',
+      description: '是否截取完整页面（包括滚动部分）',
+      default: true
+    },
+    clip: {
+      type: 'object',
+      description: '指定裁剪区域',
+      properties: {
+        x: {
+          type: 'number',
+          description: '裁剪区域左上角 x 坐标'
+        },
+        y: {
+          type: 'number',
+          description: '裁剪区域左上角 y 坐标'
+        },
+        width: {
+          type: 'number',
+          description: '裁剪区域宽度'
+        },
+        height: {
+          type: 'number',
+          description: '裁剪区域高度'
+        }
+      },
+      required: ['x', 'y', 'width', 'height'],
+      additionalProperties: false
+    },
+    omitBackground: {
+      type: 'boolean',
+      description: '是否隐藏默认白色背景（使背景透明），仅适用于 png 格式'
+    },
+    encoding: {
+      type: 'string',
+      enum: ['binary', 'base64'],
+      description: '返回数据的编码格式'
+    },
+    captureBeyondViewport: {
+      type: 'boolean',
+      description: '是否捕获视口外的内容（仅当 fullPage 为 true 时有效）'
+    },
+    waitForMaxTime: { type: 'number' },
+    waitForVisible: { type: 'boolean' },
+    waitForSelector: {
+      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }]
+    }
+  },
+  additionalProperties: false
+};
+
 module.exports = fp(async (fastify, options) => {
   const { maxCacheKeys, maxConcurrent, root } = options;
   const cache = await createCache(options);
@@ -147,6 +322,8 @@ module.exports = fp(async (fastify, options) => {
   };
 
   Object.assign(fastify.puppeteer.services, {
+    pdfSchema,
+    photoSchema,
     puppeteerPage,
     getFilePath,
     parseHtmlToPdf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-puppeteer",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "用于操作无头浏览器截图保存pdf等",
   "main": "index.js",
   "scripts": {