yz-yuki-plugin 2.0.1 → 2.0.2-1

package/lib/utils/config.js

@@ -5,6 +5,9 @@ import lodash from 'lodash';
 import path from 'path';
 import { _paths } from './paths.js';
 
+/**
+ * Config 类用于管理配置文件的读取和监听
+ */
 class Config {
     versionPath;
     defaultConfigPath;
@@ -14,13 +17,17 @@ class Config {
     watcher;
     constructor() {
         this.versionPath = path.join(_paths.pluginPath, 'CHANGELOG.md');
+        /** 默认设置 */
         this.defaultConfigPath = path.join(_paths.pluginPath, 'defaultConfig');
         this.defaultConfig = {};
+        /** 用户设置 */
         this.userConfigPath = path.join(_paths.pluginPath, 'config');
         this.userConfig = {};
+        /** 监听文件 */
         this.watcher = {};
         this.initConfigFiles();
     }
+    /** 操作并创建配置文件到指定目录 */
     initConfigFiles() {
         const configFiles = [
             {
@@ -54,6 +61,13 @@ class Config {
             }
         }
     }
+    /**
+     * 通用获取配置文件数据方法
+     * @param typeDir 配置文件目录类型对应路径 defaultConfig: defaultConfig 或 config: yunzai/data/yuki-plugin/config
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     * @returns {object} 配置数据
+     */
     getConfigData(typeDir, appDir, functionName) {
         const configFilePath = this.getConfigFilePath(typeDir, appDir, functionName);
         const key = `${typeDir}_${appDir}_${functionName}`;
@@ -63,6 +77,13 @@ class Config {
         this.watch(configFilePath, typeDir, appDir, functionName);
         return this[key];
     }
+    /**
+     * 获取配置文件路径
+     * @param typeDir 配置文件目录类型对应路径 defaultConfig: defaultConfig 或 config: yunzai/data/yuki-plugin/config
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     * @returns {string} 配置文件路径
+     */
     getConfigFilePath(typeDir, appDir, functionName) {
         if (typeDir === "defaultConfig") {
             return path.join(_paths.pluginPath, `${typeDir}`, `${appDir}`, `${functionName}.yaml`);
@@ -71,6 +92,13 @@ class Config {
             return path.join(_paths.botYukiData, `${typeDir}`, `${appDir}`, `${functionName}.yaml`);
         }
     }
+    /**
+     * 监听配置文件的变化
+     * @param configFilePath 文件路径
+     * @param typeDir 配置文件目录类型对应路径 defaultConfig: defaultConfig 或 config: yunzai/data/yuki-plugin/config
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     */
     watch(configFilePath, typeDir, appDir, functionName) {
         const key = `${typeDir}_${appDir}_${functionName}`;
         if (this.watcher[key])
@@ -85,14 +113,31 @@ class Config {
         });
         this.watcher[key] = watcher;
     }
+    /**
+     * 获取默认配置
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     */
     getDefaultConfig(appDir, functionName) {
         return this.getConfigData("defaultConfig", appDir, functionName);
     }
+    /**
+     * 获取用户配置
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     */
     getUserConfig(appDir, functionName) {
         const userConfigData = this.getConfigData("config", appDir, functionName);
         const defaultConfigData = this.getDefaultConfig(appDir, functionName);
         return lodash.merge({}, defaultConfigData, userConfigData);
     }
+    /**
+     * 保存配置文件
+     * @param typeDir 插件为起始的配置文件目录
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     * @param data 配置数据
+     */
     saveConfig(typeDir, appDir, functionName, data) {
         const filePath = this.getConfigFilePath(typeDir, appDir, functionName);
         if (lodash.isEmpty(data)) {
@@ -103,11 +148,19 @@ class Config {
             fs.writeFileSync(filePath, yamlContent, "utf8");
         }
     }
+    /**
+     * 更新并保存配置项
+     * @param appDir 配置app目录
+     * @param functionName 配置文件名称，不包含.yaml后缀
+     * @param key 配置项的键
+     * @param value 配置项的值
+     */
     updateConfigItem(appDir, functionName, key, value) {
         const config = this.getUserConfig(appDir, functionName);
-        config[key] = value;
-        this.saveConfig("config", appDir, functionName, config);
+        config[key] = value; // 更新配置项
+        this.saveConfig("config", appDir, functionName, config); // 保存更新后的配置
     }
+    /** 读取CHANGELOG.md文件，获取最新版本号*/
     getLatestVersion() {
         const content = fs.readFileSync(this.versionPath, 'utf-8');
         const versionPattern = /#\s(\d+\.\d+\.\d+)/g;

package/lib/utils/image.d.ts

@@ -1,7 +1,18 @@
 import { Picture, ComponentCreateOpsionType } from 'react-puppeteer';
 import { ScreenshotOptions } from '@/utils/puppeteer.render';
 export declare class Image extends Picture {
+    /**
+     * 初始化运行Puppeteer
+     */
     constructor();
+    /**
+   * @param uid 唯一标识符
+   * @param page 组件名称
+   * @param props 传入的组件参数
+   * @param ComponentCreateOpsion 组件创建选项
+   * @param ScreenshotOptions 截图选项
+   * @returns {false | {img: buffer[]}}
+   */
     renderPage<T = any>(uid: number | string, page: string, props?: T, ScreenshotOptions?: ScreenshotOptions, ComponentCreateOpsion?: ComponentCreateOpsionType): Promise<false | {
         img: Buffer[];
     }>;

package/lib/utils/image.js

@@ -3,14 +3,28 @@ import { Component, Picture, Puppeteer } from 'react-puppeteer';
 import { YukiPuppeteerRender } from './puppeteer.render.js';
 import * as index from '../components/index.js';
 
+// 初始化 组件渲染对象
 const com = new Component();
 const yukiPuppeteerRender = new YukiPuppeteerRender();
 class Image extends Picture {
+    /**
+     * 初始化运行Puppeteer
+     */
     constructor() {
+        // 继承实例
         super();
+        // start
         this.Pup = new Puppeteer();
         this.Pup.start();
     }
+    /**
+   * @param uid 唯一标识符
+   * @param page 组件名称
+   * @param props 传入的组件参数
+   * @param ComponentCreateOpsion 组件创建选项
+   * @param ScreenshotOptions 截图选项
+   * @returns {false | {img: buffer[]}}
+   */
     async renderPage(uid, page, props = {}, ScreenshotOptions, ComponentCreateOpsion) {
         const Page = index[page];
         return yukiPuppeteerRender.yukiScreenshot(com.compile({
@@ -21,6 +35,7 @@ class Image extends Picture {
         }), ScreenshotOptions);
     }
 }
+// 初始化 图片生成对象
 var Image$1 = new Image();
 
 export { Image, Image$1 as default };

package/lib/utils/paths.js

@@ -6,13 +6,13 @@ const thisFilePath = dirname(fileURLToPath(import.meta.url));
 const pluginPath = join(thisFilePath, '..', '..');
 const pluginName = basename(pluginPath);
 const _paths = {
-    root: _path,
-    botData: join(_path, 'data'),
-    botYukiData: join(_path, 'data/yuki-plugin'),
-    botTempPath: join(_path, 'temp'),
-    pluginPath,
-    pluginResources: join(pluginPath, 'resources'),
-    pluginName,
+    root: _path, // Bot根目录
+    botData: join(_path, 'data'), // BotData目录
+    botYukiData: join(_path, 'data/yuki-plugin'), // yuki-Data目录
+    botTempPath: join(_path, 'temp'), // Bot缓存目录
+    pluginPath, // yuki-plugin根目录
+    pluginResources: join(pluginPath, 'resources'), // yuki-plugin资源目录
+    pluginName, // 插件所在文件夹名称
 };
 
 export { _paths, pluginName };

package/lib/utils/puppeteer.render.d.ts

@@ -17,6 +17,21 @@ export type ScreenshotOptions = {
     saveHtmlfile?: boolean;
 };
 export declare class YukiPuppeteerRender extends Puppeteer {
+    /**
+     * 截图并返回buffer
+     * @param htmlPath 绝对路径
+     * @param tab 截图元素位 默认 body
+     * @param type 图片类型，默认png
+     * @param quality 清晰度，默认100
+     * @param timeout 响应检查，默认120000
+     * @param isSplit 是否分割图片 booelan，默认undefined，如果为undefined则截取整个页面为一张图片，如果为true则按照 pageSplitHeight 高度分割全部页面，如果为false则截取页面的第一个默认pageSplitHeight高度的页面
+     * @param pageSplitHeight 分割图片高度，默认 8000。
+     * @param pageWidth 页面宽度，默认 900
+     * @param addStyle 额外的 CSS 样式 示例 '.ql-editor { max-height: 100% !important; overflow-x: hidden; }'
+     * @param header 请求头 { [key: string]: string }，示例：{ 'referer': 'https://space.bilibili.com' }
+     * @param modelName 调用模块名称，默认yuki-plugin
+     * @returns {false | {img: buffer[]}}
+     */
     yukiScreenshot(htmlPath: string, Options?: ScreenshotOptions): Promise<false | {
         img: Buffer[];
     }>;

package/lib/utils/puppeteer.render.js

@@ -3,12 +3,28 @@ import fs__default from 'fs';
 import path from 'path';
 import { _paths } from './paths.js';
 
+// 该文件是 yuki-plugin 插件的截图类，继承了 Puppeteer 类，重写了 screenshot 方法，实现了截图的额外功能。
 class YukiPuppeteerRender extends Puppeteer {
+    /**
+     * 截图并返回buffer
+     * @param htmlPath 绝对路径
+     * @param tab 截图元素位 默认 body
+     * @param type 图片类型，默认png
+     * @param quality 清晰度，默认100
+     * @param timeout 响应检查，默认120000
+     * @param isSplit 是否分割图片 booelan，默认undefined，如果为undefined则截取整个页面为一张图片，如果为true则按照 pageSplitHeight 高度分割全部页面，如果为false则截取页面的第一个默认pageSplitHeight高度的页面
+     * @param pageSplitHeight 分割图片高度，默认 8000。
+     * @param pageWidth 页面宽度，默认 900
+     * @param addStyle 额外的 CSS 样式 示例 '.ql-editor { max-height: 100% !important; overflow-x: hidden; }'
+     * @param header 请求头 { [key: string]: string }，示例：{ 'referer': 'https://space.bilibili.com' }
+     * @param modelName 调用模块名称，默认yuki-plugin
+     * @returns {false | {img: buffer[]}}
+     */
     async yukiScreenshot(htmlPath, Options) {
         if (!(await this.isStart()))
             return false;
         let name = Options?.modelName ?? 'yuki-plugin';
-        let pageHeight = Options?.pageSplitHeight ?? 8000;
+        let pageHeight = Options?.pageSplitHeight ?? 8000; // 分割图片高度，默认 8000
         try {
             const page = await this.browser?.newPage().catch(err => {
                 logger.error(err);
@@ -19,6 +35,7 @@ class YukiPuppeteerRender extends Puppeteer {
                 width: Options?.pageWidth ?? 900,
                 height: 7500
             });
+            // 设置请求 Header
             if (Options?.header) {
                 await page.setExtraHTTPHeaders(Options.header);
             }
@@ -26,21 +43,24 @@ class YukiPuppeteerRender extends Puppeteer {
             const element = await page.$(Options?.tab ?? 'body');
             if (!element)
                 return false;
-            const boundingBox = await element.boundingBox();
-            const num = Options?.isSplit ? Math.ceil(boundingBox.height / pageHeight) : 1;
-            pageHeight = Math.round(boundingBox.height / num);
+            const boundingBox = await element.boundingBox(); // 获取内容区域的边界框信息
+            const num = Options?.isSplit ? Math.ceil(boundingBox.height / pageHeight) : 1; // 根据是否需要分片，计算分片数量，默认为 1
+            pageHeight = Math.round(boundingBox.height / num); //动态调整分片高度，防止过短影响观感。
             await page.setViewport({
                 width: boundingBox.width + 50,
                 height: pageHeight + 100
             });
+            // 根据 style 的值来修改 CSS 样式
             if (Options?.addStyle) {
                 await page.addStyleTag({
                     content: Options.addStyle,
                 });
             }
+            // 禁止 GIF 动图播放
             await page.addStyleTag({
                 content: `img[src$=".gif"] {animation-play-state: paused !important;}`
             });
+            // 是否保存 html 文件
             if (Options?.saveHtmlfile === true) {
                 const htmlContent = await page.content();
                 const Dir = path.join(_paths.root, `/temp/html/yuki-plugin/${name}/`);
@@ -57,30 +77,31 @@ class YukiPuppeteerRender extends Puppeteer {
             for (let i = 1; i <= num; i++) {
                 if (i > 1) {
                     await page.evaluate(pageHeight => {
-                        window.scrollBy(0, pageHeight);
+                        window.scrollBy(0, pageHeight); // 在页面上下文中执行滚动操作
                     }, pageHeight);
-                    await new Promise((resolve) => setTimeout(resolve, 500));
+                    await new Promise((resolve) => setTimeout(resolve, 500)); // 等待一段时间，确保页面加载完成
                 }
                 let renderOptions = Options?.SOptions ?? { type: 'png' };
                 const screenshotOptions = {
                     ...renderOptions,
                     clip: {
                         x: 0,
-                        y: pageHeight * (i - 1),
-                        width: Math.round(boundingBox.width),
-                        height: Math.min(pageHeight, boundingBox.height - pageHeight * (i - 1)),
+                        y: pageHeight * (i - 1), // 根据分片序号计算截图区域的起始位置
+                        width: Math.round(boundingBox.width), // 截图区域的宽度与内容区域宽度一致
+                        height: Math.min(pageHeight, boundingBox.height - pageHeight * (i - 1)), // 截图区域的高度取决于内容区域剩余的高度或者默认的分片高度
                     },
                 };
                 buff = await element.screenshot(screenshotOptions).catch(err => {
                     logger.error('[puppeteer]', 'screenshot', err);
                     return false;
-                });
-                numSun++;
+                }); // 对指定区域进行截图
+                numSun++; // 增加截图次数
                 if (buff !== false) {
                     let imgBuff = !Buffer.isBuffer(buff) ? Buffer.from(buff) : buff;
-                    const kb = (imgBuff?.length / 1024).toFixed(2) + "kb";
-                    logger.mark(`[图片生成][${name}][${numSun}次] ${kb} ${logger.green(`${Date.now() - start}ms`)}`);
-                    ret.push(imgBuff);
+                    /** 计算图片大小 */
+                    const kb = (imgBuff?.length / 1024).toFixed(2) + "kb"; // 计算图片大小
+                    logger.mark(`[图片生成][${name}][${numSun}次] ${kb} ${logger.green(`${Date.now() - start}ms`)}`); // 记录日志
+                    ret.push(imgBuff); // 将截图结果添加到数组中
                 }
                 else {
                     logger.error(`[puppeteer]`, '截图失败');
@@ -90,8 +111,9 @@ class YukiPuppeteerRender extends Puppeteer {
                 logger.error(`[图片生成][${name}] 图片生成为空`);
                 return false;
             }
+            // 关闭页面
             await page.close().catch(err => logger.error(err));
-            return { img: ret };
+            return { img: ret }; // 返回图像数组
         }
         catch (err) {
             logger.error('[puppeteer] newPage', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yz-yuki-plugin",
-  "version": "2.0.1",
+  "version": "2.0.2-1",
   "description": "优纪插件，yunzaijs 关于 微博推送、B站推送 等功能的拓展插件",
   "author": "snowtafir",
   "type": "module",
@@ -17,7 +17,8 @@
     "css-app": "tailwindcss -i ./src/input.css -o ./public/output.css",
     "css-dev": "tailwindcss -i ./src/input.css -o ./public/output.css --watch",
     "css-m": "tailwindcss -i ./src/input.css -o ./public/output.css -m",
-    "format": "prettier --write ."
+    "format": "prettier --write .",
+    "check-format": "git diff --exit-code"
   },
   "dependencies": {
     "axios": "^1.7.3",
@@ -33,7 +34,7 @@
     "qrcode": "^1.5.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-puppeteer": "1.0.3",
+    "react-puppeteer": "^1.0.3",
     "redis": "^4.7.0",
     "yaml": "^2.5.0",
     "yarn": "^1.19.1"
@@ -84,9 +85,9 @@
     "rollup-plugin-ignore": "^1.0.10",
     "tailwindcss": "^3.4.9",
     "ts-node": "^10.9.2",
-    "tsx": "^4.18.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.5.4",
-    "yunzai": "^1.0.6",
+    "yunzai": "^1.1.3",
     "yunzai-mys": "^1.0.5"
   },
   "files": [