@kne/react-pdf-sign 1.0.6 → 1.1.0

package/README.md

@@ -16,7 +16,7 @@ npm i --save @kne/react-pdf-sign
 
 ### 概述
 
-这是一个功能强大的 React PDF 签名组件库，专为需要在 PDF 文档上添加电子签名的应用场景而设计。该组件库提供了灵活的签名解决方案，支持即时签名添加和预定义签名区域两种模式。
+这是一个功能强大的 React PDF 签名组件库，专为需要在 PDF 文档上添加电子签名的应用场景而设计。该组件库提供了灵活的签名解决方案，支持单签名位置和多签名位置两种模式，满足不同业务需求。
 
 ## 核心特性
 
@@ -24,9 +24,13 @@ npm i --save @kne/react-pdf-sign
 
 **灵活的定位控制** - 签名区域可以在 PDF 页面上自由拖拽、缩放和精确定位，支持保持比例缩放，确保签名的视觉效果。
 
+**多位置签名支持** - 支持在 PDF 文档的多个页面或同一页面的不同位置添加签名，通过 `PDFSignMulti` 组件实现批量签名管理，可动态添加、删除签名位置。
+
 **完整的 PDF 操作** - 基于 pdf-lib 和 react-pdf，支持多页 PDF 文档的浏览、签名定位和最终签名文件的生成。
 
-**组件化设计** - 提供多个独立组件（PDFSign、PDFViewer、LocationLayer、useSignature），开发者可以根据需求灵活组合使用。支持默认签名位置设置和位置变化回调，便于集成到现有业务流程。
+**组件化设计** - 提供多个独立组件（PDFSign、PDFSignMulti、PDFViewer、LocationLayer、useSignature），开发者可以根据需求灵活组合使用。支持默认签名位置设置和位置变化回调，便于集成到现有业务流程。
+
+**智能位置计算** - 内置 `computedPDFSignLocation` 和 `getInitLocation` 工具函数，自动处理显示坐标与 PDF 原始坐标的转换，简化开发复杂度。
 
 **国际化支持** - 内置中英文语言包，支持多语言切换，适合国际化应用。
 
@@ -34,13 +38,13 @@ npm i --save @kne/react-pdf-sign
 
 ## 使用场景
 
-- 合同签署系统
-- 文档审批流程
-- 电子表单签名
-- 证书颁发系统
-- 法律文件签署
+- 合同签署系统 - 支持多方签名位置预定义
+- 文档审批流程 - 单个或多个审批人签名
+- 电子表单签名 - 固定位置的表单签名
+- 证书颁发系统 - 多签名证书生成
+- 法律文件签署 - 多方见证签名
 
-该组件库简化了 PDF 签名的复杂实现，开发者只需要几行代码就能集成完整的签名功能，大大提升了开发效率。新增的签名叠加功能让签名更加丰富和个性化，满足各种业务场景需求。
+该组件库简化了 PDF 签名的复杂实现，开发者只需要几行代码就能集成完整的签名功能，大大提升了开发效率。新增的多位置签名功能和智能坐标计算让复杂场景的实现变得简单快捷。
 
 ### 示例
 
@@ -117,18 +121,210 @@ render(<BaseExample />);
 
 ```
 
+- 多位置PDF签名
+- 演示在同一PDF文档中添加多个签名位置的完整流程：1. 上传PDF文档；2. 在编辑模式下点击'添加签名位置'按钮为不同页面添加签名区域；3. 切换至非编辑模式进行签名；4. 完成所有签名后点击'生成签名PDF'导出已签名的文档
+- _ReactPdfSign(@kne/current-lib_react-pdf-sign)[import * as _ReactPdfSign from "@kne/react-pdf-sign"],antd(antd),(@kne/current-lib_react-pdf-sign/dist/index.css)
+
+```jsx
+const { PDFSignMulti, useSignature } = _ReactPdfSign;
+const { useState, useRef } = React;
+const { Flex, Button, Switch, App } = antd;
+
+const BaseExample = () => {
+  const [pdfFile, setPdfFile] = useState(null);
+  const [isEdit, setIsEdit] = useState(true);
+  const ref = useRef(null);
+  const signatureModal = useSignature();
+  const { message } = App.useApp();
+  return (
+    <Flex vertical gap={12}>
+      <Flex gap={8} align="center">
+        <Button>
+          <input
+            type="file"
+            accept="application/pdf"
+            onChange={e => {
+              const file = e.target.files[0];
+              setPdfFile(URL.createObjectURL(file));
+            }}
+          />
+        </Button>
+        {pdfFile && (
+          <Flex gap={8}>
+            <div>编辑模式:</div>
+            <Switch value={isEdit} onChange={setIsEdit} />
+          </Flex>
+        )}
+        {pdfFile && isEdit && (
+          <Button
+            onClick={() => {
+              ref.current.addSignLocation();
+            }}>
+            添加签名位置
+          </Button>
+        )}
+        {pdfFile && !isEdit && (
+          <Button
+            onClick={async () => {
+              try {
+                const blob = await ref.current.sign();
+                const link = document.createElement('a');
+                const url = URL.createObjectURL(blob);
+                link.href = url;
+                link.download = 'signed-document.pdf';
+                link.click();
+                URL.revokeObjectURL(url);
+              } catch (e) {
+                message.error(e.message);
+              }
+            }}>
+            生成签名PDF
+          </Button>
+        )}
+      </Flex>
+      {pdfFile ? (
+        <PDFSignMulti
+          url={pdfFile}
+          ref={ref}
+          isEdit={isEdit}
+          onSign={({ size, callback }) => {
+            signatureModal({
+              mask: (
+                <Flex justify="flex-end" align="flex-end" style={{ height: '100%', width: '100%', padding: '10px', boxSizing: 'border-box' }}>
+                  签字日期: {new Date().toLocaleDateString()}
+                </Flex>
+              ),
+              width: size.width,
+              height: size.height,
+              onSuccess: file => {
+                callback(URL.createObjectURL(file));
+              }
+            });
+          }}
+        />
+      ) : null}
+    </Flex>
+  );
+};
+
+render(<BaseExample />);
+
+```
+
 - 签名定位层
 - 展示独立的签名定位组件，支持拖拽和缩放调整签名位置
-- _ReactPdfSign(@kne/current-lib_react-pdf-sign)[import * as _ReactPdfSign from "@kne/react-pdf-sign"],(@kne/current-lib_react-pdf-sign/dist/index.css)
+- _ReactPdfSign(@kne/current-lib_react-pdf-sign)[import * as _ReactPdfSign from "@kne/react-pdf-sign"],antd(antd),(@kne/current-lib_react-pdf-sign/dist/index.css)
 
 ```jsx
-const { LocationLayer } = _ReactPdfSign;
+const { LocationLayer, LocationGroup } = _ReactPdfSign;
+const { Flex, Button, Switch, App } = antd;
+const { useState } = React;
+
+const defaultList = [
+  {
+    size: {
+      width: 200,
+      height: 80,
+      x: 325,
+      y: 78
+    },
+    scaleX: 1,
+    scaleY: 1,
+    x: 325,
+    y: 78
+  },
+  {
+    size: {
+      width: 200,
+      height: 80,
+      x: 44,
+      y: 78
+    },
+    scaleX: 1,
+    scaleY: 1,
+    x: 44,
+    y: 78
+  },
+  {
+    size: {
+      width: 200,
+      height: 80,
+      x: 126,
+      y: 206
+    },
+    scaleX: 1,
+    scaleY: 1,
+    x: 126,
+    y: 206
+  },
+  {
+    size: {
+      width: 200,
+      height: 195,
+      x: 129,
+      y: 308
+    },
+    scaleX: 1,
+    scaleY: 2.44,
+    x: 129,
+    y: 308
+  },
+  {
+    size: {
+      width: 135,
+      height: 217,
+      x: 355,
+      y: 182
+    },
+    scaleX: 0.67,
+    scaleY: 2.71,
+    x: 355,
+    y: 182
+  }
+];
 
 const BaseExample = () => {
+  const [value, setValue] = useState(defaultList);
+  const [isEdit, setIsEdit] = useState(true);
+  const { modal } = App.useApp();
   return (
-    <div>
-      <LocationLayer stageWidth={400} stageHeight={300} />
-    </div>
+    <Flex vertical gap={10}>
+      <LocationLayer stageWidth={600} stageHeight={400} />
+      <Flex vertical gap={4}>
+        <Flex gap={8} align="center">
+          <Button
+            onClick={() => {
+              setValue(value => {
+                return [...value, {}];
+              });
+            }}>
+            添加
+          </Button>
+          <Flex gap={4}>
+            <div>编辑模式:</div>
+            <Switch value={isEdit} onChange={setIsEdit} />
+          </Flex>
+        </Flex>
+        <LocationGroup
+          stageWidth={600}
+          stageHeight={600}
+          value={value}
+          onChange={setValue}
+          isEdit={isEdit}
+          placeholder={isEdit ? '签名区域' : '点击获取点击区域'}
+          onClick={output => {
+            modal.info({
+              title: '非编辑模式获取签名点击区域',
+              content: (
+                <div style={{ maxHeight: 400, overflow: 'auto' }}>
+                  <pre style={{ 'white-space': 'break-spaces' }}>{JSON.stringify(output, null, 2)}</pre>
+                </div>
+              )
+            });
+          }}
+        />
+      </Flex>
+    </Flex>
   );
 };
 
@@ -301,19 +497,19 @@ render(<BaseExample />);
 
 ### PDFSign
 
-主要的 PDF 签名组件，集成了 PDF 查看器和签名定位功能。
+主要的 PDF 签名组件，集成了 PDF 查看器和签名定位功能，适用于单签名场景。
 
-| 属性             | 类型       | 默认值              | 说明                |
-|----------------|----------|-------------------|-------------------|
-| url            | string   | -                 | PDF 文件的 URL 地址    |
-| signature      | string   | -                 | 签名图片的 URL 地址      |
-| width          | number   | 200               | 签名区域的宽度           |
-| height         | number   | 50                | 签名区域的高度           |
-| padding        | number   | 8                 | 签名区域变换器的内边距       |
-| placeholder    | string   | '拖拽到签名位置'        | 签名区域的占位文本         |
-| filename       | string   | 'signed-document.pdf' | 生成签名PDF的文件名       |
-| defaultLocation | object   | -                 | 默认签名位置信息          |
-| onChange       | function | -                 | 签名位置变化回调函数       |
+| 属性              | 类型       | 默认值                   | 说明             |
+|-----------------|----------|-----------------------|----------------|
+| url             | string   | -                     | PDF 文件的 URL 地址 |
+| signature       | string   | -                     | 签名图片的 URL 地址   |
+| width           | number   | 200                   | 签名区域的宽度        |
+| height          | number   | 80                    | 签名区域的高度        |
+| padding         | number   | 8                     | 签名区域变换器的内边距    |
+| placeholder     | string   | -                     | 签名区域的占位文本      |
+| filename        | string   | 'signed-document.pdf' | 生成签名PDF的文件名    |
+| defaultLocation | object   | -                     | 默认签名位置信息       |
+| onChange        | function | -                     | 签名位置变化回调函数     |
 
 #### 实例方法
 
@@ -324,6 +520,33 @@ render(<BaseExample />);
 | getPdfSignature | -                | object        | 获取 PDF 签名信息   |
 | sign            | -                | Promise<File> | 生成签名后的 PDF 文件 |
 
+### PDFSignMulti
+
+多位置 PDF 签名组件，支持在同一 PDF 文档中添加多个签名位置，适用于需要多方签名或多页面签名的场景。
+
+| 属性                   | 类型       | 默认值                   | 说明             |
+|----------------------|----------|-----------------------|----------------|
+| url                  | string   | -                     | PDF 文件的 URL 地址 |
+| width                | number   | 200                   | 签名区域的宽度        |
+| height               | number   | 80                    | 签名区域的高度        |
+| padding              | number   | 8                     | 签名区域变换器的内边距    |
+| placeholder          | string   | -                     | 签名区域的占位文本      |
+| filename             | string   | 'signed-document.pdf' | 生成签名PDF的文件名    |
+| defaultSignatureList | array    | -                     | 默认签名位置列表       |
+| isEdit               | boolean  | -                     | 是否处于编辑模式       |
+| onSign               | function | -                     | 点击签名区域时的回调函数   |
+| onChange             | function | -                     | 签名位置列表变化回调函数   |
+
+#### 实例方法
+
+| 方法名                 | 参数           | 返回值           | 说明            |
+|---------------------|--------------|---------------|---------------|
+| getSignatureList    | -            | array         | 获取当前签名位置列表    |
+| setSignatureList    | value: array | -             | 设置签名位置列表      |
+| getPdfSignatureList | -            | array         | 获取 PDF 签名信息列表 |
+| sign                | -            | Promise<File> | 生成签名后的 PDF 文件 |
+| addSignLocation     | -            | -             | 添加一个新的签名位置    |
+
 ### PDFViewer
 
 PDF 文档查看器组件，提供 PDF 页面浏览功能。
@@ -351,17 +574,31 @@ PDF 文档查看器组件，提供 PDF 页面浏览功能。
 
 签名定位层组件，用于在 PDF 上定位和调整签名区域。
 
-| 属性          | 类型       | 默认值       | 说明       |
-|-------------|----------|-----------|----------|
-| stageWidth  | number   | -         | 画布宽度（必需） |
-| stageHeight | number   | -         | 画布高度（必需） |
-| width       | number   | 200       | 签名区域宽度   |
-| height      | number   | 50        | 签名区域高度   |
-| padding     | number   | 8         | 变换器内边距   |
-| placeholder | string   | '拖拽到签名位置' | 占位文本     |
-| signature   | string   | -         | 签名图片 URL |
-| value       | object   | -         | 受控的位置值   |
-| onChange    | function | -         | 位置变化回调   |
+| 属性          | 类型       | 默认值 | 说明       |
+|-------------|----------|-----|----------|
+| stageWidth  | number   | -   | 画布宽度（必需） |
+| stageHeight | number   | -   | 画布高度（必需） |
+| width       | number   | 200 | 签名区域宽度   |
+| height      | number   | 80  | 签名区域高度   |
+| padding     | number   | 8   | 变换器内边距   |
+| placeholder | string   | -   | 占位文本     |
+| signature   | string   | -   | 签名图片 URL |
+| value       | object   | -   | 受控的位置值   |
+| onChange    | function | -   | 位置变化回调   |
+
+### LocationGroup
+
+签名位置组组件，用于管理多个签名位置。
+
+| 属性          | 类型       | 默认值  | 说明         |
+|-------------|----------|------|------------|
+| stageWidth  | number   | -    | 画布宽度（必需）   |
+| stageHeight | number   | -    | 画布高度（必需）   |
+| isEdit      | boolean  | true | 是否处于编辑模式   |
+| currentPage | number   | -    | 当前页码       |
+| value       | array    | -    | 受控的位置值数组   |
+| onChange    | function | -    | 位置列表变化回调   |
+| onClick     | function | -    | 点击签名区域时的回调 |
 
 ### useSignature
 
@@ -369,18 +606,20 @@ PDF 文档查看器组件，提供 PDF 页面浏览功能。
 
 #### 返回的函数参数
 
-| 参数         | 类型       | 默认值             | 说明         |
-|------------|----------|-----------------|------------|
-| filename   | string   | 'signature.png' | 签名文件名      |
-| width      | number   | 200             | 签名画板宽度     |
-| height     | number   | 80              | 签名画板高度     |
+| 参数         | 类型        | 默认值             | 说明         |
+|------------|-----------|-----------------|------------|
+| filename   | string    | 'signature.png' | 签名文件名      |
+| width      | number    | 200             | 签名画板宽度     |
+| height     | number    | 80              | 签名画板高度     |
 | mask       | ReactNode | -               | 签名画板叠加内容   |
-| onSuccess  | function | -               | 签名完成回调     |
-| modalProps | object   | -               | Modal 组件属性 |
+| onSuccess  | function  | -               | 签名完成回调     |
+| modalProps | object    | -               | Modal 组件属性 |
+
+### signPdfFile
+
+签名文件生成工具函数，支持单个签名。
 
-#### Hook 配置参数
+| 参数           | 类型     | 默认值 | 说明         |
+|--------------|--------|-----|------------|
+| pdfSignature | object | -   | PDF 签名配置对象 |
 
-| 参数     | 类型     | 默认值 | 说明       |
-|--------|--------|-----|----------|
-| width  | number | 200 | 默认签名画板宽度 |
-| height | number | 80  | 默认签名画板高度 |