@oiij/js-pdf 0.0.10 → 0.0.11

package/README.md

@@ -1,12 +1,90 @@
-# Use JS-PDF
+# Use JS-PDF 🚀
 
 [![NPM version](https://img.shields.io/npm/v/@oiij/js-pdf)](https://www.npmjs.com/package/@oiij/js-pdf)
-[![MIT-license](https://img.shields.io/npm/l/@oiij/js-pdf)](https://github.com/Eiog/@oiij/js-pdf/blob/main/LICENSE)
+[![MIT-license](https://img.shields.io/npm/l/@oiij/js-pdf)](https://github.com/oiij/use/blob/main/packages/js-pdf/LICENSE)
 
-## Usage
+## 项目简介 📦
+
+Use JS-PDF 是基于 jsPDF 的 Vue 3 封装，提供便捷的 PDF 生成功能，帮助开发者在浏览器端快速生成和下载 PDF 文档。
+
+## 功能特点 ✨
+
+### PDF 生成 📄
+
+- 📝 支持文本、图片等多种内容
+- 🎨 提供丰富的样式配置
+- 💾 直接在浏览器端生成 PDF
+
+### 模块化设计 🧩
+
+- 📁 采用模块化架构，组件独立封装
+- 📦 支持按需导入，减小打包体积
+- 🔧 清晰的文件结构，易于维护和扩展
+
+### 类型安全 🔒
+
+- 📝 完整的 TypeScript 类型定义
+- 💡 提供准确的类型推断和代码提示
+- 🎯 支持 Vue 3 的 Composition API 类型系统
+
+### 轻量高效 ⚡
+
+- 🚀 核心代码精简，无额外依赖
+- 🏃 优化的性能表现，最小化运行时开销
+- 📦 支持 Tree Shaking，进一步减小打包体积
+
+## 安装 📥
+
+### 使用 pnpm 🐱
 
 ```bash
 pnpm add @oiij/js-pdf
 ```
 
-[在线文档](https://oiij-use.vercel.app/examples/js-pdf/started)
+### 使用 npm 📦
+
+```bash
+npm install @oiij/js-pdf
+```
+
+### 使用 yarn 🧶
+
+```bash
+yarn add @oiij/js-pdf
+```
+
+## 快速开始 🌟
+
+### 基础使用
+
+```vue
+<script setup>
+import { useJsPdf } from '@oiij/js-pdf'
+</script>
+
+<template>
+  <div />
+</template>
+```
+
+## 在线文档 📚
+
+[在线文档](https://oiij-use.vercel.app/js-pdf/js-pdf) 📖
+
+## 贡献指南 🤝
+
+欢迎贡献代码、报告问题或提出新功能建议！
+
+1. Fork 本仓库 🍴
+2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`) 🌿
+3. 提交您的更改 (`git commit -m 'Add some amazing feature'`) 💾
+4. 推送到分支 (`git push origin feature/amazing-feature`) 🚀
+5. 打开一个 Pull Request 📥
+
+## 许可证 📄
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 📑
+
+## 联系方式 📞
+
+- GitHub: [https://github.com/Eiog/@oiij/js-pdf](https://github.com/Eiog/@oiij/js-pdf) 🌟

package/dist/index.d.mts

@@ -2,14 +2,76 @@ import { HTMLFontFace, ImageOptions, TextOptions, jsPDF, jsPDFOptions } from "js
 import * as pdfjs_dist_types_src_display_api0 from "pdfjs-dist/types/src/display/api";
 
 //#region src/utils.d.ts
+/**
+ * 打开 PDF 文件
+ *
+ * @param url - PDF 文件的 URL 或 File 对象
+ * @returns PDF 文档、页面、ID 和画布
+ *
+ * @example
+ * ```ts
+ * import { openPdf } from '@oiij/js-pdf'
+ *
+ * // 从 URL 打开
+ * const { pdf, canvases } = await openPdf('https://example.com/file.pdf')
+ *
+ * // 从 File 对象打开
+ * const file = document.querySelector('input[type="file"]').files[0]
+ * const { pdf, canvases } = await openPdf(file)
+ * ```
+ */
 declare function openPdf(url?: string | URL | File): Promise<{
   pdf: pdfjs_dist_types_src_display_api0.PDFDocumentProxy;
   pages: pdfjs_dist_types_src_display_api0.PDFPageProxy[];
   id: string;
   canvases: HTMLCanvasElement[];
 } | undefined>;
+/**
+ * 将画布转换为 PDF
+ *
+ * @param canvases - 画布数组
+ * @param fileName - 文件名
+ *
+ * @example
+ * ```ts
+ * import { canvas2Pdf } from '@oiij/js-pdf'
+ *
+ * // 将画布数组转换为 PDF 并保存
+ * canvas2Pdf(canvases, 'output.pdf')
+ * ```
+ */
 declare function canvas2Pdf(canvases: HTMLCanvasElement[], fileName: string): void;
+/**
+ * 将画布转换为 ZIP 文件
+ *
+ * @param canvases - 画布数组
+ * @param fileName - 文件名
+ * @returns Promise<Blob[]>
+ *
+ * @example
+ * ```ts
+ * import { canvas2Zip } from '@oiij/js-pdf'
+ *
+ * // 将画布数组转换为 ZIP 并保存
+ * await canvas2Zip(canvases, 'output')
+ * ```
+ */
 declare function canvas2Zip(canvases: HTMLCanvasElement[], fileName: string): Promise<unknown>;
+/**
+ * 读取 PDF 文件
+ *
+ * @param buffer - PDF 文件的 ArrayBuffer
+ * @returns PDF 文档、页面、ID 和画布
+ *
+ * @example
+ * ```ts
+ * import { readPdfFile } from '@oiij/js-pdf'
+ *
+ * // 读取 PDF 文件缓冲区
+ * const buffer = await file.arrayBuffer()
+ * const { pdf, canvases } = await readPdfFile(buffer)
+ * ```
+ */
 declare function readPdfFile(buffer: ArrayBuffer): Promise<{
   pdf: pdfjs_dist_types_src_display_api0.PDFDocumentProxy;
   pages: pdfjs_dist_types_src_display_api0.PDFPageProxy[];
@@ -18,48 +80,178 @@ declare function readPdfFile(buffer: ArrayBuffer): Promise<{
 }>;
 //#endregion
 //#region src/index.d.ts
+/**
+ * 颜色类型
+ */
 type Color = string | [number, number, number, number];
+/**
+ * 文本样式类型
+ */
 type TextStyle = {
+  /**
+   * 字体大小
+   */
   fontSize?: number;
+  /**
+   * 字体名称
+   */
   fontName?: string;
+  /**
+   * 字体样式
+   */
   fontStyle?: HTMLFontFace['style'];
+  /**
+   * 字体粗细
+   */
   fontWeight?: HTMLFontFace['weight'];
+  /**
+   * 文本颜色
+   */
   textColor?: Color;
 };
+/**
+ * 绘制样式类型
+ */
 type DrawStyle = {
+  /**
+   * 绘制颜色
+   */
   drawColor?: Color;
+  /**
+   * 填充颜色
+   */
   fillColor?: Color;
+  /**
+   * 字符间距
+   */
   charSpace?: number;
+  /**
+   * 线宽
+   */
   lineWidth?: number;
+  /**
+   * 样式
+   */
   style?: 'S' | 'F' | 'FD' | 'DF' | null;
 };
+/**
+ * PDF 样式类型
+ */
 type PDFStyle = TextStyle & DrawStyle & {};
+/**
+ * PDF 数据类型
+ */
 type PDFDataType = 'text' | 'image' | 'circle' | 'line' | 'lines';
+/**
+ * 文本选项类型
+ */
 type OTextOptions = TextOptions & TextStyle;
+/**
+ * 图片选项类型
+ */
 type OImageOptions = Omit<ImageOptions, 'imageData'> & {
+  /**
+   * 图片数据
+   */
   imageData: ImageOptions['imageData'] | (() => ImageOptions['imageData']) | (() => Promise<ImageOptions['imageData']>);
 };
+/**
+ * 圆形选项类型
+ */
 type OCircleOptions = DrawStyle & {
+  /**
+   * x 坐标
+   */
   x: number;
+  /**
+   * y 坐标
+   */
   y: number;
+  /**
+   * 半径
+   */
   r: number;
 };
+/**
+ * 线段选项类型
+ */
 type OLineOptions = DrawStyle & {
+  /**
+   * 起点 x 坐标
+   */
   x1: number;
+  /**
+   * 起点 y 坐标
+   */
   y1: number;
+  /**
+   * 终点 x 坐标
+   */
   x2: number;
+  /**
+   * 终点 y 坐标
+   */
   y2: number;
 };
+/**
+ * 多线段选项类型
+ */
 type OLinesOptions = DrawStyle & {
+  /**
+   * 线段数组
+   */
   lines: number[][];
+  /**
+   * x 坐标
+   */
   x: number;
+  /**
+   * y 坐标
+   */
   y: number;
+  /**
+   * 缩放比例
+   */
   scale?: [number, number];
+  /**
+   * 是否闭合
+   */
   closed?: boolean;
 };
+/**
+ * PDF 数据行类型
+ */
 type PDFDataRow<T extends PDFDataType = PDFDataType> = {
+  /**
+   * 数据类型
+   */
   type: T;
 } & (T extends 'text' ? OTextOptions : T extends 'image' ? OImageOptions : T extends 'circle' ? OCircleOptions : T extends 'line' ? OLineOptions : T extends 'lines' ? OLinesOptions : never);
+/**
+ * 生成 PDF
+ *
+ * @param data - PDF 数据行数组
+ * @param options - jsPDF 选项
+ * @param globalStyle - 全局样式
+ * @returns PDF 实例
+ *
+ * @example
+ * ```ts
+ * import { generatePDF } from '@oiij/js-pdf'
+ *
+ * const { pdf } = await generatePDF([
+ *   {
+ *     type: 'text',
+ *     text: 'Hello World',
+ *     x: 10,
+ *     y: 10
+ *   }
+ * ])
+ *
+ * // 保存 PDF
+ * pdf.save('example.pdf')
+ * ```
+ */
 declare function generatePDF(data: PDFDataRow[], options?: jsPDFOptions, globalStyle?: PDFStyle): Promise<{
   pdf: jsPDF;
 }>;

package/dist/index.mjs

@@ -58,6 +58,24 @@ async function pdf2Canvases(pdf) {
 		return Promise.reject(error);
 	}
 }
+/**
+* 打开 PDF 文件
+*
+* @param url - PDF 文件的 URL 或 File 对象
+* @returns PDF 文档、页面、ID 和画布
+*
+* @example
+* ```ts
+* import { openPdf } from '@oiij/js-pdf'
+*
+* // 从 URL 打开
+* const { pdf, canvases } = await openPdf('https://example.com/file.pdf')
+*
+* // 从 File 对象打开
+* const file = document.querySelector('input[type="file"]').files[0]
+* const { pdf, canvases } = await openPdf(file)
+* ```
+*/
 async function openPdf(url) {
 	try {
 		if (url && (typeof url === "string" || url instanceof URL)) {
@@ -97,6 +115,20 @@ function canvas2Blob(canvas) {
 		}
 	});
 }
+/**
+* 将画布转换为 PDF
+*
+* @param canvases - 画布数组
+* @param fileName - 文件名
+*
+* @example
+* ```ts
+* import { canvas2Pdf } from '@oiij/js-pdf'
+*
+* // 将画布数组转换为 PDF 并保存
+* canvas2Pdf(canvases, 'output.pdf')
+* ```
+*/
 function canvas2Pdf(canvases, fileName) {
 	let doc = null;
 	canvases.forEach((canvas, i) => {
@@ -113,6 +145,21 @@ function canvas2Pdf(canvases, fileName) {
 		return doc;
 	});
 }
+/**
+* 将画布转换为 ZIP 文件
+*
+* @param canvases - 画布数组
+* @param fileName - 文件名
+* @returns Promise<Blob[]>
+*
+* @example
+* ```ts
+* import { canvas2Zip } from '@oiij/js-pdf'
+*
+* // 将画布数组转换为 ZIP 并保存
+* await canvas2Zip(canvases, 'output')
+* ```
+*/
 function canvas2Zip(canvases, fileName) {
 	return new Promise((resolve, reject) => {
 		const zip = new JsZip();
@@ -127,6 +174,21 @@ function canvas2Zip(canvases, fileName) {
 		}).catch((error) => reject(error));
 	});
 }
+/**
+* 读取 PDF 文件
+*
+* @param buffer - PDF 文件的 ArrayBuffer
+* @returns PDF 文档、页面、ID 和画布
+*
+* @example
+* ```ts
+* import { readPdfFile } from '@oiij/js-pdf'
+*
+* // 读取 PDF 文件缓冲区
+* const buffer = await file.arrayBuffer()
+* const { pdf, canvases } = await readPdfFile(buffer)
+* ```
+*/
 async function readPdfFile(buffer) {
 	const pdf = await getDocument(buffer).promise;
 	const { pages, id, canvases } = await pdf2Canvases(pdf);
@@ -148,6 +210,31 @@ function setDrawStyle(pdf, data) {
 	else pdf.setDrawColor(...drawColor);
 	pdf.setLineWidth(lineWidth);
 }
+/**
+* 生成 PDF
+*
+* @param data - PDF 数据行数组
+* @param options - jsPDF 选项
+* @param globalStyle - 全局样式
+* @returns PDF 实例
+*
+* @example
+* ```ts
+* import { generatePDF } from '@oiij/js-pdf'
+*
+* const { pdf } = await generatePDF([
+*   {
+*     type: 'text',
+*     text: 'Hello World',
+*     x: 10,
+*     y: 10
+*   }
+* ])
+*
+* // 保存 PDF
+* pdf.save('example.pdf')
+* ```
+*/
 async function generatePDF(data, options, globalStyle) {
 	const pdf = new jsPDF(options);
 	const font = pdf.getFont();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oiij/js-pdf",
   "type": "module",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "A simple PDF library for JavaScript",
   "author": "oiij",
   "license": "MIT",