@kne/react-pdf-sign 1.0.0

package/README.md

@@ -0,0 +1,346 @@
+
+# react-pdf-sign
+
+
+### 描述
+
+这是一个功能强大的 React PDF 签名组件库，专为需要在 PDF 文档上添加电子签名的应用场景而设计。该组件库提供了灵活的签名解决方案，支持即时签名添加和预定义签名区域两种模式
+
+
+### 安装
+
+```shell
+npm i --save @kne/react-pdf-sign
+```
+
+
+### 概述
+
+这是一个功能强大的 React PDF 签名组件库，专为需要在 PDF 文档上添加电子签名的应用场景而设计。该组件库提供了灵活的签名解决方案，支持即时签名添加和预定义签名区域两种模式。
+
+## 核心特性
+
+**直观的签名体验** - 提供手写签名画板，用户可以通过鼠标或触摸设备自然地绘制签名，签名支持实时预览和调整。
+
+**灵活的定位控制** - 签名区域可以在 PDF 页面上自由拖拽、缩放和精确定位，支持保持比例缩放，确保签名的视觉效果。
+
+**完整的 PDF 操作** - 基于 pdf-lib 和 react-pdf，支持多页 PDF 文档的浏览、签名定位和最终签名文件的生成。
+
+**组件化设计** - 提供多个独立组件（PDFSign、PDFViewer、LocationLayer、useSignature），开发者可以根据需求灵活组合使用。
+
+**国际化支持** - 内置中英文语言包，支持多语言切换，适合国际化应用。
+
+**现代化技术栈** - 基于 React 18+，使用 Konva.js 实现高性能的图形渲染，支持响应式设计。
+
+## 使用场景
+
+- 合同签署系统
+- 文档审批流程
+- 电子表单签名
+- 证书颁发系统
+- 法律文件签署
+
+该组件库简化了 PDF 签名的复杂实现，开发者只需要几行代码就能集成完整的签名功能，大大提升了开发效率。
+
+### 示例
+
+#### 示例代码
+
+- 完整签名流程
+- 演示PDF上传、手写签名创建和签名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 { default: ReactPdfSign, useSignature } = _ReactPdfSign;
+const { useState, useRef } = React;
+const { Flex, Button } = antd;
+
+const BaseExample = () => {
+  const [pdfFile, setPdfFile] = useState(null);
+  const [sign, setSign] = useState(null);
+  const ref = useRef(null);
+  const signatureModal = useSignature();
+  return (
+    <Flex vertical gap={12}>
+      <Flex gap={8}>
+        <Button>
+          <input
+            type="file"
+            accept="application/pdf"
+            onChange={e => {
+              const file = e.target.files[0];
+              setPdfFile(URL.createObjectURL(file));
+            }}
+          />
+        </Button>
+        <Button
+          onClick={() => {
+            signatureModal({
+              onSuccess: file => {
+                setSign(URL.createObjectURL(file));
+              }
+            });
+          }}>
+          添加签名
+        </Button>
+        {pdfFile && sign && (
+          <Button
+            onClick={async () => {
+              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);
+            }}>
+            生成签名PDF
+          </Button>
+        )}
+      </Flex>
+      {pdfFile ? <ReactPdfSign url={pdfFile} signature={sign} ref={ref} /> : 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)
+
+```jsx
+const { LocationLayer } = _ReactPdfSign;
+
+const BaseExample = () => {
+  return (
+    <div>
+      <LocationLayer stageWidth={400} stageHeight={300} />
+    </div>
+  );
+};
+
+render(<BaseExample />);
+
+```
+
+- PDF查看器
+- 基础的PDF文档查看器，支持页面切换和缩放显示
+- _ReactPdfSign(@kne/current-lib_react-pdf-sign)[import * as _ReactPdfSign from "@kne/react-pdf-sign"],_examplePdf(./doc/example.pdf),(@kne/current-lib_react-pdf-sign/dist/index.css)
+
+```jsx
+const { PDFViewer } = _ReactPdfSign;
+const { default: examplePdf } = _examplePdf;
+
+const BaseExample = () => {
+  return (
+    <div>
+      <PDFViewer url={examplePdf} />
+    </div>
+  );
+};
+
+render(<BaseExample />);
+
+```
+
+- PDF签名组件
+- 演示PDF签名组件的API使用，包括位置获取、设置和签名文件生成
+- _ReactPdfSign(@kne/current-lib_react-pdf-sign)[import * as _ReactPdfSign from "@kne/react-pdf-sign"],_examplePdf(./doc/example.pdf),_signature(./doc/signature.png),antd(antd),(@kne/current-lib_react-pdf-sign/dist/index.css)
+
+```jsx
+const { PDFSign } = _ReactPdfSign;
+const { default: examplePdf } = _examplePdf;
+const { default: signature } = _signature;
+const { useRef } = React;
+const { Flex, Button, App } = antd;
+
+const BaseExample = () => {
+  const ref = useRef();
+  const ref2 = useRef();
+  const { modal } = App.useApp();
+  return (
+    <Flex vertical gap={24}>
+      <Flex vertical gap={8}>
+        <Flex gap={8}>
+          <Button
+            onClick={() => {
+              const location = ref.current.getLocation();
+              modal.info({
+                title: '签名位置',
+                content: <pre>{JSON.stringify(location, null, 2)}</pre>
+              });
+            }}>
+            获取签名位置
+          </Button>
+          <Button
+            onClick={() => {
+              ref.current.setLocation({
+                size: {
+                  width: 200,
+                  height: 50,
+                  x: 240,
+                  y: 47
+                },
+                scaleX: 1,
+                scaleY: 1,
+                x: 240,
+                y: 47
+              });
+            }}>
+            设置签名位置
+          </Button>
+          <Button
+            onClick={() => {
+              const pdfSignature = ref.current.getPdfSignature();
+              modal.info({
+                title: 'PDF签名信息',
+                content: <pre style={{ 'white-space': 'break-spaces' }}>{JSON.stringify(pdfSignature, null, 2)}</pre>
+              });
+            }}>
+            获取PDF签名信息
+          </Button>
+        </Flex>
+        <PDFSign url={examplePdf} ref={ref} />
+      </Flex>
+      <Flex vertical gap={8}>
+        <div>
+          <Button
+            onClick={async () => {
+              const blob = await ref2.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);
+            }}>
+            生成签名文件
+          </Button>
+        </div>
+        <PDFSign url={examplePdf} signature={signature} ref={ref2} />
+      </Flex>
+    </Flex>
+  );
+};
+
+render(<BaseExample />);
+
+```
+
+- 手写签名画板
+- 展示useSignature Hook的使用，打开手写签名模态框
+- _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 { useSignature } = _ReactPdfSign;
+const { Button } = antd;
+
+const BaseExample = () => {
+  const modal = useSignature();
+  return (
+    <div>
+      <Button
+        onClick={() => {
+          modal({
+            onSuccess: file => {
+              console.log(file);
+            }
+          });
+        }}>
+        签名
+      </Button>
+    </div>
+  );
+};
+
+render(<BaseExample />);
+
+```
+
+
+### API
+
+### PDFSign
+
+主要的 PDF 签名组件，集成了 PDF 查看器和签名定位功能。
+
+| 属性          | 类型     | 默认值       | 说明             |
+|-------------|--------|-----------|----------------|
+| url         | string | -         | PDF 文件的 URL 地址 |
+| signature   | string | -         | 签名图片的 URL 地址   |
+| width       | number | 200       | 签名区域的宽度        |
+| height      | number | 50        | 签名区域的高度        |
+| padding     | number | 8         | 签名区域变换器的内边距    |
+| placeholder | string | '拖拽到签名位置' | 签名区域的占位文本      |
+
+#### 实例方法
+
+| 方法名             | 参数               | 返回值           | 说明            |
+|-----------------|------------------|---------------|---------------|
+| getLocation     | -                | object        | 获取当前签名位置信息    |
+| setLocation     | location: object | -             | 设置签名位置        |
+| getPdfSignature | -                | object        | 获取 PDF 签名信息   |
+| sign            | -                | Promise<File> | 生成签名后的 PDF 文件 |
+
+### PDFViewer
+
+PDF 文档查看器组件，提供 PDF 页面浏览功能。
+
+| 属性          | 类型     | 默认值  | 说明                |
+|-------------|--------|------|-------------------|
+| url         | string | -    | PDF 文件的 URL 地址    |
+| className   | string | -    | 自定义 CSS 类名        |
+| defaultPage | number | 1    | 默认显示的页码           |
+| maxWidth    | number | 1200 | 最大显示宽度            |
+| pdfjsUrl    | string | -    | 自定义 pdf.js CDN 地址 |
+| apis        | object | -    | API 配置对象          |
+
+#### children 渲染属性
+
+当 children 为函数时，会传入以下参数：
+
+| 参数          | 类型     | 说明        |
+|-------------|--------|-----------|
+| size        | object | 当前页面的尺寸信息 |
+| currentPage | number | 当前页码      |
+| pageSize    | number | 总页数       |
+
+### LocationLayer
+
+签名定位层组件，用于在 PDF 上定位和调整签名区域。
+
+| 属性          | 类型       | 默认值       | 说明       |
+|-------------|----------|-----------|----------|
+| stageWidth  | number   | -         | 画布宽度（必需） |
+| stageHeight | number   | -         | 画布高度（必需） |
+| width       | number   | 200       | 签名区域宽度   |
+| height      | number   | 50        | 签名区域高度   |
+| padding     | number   | 8         | 变换器内边距   |
+| placeholder | string   | '拖拽到签名位置' | 占位文本     |
+| signature   | string   | -         | 签名图片 URL |
+| value       | object   | -         | 受控的位置值   |
+| onChange    | function | -         | 位置变化回调   |
+
+### useSignature
+
+签名画板 Hook，提供手写签名功能。
+
+#### 返回的函数参数
+
+| 参数         | 类型       | 默认值             | 说明         |
+|------------|----------|-----------------|------------|
+| filename   | string   | 'signature.png' | 签名文件名      |
+| width      | number   | 200             | 签名画板宽度     |
+| height     | number   | 50              | 签名画板高度     |
+| onSuccess  | function | -               | 签名完成回调     |
+| modalProps | object   | -               | Modal 组件属性 |
+
+#### Hook 配置参数
+
+| 参数     | 类型     | 默认值 | 说明       |
+|--------|--------|-----|----------|
+| width  | number | 200 | 默认签名画板宽度 |
+| height | number | 50  | 默认签名画板高度 |

package/dist/index.css

@@ -0,0 +1,64 @@
+._RgZXN {
+  margin: 0 auto;
+  position: relative;
+  max-width: 1200px;
+  width: 100%;
+}
+._RgZXN .react-pdf__Page__canvas,
+._RgZXN .textLayer {
+  margin: 0 auto;
+}
+
+._PAju1 {
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);
+}
+
+._N11Pj {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 10;
+}
+
+._IbVpf,
+._IIgqj {
+  position: absolute;
+  font-size: 30px;
+  top: calc(50% - 19px);
+  z-index: 10;
+  padding: 8px;
+  cursor: pointer;
+  opacity: 0.3;
+}
+
+._JW3CT {
+  position: absolute;
+  bottom: 10px;
+  left: 50%;
+  transform: translateX(-50%);
+  color: #666666;
+  background-color: rgba(255, 255, 255, 0.5);
+  text-shadow: 0 0 8px white, 0 0 8px white;
+  border-radius: 4px;
+}
+
+._IIgqj {
+  right: 0;
+}
+
+._6TDb- {
+  border: 1px solid #cccccc;
+  border-radius: 4px;
+}
+
+._2CGF4 {
+  width: 100%;
+  height: 100%;
+}
+
+._kWe3k .ant-modal-confirm-paragraph {
+  max-width: unset;
+}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["style.module.scss"],"names":[],"mappings":"AAAA;EACE,cAAc;EACd,kBAAkB;EAClB,iBAAiB;EACjB,WAAW;AACb;AACA;;EAEE,cAAc;AAChB;;AAEA;EACE,wEAAwE;AAC1E;;AAEA;EACE,kBAAkB;EAClB,MAAM;EACN,OAAO;EACP,WAAW;EACX,YAAY;EACZ,WAAW;AACb;;AAEA;;EAEE,kBAAkB;EAClB,eAAe;EACf,qBAAqB;EACrB,WAAW;EACX,YAAY;EACZ,eAAe;EACf,YAAY;AACd;;AAEA;EACE,kBAAkB;EAClB,YAAY;EACZ,SAAS;EACT,2BAA2B;EAC3B,cAAc;EACd,0CAA0C;EAC1C,yCAAyC;EACzC,kBAAkB;AACpB;;AAEA;EACE,QAAQ;AACV;;AAEA;EACE,yBAAyB;EACzB,kBAAkB;AACpB;;AAEA;EACE,WAAW;EACX,YAAY;AACd;;AAEA;EACE,gBAAgB;AAClB","file":"index.css","sourcesContent":[".pdf-view-container {\n  margin: 0 auto;\n  position: relative;\n  max-width: 1200px;\n  width: 100%;\n}\n.pdf-view-container :global(.react-pdf__Page__canvas),\n.pdf-view-container :global(.textLayer) {\n  margin: 0 auto;\n}\n\n.pdf-view {\n  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);\n}\n\n.pdf-view-children {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  z-index: 10;\n}\n\n.pdf-view-page-control-left,\n.pdf-view-page-control-right {\n  position: absolute;\n  font-size: 30px;\n  top: calc(50% - 19px);\n  z-index: 10;\n  padding: 8px;\n  cursor: pointer;\n  opacity: 0.3;\n}\n\n.pdf-view-page-control-current {\n  position: absolute;\n  bottom: 10px;\n  left: 50%;\n  transform: translateX(-50%);\n  color: #666666;\n  background-color: rgba(255, 255, 255, 0.5);\n  text-shadow: 0 0 8px white, 0 0 8px white;\n  border-radius: 4px;\n}\n\n.pdf-view-page-control-right {\n  right: 0;\n}\n\n.signature-container {\n  border: 1px solid #cccccc;\n  border-radius: 4px;\n}\n\n.signature-canvas {\n  width: 100%;\n  height: 100%;\n}\n\n.signature-modal :global .ant-modal-confirm-paragraph {\n  max-width: unset;\n}"]}