# @anvilco/react-signature-modal 中文文档

规范地址：https://npmcn.com/package/%40anvilco/react-signature-modal/

版本：2\.1\.4
npm 元数据更新时间：2025-11-12T22:03:21.326Z
中文译文更新时间：2026-11-06T07:40:18.737Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40anvilco/react-signature-modal
原文对照：https://npmcn.com/package/%40anvilco/react-signature-modal/?lang=original
项目主页：https://github.com/anvilco/react-ui#readme
源码仓库：https://github.com/anvilco/react-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\*
- 运行依赖：0 个
- peer 依赖：react \>=16，react-dom \>=16，prop-types ^15\.6\.0，react-modal ^3\.11\.2
- 首次发布：2020-11-13T02:35:11.516Z
- 最新版本发布：2025-10-28T20:34:36.255Z
- 近 30 天下载量：44499（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 0 个）

## 中文简介

嵌入式 Etch 签名的 AnvilSignature Modal 反应组件

## 安装

```sh
npm install @anvilco/react-signature-modal
```

也可以使用：`pnpm add @anvilco/react-signature-modal`、`yarn add @anvilco/react-signature-modal`、`bun add @anvilco/react-signature-modal`

## README

# 签名

允许嵌入的轻量级模式组件 [电子签名](https://www.useanvil.com/docs/api/e-signatures) 通过一个模式弹出 在你的应用程序。 它会通过签名过程生命周期的回调给您信息. 兼容最小依赖的移动取景口.

见 [现场演示](https://esign-demo.useanvil.com/) 和开源 [演示仓库](https://github.com/anvilco/anvil-e-signature-api-node-example) 以用法为例.

![image](https://user-images.githubusercontent.com/26425671/101393509-0f604680-387c-11eb-8e09-b889b0c21c7f.png)

## 安维尔是什么?

[安维尔](https://www.useanvil.com/developers) 为所有文件提供方便的API.

1.  [PDF 填补 API](https://www.useanvil.com/products/pdf-filling-api/) - 填写一个PDF模板,其中包含网络请求和结构化的JSON数据.
2.  [PDF 生成 API](https://www.useanvil.com/products/pdf-generation-api/) - 发送标记下来或HTML和Anvil会把它变成PDF.
3.  [Etch 带有 API 的 E 签名](https://www.useanvil.com/products/etch/) - 可自定义的、可嵌入的、带有API的电子签名平台,以控制签名过程的端到端.
4.  [工作流量(w/ API)](https://www.useanvil.com/products/workflows/) - Webforms + PDF + E- sign 带有强大的无码构建器. 轻松地收集结构化数据,生成PDF,并请求签名.

学着点 [Anvil 开发者页面](https://www.useanvil.com/developers)。 。 。 .

## 使用量

```sh
yarn add @anvilco/react-signature-modal
```

```sh
npm install @anvilco/react-signature-modal
```

```js
import AnvilSignatureModal from '@anvilco/react-signature-modal'
import '@anvilco/react-signature-modal/dist/styles.css'

<AnvilSignatureModal
  iframeURL={iframeURL}
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  onLoad={() => setLoading(false)}
  onEvent={(eventObject) => {
    console.log(eventObject)

    // See https://www.useanvil.com/docs/api/e-signatures/#iframe-event-details
    // for all event details.
    //
    // Example:
    //
    // {
    //   action: 'signerComplete',
    //   signerStatus: 'completed',
    //   signerEid: 'Jc1ZJisPnpF5lHyfyqBW',
    //   nextSignerEid: 'WBqyfyHl5FpnPsiJZ1cJ',
    //   documentGroupStatus: 'partial',
    //   documentGroupEid: 'nEKq2eGim0ijSqKd98nG',
    //   etchPacketEid: 'XzfmVPfGUEyBc1XyylFo',
    // }
  }}
/>
```

## 从v1升级到v2

截至二零零年代 `AnvilSignatureModal` 现在使用 `AnvilEmbedFrame` 在引擎盖下。 道具略有变化:

-   `signURL` - > (中文) `iframeURL`
-   `onFinishSigning` - > (中文) `onEvent`。检查 `eventObject.action === 'signerComplete'` 以检测签名器已签名
-   `onError` - > (中文) `onEvent`。检查 `eventObject.error` 以确定是否存在错误

```js
// v1.x
<AnvilSignatureModal
  // Changed props, see below
  signURL={signURL}
  onFinishSigning={(eventObject) => console.log(eventObject)}
  onError={(eventObject) => console.log(eventObject)}

  // Unchanged!
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  onLoad={() => setLoading(false)}
/>

// v2.x
<AnvilSignatureModal
  // New
  iframeURL={iframeURL}
  onEvent={(eventObject) => {
    console.log(eventObject)
    if (eventObject.action === 'signerComplete') {
      // Signer has finished signing
    } else if (eventObject.error) {
      // There has been an error
    }
  }}

  // Unchanged!
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  onLoad={() => setLoading(false)}
/>
```

## 道具

### 编号

_字符串_ - html id属性,压倒 `id` 还会删除所有默认样式 `react-siganture-modal`。如果想要覆盖特定样式元素,则使用 `anvilFrameProps` 见下文.

### 框架

_字符串( 需要)_ - 从该数据库生成的Anvil签名页面的URL [`generateEtchSignURL` 图QL 变异](https://www.useanvil.com/docs/api/e-signatures#controlling-the-signature-process-with-embedded-signers)。签名框将通过此 URL 显示签名页面.

示例

```js
iframeURL={`https://app.useanvil.com/etch/8iJDbq8dkEmjrsNw7Dnb/sign?token=dsa...`}
```

### 打开

_布尔_ - 如果 `isOpen` 这是真的.

### 关闭

_函数_ - 在右上角单击 X 按钮时,此函数被调用.

示例

```js
onClose={() => setIsOpen(false))}
```

### 活动

_函数_ - 调用函数 `payload` 作为参数。 当一个用户成功完成签名时,它就会被调用 .

示例

```js
onEvent={(eventObject) => console.log(eventObject)}

/*
{
  action: "signerComplete",
  signerEid: "kJzR6mcIWKoZs6KOxV4w",
  signerStatus: "completed",
  nextSignerEid: "HRLhx4khticpfxsUFSpj",
  documentGroupEid: "9fQnvfy51p7oKrEYajMh",
  documentGroupStatus: "partial",
  etchPacketEid: "J1phQTO6WQH6gZcMJAG5", // If from an EtchPacket
  weldDataEid: "J1phQTO6WQH6gZcMJAG5", // If from a workflow
}
*/
```

见 [我们的电子签名文件](https://www.useanvil.com/docs/api/e-signatures/#iframe-event-details) 关于所有iframe事件的全部细节.

`onEvent` 当用户尝试签名时遇到错误时,也叫它。 详情见文件 [如何从错误中恢复](https://www.useanvil.com/docs/api/e-signatures#handling-signing-errors)。 。 。 .

示例出错有效载荷 :

```js
{
  action: "signerError",
  errorType: "tokenExpired", tokenExpired || tokenInvalid || notFound
  error: "Token Expired",
  message: "Error specific message",
  signerEid: "kJzR6mcIWKoZs6KOxV4w",

  // depending on the errorType, you may or may not receive the following
  signerStatus: "sent",
  nextSignerEid: "HRLhx4khticpfxsUFSpj",
  documentGroupEid: "9fQnvfy51p7oKrEYajMh",
  documentGroupStatus: "sent",
  etchPacketEid: "J1phQTO6WQH6gZcMJAG5", // If from an EtchPacket
  weldDataEid: "J1phQTO6WQH6gZcMJAG5", // If from a workflow
}
```

### 登录

_函数_ - 当签名页面装入完成时,此函数被调用 .

示例

```js
onLoad={() => setLoading(false)}
```

### 模式

_字符串_ - 通过一个查询选择器 识别您的应用程序的根。 在模式打开时隐藏其他页面内容 屏幕阅读器和其他无障碍目的.

默认 : `#root`

### 显示关闭

_布尔_ - 显示模式右上方的相近图标, 如果真实的话.

### iframewarning 方案

_对象_ - 如果用户的浏览器不支持iframes,将自定义道具传入显示的段落标记.

示例

```js
iframeWarningProps={{ className: 'warning-text' }}
```

### 紫外线

_对象_ - 将自定义道具传入模式内显示的 Iframe 标记.

示例

```js
anvilFrameProps={{
  style: { background: 'white' },
}}
```

### 图标关闭选项

_对象_ - 将自定义道具传入模式内显示的删除按钮的 svg 标签.

示例

```js
iconCloseProps={{ className: 'red-delete-button' }}
```

## 样式

通过导入您的 CSS 样式表来自定义组件 。 将ID或类名通过作为道具传递来取代.

## Anvil Etch 电子签名文件

[阅读文档](https://www.useanvil.com/docs/api/e-signatures)

## 链接 QQ

-   [@anvilco/反应-签名-模式](https://www.npmjs.com/package/@anvilco/react-signature-modal)
-   [开始使用 Anvil API](https://www.useanvil.com/docs/api/getting-started)

## 页:1

-   要启用 Iframe 嵌入: 请访问您在 Anvil 中的组织设置, 并启用 API 部分的 “ Iframe Embedding ” .
-   反应 QQ v16.0 需要.

## 错误

请为错误、 缺少文档或意外行为存档 .

## 问题或反馈

请发电子邮件给我们 [支持@useanvil.com](mailto:support@useanvil.com)。 。 。 .

## 常见问题

### @anvilco/react-signature-modal 是什么？

嵌入式 Etch 签名的 AnvilSignature Modal 反应组件

### 如何安装 @anvilco/react-signature-modal？

在项目目录运行 npm install @anvilco/react-signature-modal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16）、react-dom（\>=16）、prop-types（^15\.6\.0）、react-modal（^3\.11\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @anvilco/react-signature-modal 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @anvilco/react-signature-modal 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @anvilco/react-signature-modal 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \*。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @anvilco/react-signature-modal 可以商用吗？

@anvilco/react-signature-modal 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @anvilco/react-signature-modal 的下载量有多少？

根据 npm 官方下载统计，@anvilco/react-signature-modal 在 2026/10/06 – 2026/11/04 这 30 天内被下载 44,499 次，日均约 1,483 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @anvilco/react-signature-modal 还在维护吗？

最新版本 2\.1\.4 发布于 2025/10/29（1 年前）；至今共发布 24 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/11/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。