# @fragment-dev/payment-elements 中文文档

规范地址：https://npmcn.com/package/%40fragment-dev/payment-elements/

版本：0\.0\.7
npm 元数据更新时间：2026-11-09T23:50:59.105Z
中文译文更新时间：2026-11-15T11:34:58.373Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fragment-dev/payment-elements
原文对照：https://npmcn.com/package/%40fragment-dev/payment-elements/?lang=original
项目主页：https://github.com/fragment-dev/workspaces
源码仓库：https://github.com/fragment-dev/workspaces

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

- 包体积（解压后）：227 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-09-15T20:32:09.732Z
- 最新版本发布：2026-11-09T23:50:58.948Z
- 近 30 天下载量：6853（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

碎块支付元素的反应组件

## 安装

```sh
npm install @fragment-dev/payment-elements
```

也可以使用：`pnpm add @fragment-dev/payment-elements`、`yarn add @fragment-dev/payment-elements`、`bun add @fragment-dev/payment-elements`

## README

# @ flagment-dev/支付要素

在你的产品中嵌入了Flagment的支付元素,通过Flagment处理支付.

## 安装

```sh
npm install @fragment-dev/payment-elements
```

反应17,18或19必须是同级依赖.

## 使用量

您的服务器调用服务器侧断层 SDK `createPayment` 和通过返回的 `Payment` 转到你产品的支付页面.

```tsx
import {
  Checkout,
  PaymentElements,
  usePayment,
} from '@fragment-dev/payment-elements';

const PayButton = () => {
  const { state, canSubmit, submit, error } = usePayment();
  if (state.status === 'accepted') {
    return <p>Payment accepted.</p>;
  }
  return (
    <>
      <button
        type="button"
        disabled={!canSubmit}
        // Call submit() inside the click handler. It never rejects.
        onClick={() => submit()}
      >
        {state.status === 'processing' ? 'Paying…' : 'Pay'}
      </button>
      {state.status === 'declined' && <p role="alert">{state.message}</p>}
      {error && <p role="alert">{error.message}</p>}
    </>
  );
};

const PaymentPage = ({ payment, email }) => (
  <PaymentElements>
    <Checkout
      payment={payment}
      billingDetails={{ email }}
      onPaymentAccepted={close}
      onPaymentDeclined={recordDecline}
      onError={({ message }) => showError(message)}
    >
      <PayButton />
    </Checkout>
  </PaymentElements>
);
```

`Checkout` 在地址和卡片字段下方设置您的付费按钮 。 这需要 同样的道具 `PaymentSession`。 。 。 .

使用 `usePayment().state` 让你的产品处于状态.

```typescript
type PaymentCheckoutState =
  | { status: 'loading' }
  | { status: 'ready' }
  | { status: 'processing' }
  | { status: 'declined'; message: string; declineCode: string | null }
  | { status: 'accepted' };
```

挂起会话时从断块中加载支付状态并继续 继续飞行的尝试,所以重装不会两次. `state` 读取 `loading` 直到那时.

-   `submit()` 等待卡片银行要求的任何核查步骤 在接受或拒绝收费时,或在收费失败时解决 错误.
-   `onPaymentAccepted` 接受指控时起火。 阅读支付 在您执行命令前从服务器上的 Flagment 状态 .
-   `onPaymentDeclined` 当卡被拒绝时开火。 付款人可以 输入另一张卡,然后再次提交。 下降趋势保持不变 `state` 直至 那麽.
-   `onError` 对不是下降的每一次失败都要开火. 无效的付款报告通过这个回拨, 没有孩子 .

### 自定义布局

要自定义布局, 渲染 `PaymentSession` 与 `AddressElement`, (中文(简体) ), `CardElement` 还有你小时候的薪水扣 挂起一个 `CardElement` 百分比 届会. `AddressElement` 是可选的。 见 [账单细节](https://npmcn.com/package/%40fragment-dev/payment-elements/#readme-billing-details) 学习更多.

### 错误

使用 `usePayment().error` 使失败不会减少。 说得很清楚 当一个字段更改时和何时 `submit()` 启动。 失败会离开会话 `ready`,所以支付的人可以再次屈服.

### 保存支付方法

设定 `savePaymentMethod` 改为 `true` 将卡片保存给付款人 `billingDetails.email` 当 付款确认。 默认为 `false`。 。 。 .

### 账单细节

你可以选择提供 `name` 财务报告和审定财务报表 `address` 支付人。 打开 `AddressElement` 如果你不提供它们.

## 保存一张牌

为了在不收费的情况下保存最终用户卡,您的服务器呼叫 服务器侧碎片 SDK 软件 `createPaymentMethodSetup` 使用终端用户的电子邮件 和通过返回的 `PaymentMethodSetup` 到您的页面.

```tsx
import {
  PaymentElements,
  SavePaymentMethod,
  usePaymentMethodSetup,
} from '@fragment-dev/payment-elements';

const SaveCardButton = () => {
  const { state, canSubmit, submit, error } = usePaymentMethodSetup();
  if (state.status === 'saved') {
    return <p>Card saved.</p>;
  }
  return (
    <>
      <button
        type="button"
        disabled={!canSubmit}
        // Call submit() inside the click handler. It never rejects.
        onClick={() => submit()}
      >
        {state.status === 'processing' ? 'Saving…' : 'Save card'}
      </button>
      {state.status === 'declined' && <p role="alert">{state.message}</p>}
      {error && <p role="alert">{error.message}</p>}
    </>
  );
};

const SaveCardPage = ({ paymentMethodSetup }) => (
  <PaymentElements>
    <SavePaymentMethod
      paymentMethodSetup={paymentMethodSetup}
      onPaymentMethodSaved={close}
      onPaymentMethodDeclined={recordDecline}
      onError={({ message }) => showError(message)}
    >
      <SaveCardButton />
    </SavePaymentMethod>
  </PaymentElements>
);
```

`SavePaymentMethod` 使您的保存按钮位于地址和卡片字段下面. 它需要同样的道具 `PaymentMethodSetupSession`。 。 。 .

要自定义布局, 渲染 `PaymentMethodSetupSession` 与 `AddressElement`, (中文(简体) ), `CardElement` 还有你小时候的"拯救按钮" 挂起一个 `CardElement` 每个届会. `AddressElement` 是可选的。 见 `billingDetails` (c) 将进一步学习.

使用 `usePaymentMethodSetup().state` 让你的产品处于状态.

```typescript
type PaymentMethodSetupState =
  | { status: 'loading' }
  | { status: 'ready' }
  | { status: 'processing' }
  | { status: 'declined'; message: string; declineCode: string | null }
  | { status: 'saved' };
```

在挂载会话时从分块中装入设置状态, 并继续一个 还在飞行中. `state` 读取 `loading` 直到那时.

-   `submit()` 等待卡片银行要求的任何核查步骤 当卡片被保存或被拒绝,或者当它因出错而失败时,解析.
-   `onPaymentMethodSaved` 成功保存支付方法时起火. 这个 `saved` 状态没有卡片细节。 要读取卡片, 您的服务器 查询 `paymentMethodSetup` 并阅读其 `paymentMethod` 字段,或列表 最终用户卡带有 `paymentMethods(filter: { user })`。 。 。 .
-   `onPaymentMethodDeclined` 当卡被拒绝时开火。 最终用户可以 输入另一张卡,然后再次提交。 下降趋势保持不变 `state` 直至 那麽.
-   `onError` 需要为其他非底线故障开火. 无效的设置通过此调用报告, 并且没有孩子 .
-   `billingDetails` 选择 `name` 财务报告和审定财务报表 `address`。没有 `AddressElement`,保存卡片需要 `name`, (中文(简体) ), `address.line1`, (中文(简体) ), `address.postalCode` 财务报告和审定财务报表 `address.country`. 使 `AddressElement` 若为 你不给他们.

## 他们

过 `theme` 样式。 每个设置都有默认值 :

```tsx
<PaymentElements
  theme={{
    appearance: 'light',
    fontFamily: 'Arial, sans-serif',
    input: {
      fontSize: '16px',
      backgroundColor: '#ffffff',
      borderColor: '#d6d1c7',
      borderWidth: '1px',
      borderRadius: '8px',
      padding: '12px',
      focus: { borderColor: '#00a7c9' },
      invalid: { borderColor: '#c62828' },
    },
    label: { fontSize: '12px', color: '#555562', spacing: '8px' },
    error: { fontSize: '12px', color: '#c62828' },
    layout: { rowGap: '16px', columnGap: '10px' },
  }}
>
```

`input` 支持 `fontSize`, (中文(简体) ), `color`, (中文(简体) ), `backgroundColor`, (中文(简体) ), `borderColor`, (中文(简体) ), `borderWidth`, (中文(简体) ), `borderRadius` 财务报告和审定财务报表 `padding`。 。 `focus` 财务报告和审定财务报表 `invalid` 对象 接受相同的属性;未指定属性继承了基础输入样式. 当一个无效字段被聚焦时,无效的样式优先 . 设定 `input.borderWidth` 改为 `'0px'` 为无边田地.

`label` 财务报告和审定财务报表 `error` 样式 hosted 标签和内置验证信件, 不 您的应用程序从会话错误中生成的消息 . `label.spacing` 控件 标签下的空格. `layout` 控制字段间的差距,而不是它们的顺序. 这些设置既适用于卡片,也适用于地址元素.

`appearance` 实值 `light` 或者说 `dark`。当省略时 `dark` 类 打开 `<html>`。默认使用16px输入文本,12px标签,1px边框, 8px角和12px输入垫.

使用字形颜色和系统字体. 主机字段无法继承您的页面 CSS自定义属性或字体. 将输入文本至少保存在 16px 上 .

## 许可证

麻省理工学院

## 常见问题

### @fragment-dev/payment-elements 是什么？

碎块支付元素的反应组件

### 如何安装 @fragment-dev/payment-elements？

在项目目录运行 npm install @fragment-dev/payment-elements，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fragment-dev/payment-elements 支持 TypeScript 吗？

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

### @fragment-dev/payment-elements 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fragment-dev/payment-elements 可以商用吗？

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

### @fragment-dev/payment-elements 的下载量有多少？

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

### @fragment-dev/payment-elements 还在维护吗？

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