# @confirmo/overlay 中文文档

规范地址：https://npmcn.com/package/%40confirmo/overlay/

版本：4\.6\.0
npm 元数据更新时间：2026-09-01T10:49:23.282Z
中文译文更新时间：2026-11-10T15:21:28.594Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40confirmo/overlay
原文对照：https://npmcn.com/package/%40confirmo/overlay/?lang=original

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

- 包体积（解压后）：78.4 MB，6362 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-05-14T08:44:06.810Z
- 最新版本发布：2026-09-01T10:49:23.064Z
- 近 30 天下载量：21186（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 4 个）

## 中文简介

确认覆盖库

## 安装

```sh
npm install @confirmo/overlay
```

也可以使用：`pnpm add @confirmo/overlay`、`yarn add @confirmo/overlay`、`bun add @confirmo/overlay`

## README

# 确认

### 无

```
npm install @confirmo/overlay
```

### 线条

```
yarn add @confirmo/overlay
```

### 小时

```
pnpm add @confirmo/overlay
```

### 光盘N

```html
<!-- To always install exact version (recommended - avoid future breaking changes) -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@4.6.0/dist/confirmo.js"></script>
<!-- To always install exact major version -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@4/dist/confirmo.js"></script>
<!-- To always install the latest version -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@latest/dist/confirmo.js"></script>
```

## 重叠

### 炸弹

```javascript
import { Invoice } from '@confirmo/overlay';

/**
 * Opens Confirmo invoice overlay
 *
 * @param {string} invoice_url - URL of invoice.
 * @param {callback} [callback_fnc] - Optional - callback which is called when overlay was closed
 * @param {InvoiceOverlayConfig} [overlayConfig] - Optional - Confirmo overlay configuration (currently only for auto-close when invoice is paid)
 *
 * @example
 *
 * // URL of invoice created from REST API
 * const invoice_url = 'https://pay.confirmo.com/public/invoice/invv9e1rxdz8?m=mer951dkwdw1';
 *
 * // (optional) Callback which is called when overlay was closed
 * const callback_fnc = () => alert('Overlay has been closed');
 *
 * // (optional) Confirmo overlay configuration
 * const overlayConfig = {
 *   closeAfterPaid: true,
 *   closeAfterPaidTimeoutMs: 2000, // when unspecified, default is 2000ms
 * }
 *
 */
const overlay = Invoice.open(invoice_url, callback_fnc, overlayConfig);

/**
 * Closes Confirmo invoice overlay
 */
overlay.close();
```

### 脚本标记

```html
<script>
  const overlay = Confirmo.Invoice.open(invoice_url, callback_fnc, overlayConfig);

  overlay.close();
</script>
```

## 支付按钮

### HTML 语言

```html
<div id="placeholder-for-button"></div>
```

### 炸弹

```javascript
import { PaymentButton } from '@confirmo/overlay';

/**
 * Creates Confirmo payment button
 */
const button = PaymentButton.initialize(
  {
    id: 'placeholder-for-button',
    paymentButtonId: 'pbt16354asde',
    buttonType: 'SIMPLE',
    values: {
      productName: 'Some cool product',
      productDescription: 'Simple description',
      reference: 'merchantRef',
      returnUrl: 'https://my-cool-eshop.com/?q=this+is+return+url',
      merchantId: 'mer951dkwdw1',
      overlay: true,
    },
  },
  /**
   * Overlay related properties (relevant only if values.overlay set to `true`)
   */
  // (optional) Callback function called on Invoice.close() (see overlay.d.ts)
  () => {
    console.log('Overlay has been closed!');
  },
  // (optional) Invoice overlay config
  overlayConfig,
);

/**
 * Removes Confirmo payment button
 */
button.remove();
```

### 脚本标记

```html
<script>
  const button = Confirmo.PaymentButton.initialize(
    {
      id: 'placeholder-for-button',
      paymentButtonId: 'pbt16354asde',
      buttonType: 'SIMPLE',
      values: {
        productName: 'Some cool product',
        productDescription: 'Simple description',
        reference: 'merchantRef',
        returnUrl: 'https://my-cool-eshop.com/?q=this+is+return+url',
        merchantId: 'mer951dkwdw1',
      },
    },
    /**
     * Overlay related properties (relevant only if values.overlay set to `true`)
     */
    // (optional) Callback function called on Invoice.close() (see overlay.d.ts)
    () => {
      console.log('Overlay has been closed!');
    },
    // (optional) Invoice overlay config
    overlayConfig,
  );

  button.remove();
</script>
```

### 重叠活动

通过窗口从公共发票视图中发射的事件# PostMessage API [https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage 互联网档案馆的存檔,存档日期2013-12-02](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)

使用 @ confirmo/ overlay 的组件可以相应收听 InvoiceOverlayMessageEventData :

```javascript
import { ConfirmoOverlayInvoiceStatus, ConfirmoOverlayMessageAction, Invoice } from '@confirmo/overlay';

const overlay = Invoice.open(invoiceUrl, callback_fnc);

// Custom implementation of closing Confirmo overlay after invoice being paid
window.addEventListener('message', (event) => {
  if (
    invoiceUrl.includes(event.origin) &&
    event.data.action === ConfirmoOverlayMessageAction.CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE &&
    event.data.status === ConfirmoOverlayInvoiceStatus.PAID
  ) {
    // handle paid invoice (e.g. by closing the overlay)
    setTimeout(() => {
      overlay.close();
    }, 2000); // close overlay after 2 seconds
  }
});
```

_注:上述效果可以简单地通过设置来实现 `overlayConfig`是因为 `closeAfterPaid`_

```javascript
import { Invoice } from '@confirmo/overlay';

const overlayConfig = {
  closeAfterPaid: true,
};

Invoice.open(invoiceUrl, callback_fnc, overlayConfig);
```

## 常见问题

### @confirmo/overlay 是什么？

确认覆盖库

### 如何安装 @confirmo/overlay？

在项目目录运行 npm install @confirmo/overlay，或使用 pnpm add / yarn add / bun add。

### @confirmo/overlay 支持 TypeScript 吗？

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

### @confirmo/overlay 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @confirmo/overlay 可以商用吗？

@confirmo/overlay 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @confirmo/overlay 的下载量有多少？

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

### @confirmo/overlay 还在维护吗？

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