# @fungies/fungies-js 中文文档

规范地址：https://npmcn.com/package/%40fungies/fungies-js/

版本：0\.8\.0
npm 元数据更新时间：2026-11-10T17:39:30.734Z
中文译文更新时间：2026-11-15T20:32:20.522Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fungies/fungies-js
原文对照：https://npmcn.com/package/%40fungies/fungies-js/?lang=original
项目主页：https://gitlab.com/fungies/fungies/fungies-apps#readme
源码仓库：https://gitlab.com/fungies/fungies/fungies-apps

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

- 包体积（解压后）：60.2 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-03-26T13:46:14.247Z
- 最新版本发布：2026-11-10T17:39:30.537Z
- 近 30 天下载量：2527（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 5 个）

## 中文简介

Fungies JavaScript SDK为Fungies在您网络应用程序中的取出提供了方便的集成.

## 安装

```sh
npm install @fungies/fungies-js
```

也可以使用：`pnpm add @fungies/fungies-js`、`yarn add @fungies/fungies-js`、`bun add @fungies/fungies-js`

## README

# 乐趣 JavaScript SDK

Fungies JavaScript SDK为Fungies在您网络应用程序中的取出提供了方便的集成.

## 安装

```bash
npm install @fungies/fungies-js
```

```bash
yarn add @fungies/fungies-js
```

```bash
pnpm add @fungies/fungies-js
```

## 使用量

### JavaScript 初始化

```javascript
import { Fungies } from "@fungies/fungies-js";

// Initialize Fungies
Fungies.Initialize({
  // Optional: Disable data attribute support
  // enableDataAttributes: false
});

// Open a checkout programmatically
Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay", // 'overlay' | 'embed'
    frameTarget: "target-element-id", // Optional, for embed mode
  },
});

// Close the checkout
Fungies.Checkout.close();
```

### 收听退出事件

SDK 监听出账iframe中的信息,并发送 DOM 事件 `document`。这在您拨打电话时自动发生 `Fungies.Initialize()` 或使用 `data-auto-init` 脚本属性——不需要额外的设置.

使用这些事件在购买后运行自己的逻辑(方向,显示感谢页,刷新权限等).

| 活动 | 当它起火时 |
| --- | --- |
| `fungies:checkout:complete` | 客户成功完成离职 |
| `fungies:checkout:close` | 结账(客户或结账后) |

```javascript
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

Fungies.Initialize();

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, () => {
  // Payment succeeded — e.g. redirect to a thank-you page
  window.location.href = "/thank-you";
});

document.addEventListener(DOM_CHECKOUT_EVENTS.CLOSE, () => {
  // Checkout overlay/embed was dismissed
  console.log("Checkout closed");
});

Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: { mode: "overlay" },
});
```

在使用 CDN 脚本标记时, 在 SDK 负载后注册听众 :

```html
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>
<script>
  document.addEventListener("fungies:checkout:complete", () => {
    window.location.href = "/thank-you";
  });
</script>
```

在反应中,附加听器在 a `useEffect` 并清理他们上山去

```tsx
import { useEffect } from "react";
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

function App() {
  useEffect(() => {
    Fungies.Initialize();

    const onComplete = () => {
      window.location.href = "/thank-you";
    };

    document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    return () => {
      document.removeEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    };
  }, []);

  return <button onClick={() => Fungies.Checkout.open({ /* ... */ })}>Buy</button>;
}
```

### 更新付款方法

让订阅者替换已过期的卡片而不离开您的页面 。 薄荷会话 ** 服务器** 与 `POST /v0/subscriptions/{subscriptionIdOrNumber}/paymentMethodSession` (密钥) 然后把SDK交给 `sessionToken` 财务报告和审定财务报表 `url` 从这个反应。 这个 向元素移动符号 `postMessage` 只有——它从未被放入URL,饼干或存储.

```javascript
import { DOM_PAYMENT_METHOD_EVENTS, Fungies } from "@fungies/fungies-js";

document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.UPDATED, () => {
  // The card on file changed; in overlay mode the element has already closed itself.
});
document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.FAILED, () => {
  // The session can no longer be used (expired, already used, invalid). Mint a new one to retry.
});
document.addEventListener(DOM_PAYMENT_METHOD_EVENTS.CLOSE, () => {
  // The customer dismissed the overlay (X, ESC or backdrop). The session is still valid.
});

const { sessionToken, url } = await fetch("/api/payment-method-session", { method: "POST" }).then((r) => r.json());

Fungies.PaymentMethod.update({
  sessionToken,
  url,
  settings: {
    mode: "overlay", // 'overlay' | 'embed'
    frameTarget: "target-element-id", // Required with 'embed', ignored by 'overlay'
  },
});

// Close it programmatically (dispatches no event)
Fungies.PaymentMethod.close();
```

| 活动 | 当它起火时 |
| --- | --- |
| `fungies:payment-method:updated` | 新的支付方法被保存了下来. 盖相自闭. |
| `fungies:payment-method:failed` | 会话已死——已过期,已使用或无效(元素显示客户为何),或者帧从未在15 s 内回答,在任一模式中被移除. 薄荷是重新试炼的新品. |
| `fungies:payment-method:close` | 顾客关闭了封面。 没有被开除 `PaymentMethod.close()`。 。 。 . |

倒卡点火无所事事:表格保持开放,顾客可以再试一张.

您的页面从不导航: 元素完成卡片在自己的框内更改, 而 框上挂着一个 `sandbox` 没有 `allow-top-navigation`,所以没有装入里面 可以替换标签.

需要不装入 SDK 的事件名称—— 服务器侧捆绑, 或装入一个 不同的 SDK 构建 `<script>`从 `@fungies/fungies-js/events`,用于安装 没什么 `window`。 。 。 .

`settings.mode` 必须是 `'overlay'` 或者说 `'embed'`; 以控制台警告拒绝其他任何值 什么都没有打开 和失踪一样 `sessionToken` 无效 `url`最多一个 `updated` 编号 : `failed` 每个会话的起火;一个在两个会话之后再次发出信号的框架不转发.

故意没有 `data-*` 此流的属性变量: DOM 属性中的会话符号 可被您页面上的每个第三方脚本读取,并被会话重放工具捕获,同时 在 JavaScript 中持有的值不是。 在代码中保留符号并打电话 `PaymentMethod.update()`。 。 。 .

您的页面来源必须位于工作空间的授权域中, 或者浏览器拒绝设定 键。 一个被拒绝的相框从不回答握手,所以SDK在加载后取出15 s 火灾 `failed` 内 `overlay` 模式中清除将吞入点击的全视图端口框架 `embed` 模式中它会空出你给它的容器,而不是离开浏览器的错误页.

### HTML 数据属性支持

您也可以使用 HTML 数据属性来创建不写入 JavaScript 的取出按钮 :

```html
<!-- Basic checkout button -->
<button
  data-fungies-checkout-url="https://store.example.com/checkout-element/my-checkout-id"
  data-fungies-mode="overlay"
>
  Open Checkout
</button>

<!-- Script tag to initialize the SDK -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>

<!-- Embed checkout with target element -->
<div id="target-element-id"></div>

<!-- Script tag to initialize and display checkout automatically -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
  data-auto-display-checkout
  data-fungies-checkout-url="https://demo.dev.fungies.net/checkout-element/a85d8c76-bc30-48a3-9861-be68952a1eca"
  data-fungies-mode="embed"
  data-fungies-frame-target="target-element-id"
></script>
```

### 手动 DOM 扫描

如果您在加载页面后动态地添加了取出元素,您可以手动触发 DOM 扫描 :

```javascript
// Scan the page for new checkout elements
Fungies.ScanDOM();
```

## 数据属性参考

-   `data-fungies-checkout-url`: (需要新格式) 检出 URL
-   `data-fungies-mode`: (可选) 退出模式( “ 覆盖” 或 “ 覆盖” )
-   `data-fungies-frame-target`: (可选) 嵌入式取出的目标元素ID
-   `data-fungies-discount-code`: (可选)将适用的贴现代码
-   `data-fungies-customer-email`: (可选)客户邮件预填(过期,使用数据fungies-billing-email)
-   `data-fungies-billing-email`: (可选) 计费电子邮件预填
-   `data-fungies-billing-first-name`: (可选) 记账首名预填
-   `data-fungies-billing-last-name`: (可选) 计费姓预填
-   `data-fungies-billing-country`: (可选) 计费国家代码(ISO 3166-1 α-2) 预填
-   `data-fungies-billing-state`: (可选) 计费州/省预填
-   `data-fungies-billing-city`: (可选) 计费城市预填
-   `data-fungies-billing-zip-code`: (可选) 计费拉链/邮戳代码以预填
-   `data-fungies-quantity`: (可选) 退出的默认数量
-   `data-fungies-items`: (可选) JSON 系列要购买的物品
-   `data-fungies-custom-fields`: (可选) JSON 字符串自定义字段
-   `data-fungies-button`: (Legacy格式)包含诸如"https://STORE URL/checkout-element/:checkoutID"或"https://STORE URL/overlay/:checkoutID"的取出URL

## 类型脚本支持

此包包括了TypeScript定义. 您可以在支持的编辑器中利用类型检查和IntelliSense:

```typescript
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";
import type { DomCheckoutEvent, InitialCheckoutOpenOptions } from "@fungies/fungies-js";

const onComplete = (event: Event) => {
  const checkoutEvent = event.type as DomCheckoutEvent;
  if (checkoutEvent === DOM_CHECKOUT_EVENTS.COMPLETE) {
    window.location.href = "/thank-you";
  }
};

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);

// TypeScript will validate all parameters
const openOptions: InitialCheckoutOpenOptions = {
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay",
    // frameTarget is optional and only used with embed mode
    frameTarget: "container-id",
  },
};

Fungies.Checkout.open(openOptions);
```

## 常见问题

### @fungies/fungies-js 是什么？

Fungies JavaScript SDK为Fungies在您网络应用程序中的取出提供了方便的集成\.

### 如何安装 @fungies/fungies-js？

在项目目录运行 npm install @fungies/fungies-js，或使用 pnpm add / yarn add / bun add。

### @fungies/fungies-js 支持 TypeScript 吗？

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

### @fungies/fungies-js 支持 ESM 还是 CommonJS？

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

### @fungies/fungies-js 可以商用吗？

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

### @fungies/fungies-js 的下载量有多少？

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

### @fungies/fungies-js 还在维护吗？

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