# @crossmint/client-sdk-react-ui 中文文档

规范地址：https://npmcn.com/package/%40crossmint/client-sdk-react-ui/

版本：5\.1\.0
npm 元数据更新时间：2026-11-10T15:57:03.107Z
中文译文更新时间：2026-11-11T01:38:37.979Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：550 kB，551 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：24 个
- peer 依赖：react \>=17\.0\.2，react-dom \>=17\.0\.2，@solana/web3\.js ^1\.98\.1
- 首次发布：2021-12-31T21:15:43.000Z
- 最新版本发布：2026-11-10T15:57:02.745Z
- 近 30 天下载量：120749（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：384（近 12 个月 87 个）

## 中文简介

反应 SDK 集成 [十字薄荷钱包](https://docs.crossmint.com/) 在您的申请。 提供供应商、钩子和内置UI,用于钱包的创建、签名、检察官办公室的核查和密码流.

## 安装

```sh
npm install @crossmint/client-sdk-react-ui
```

也可以使用：`pnpm add @crossmint/client-sdk-react-ui`、`yarn add @crossmint/client-sdk-react-ui`、`bun add @crossmint/client-sdk-react-ui`

## README

# 交叉薄荷反应SDK

反应 SDK 集成 [十字薄荷钱包](https://docs.crossmint.com/) 在您的申请。 提供供应商、钩子和内置UI,用于钱包的创建、签名、检察官办公室的核查和密码流.

## 先决条件

获取一个 **客户端** API 密钥从 [Crossmint 开发器控制台](https://docs.crossmint.com/introduction/platform/api-keys)。确保您的键有 **钱包 API** 启用范围,包括 `wallets.fund` 页:1 `stagingFund`。 。 。 .

## 安装

```bash
npm install @crossmint/client-sdk-react-ui
# or
pnpm add @crossmint/client-sdk-react-ui
# or
yarn add @crossmint/client-sdk-react-ui
```

## 快速启动

### 1\. 设置供应商

**带有 Crossmint Auth( 运行中的默认)**

```tsx
"use client";

import {
  CrossmintProvider,
  CrossmintAuthProvider,
  CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

export default function App({ children }) {
  return (
    <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}>
      <CrossmintAuthProvider>
        <CrossmintWalletProvider
          createOnLogin={{
            chain: "base-sepolia",
            recoveryMethods: [{ type: "email" }],
          }}
        >
          {children}
        </CrossmintWalletProvider>
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}
```

**带来您自己的认证**

当您的应用程序已经拥有认证提供者时使用, 并在生产中: 连接您的提供者并配置 [JWT 认证](https://docs.crossmint.com/introduction/platform/api-keys/jwt-authentication) 在 Crossmint 控制台(参见 [移动到生产](https://docs.crossmint.com/wallets/guides/crossmint-auth#move-to-production)) (中文(简体) ). 那就跳过 `CrossmintAuthProvider` 把你的供应商的JWT传给钱包SDK 见 [自定义认证指南](https://docs.crossmint.com/wallets/guides/bring-your-own-auth) 详细情况.

```tsx
"use client";

import {
  CrossmintProvider,
  CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

export default function App({ children }) {
  return (
    <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}>
      <CrossmintWalletProvider
        createOnLogin={{
          chain: "base-sepolia",
          recoveryMethods: [
            {
              type: "email",
              email: "user@example.com",
            },
          ],
        }}
      >
        {children}
      </CrossmintWalletProvider>
    </CrossmintProvider>
  );
}
```

### 2\. 使用钱包

```tsx
import { useWallet } from "@crossmint/client-sdk-react-ui";

function WalletActions() {
  const { wallet, status } = useWallet();

  if (status === "in-progress") return <p>Loading wallet...</p>;
  if (!wallet) return <p>No wallet</p>;

  // Staging only: mints USDXM, Crossmint's test stablecoin, into the wallet
  const handleFund = async () => {
    await wallet.stagingFund(10);
  };

  const handleSend = async () => {
    const tx = await wallet.send("0xRecipient", "usdxm", "10");
    console.log("Transaction:", tx.explorerLink);
  };

  return (
    <div>
      <p>Wallet: {wallet.address}</p>
      <button onClick={handleFund}>Get 10 USDXM</button>
      <button onClick={handleSend}>Send 10 USDXM</button>
    </div>
  );
}
```

## 供应商

| 提供者 | 目的 |
| --- | --- |
| `CrossmintProvider` | 根供养. 需要所有 Crossmint 特性 . |
| `CrossmintAuthProvider` | 认证(电子邮件:OTP、Google、Twitter/X)。 如果使用自己的认证可以选择 . |
| `CrossmintWalletProvider` | 钱包的创建、设备标志管理以及内置的OTP/passkey UI. |

### `createOnLogin` 配置

何时 `createOnLogin` 设置在 `CrossmintWalletProvider`,当用户在 :

```tsx
<CrossmintWalletProvider
  createOnLogin={{
    chain: "base-sepolia",       // required — the blockchain
    recoveryMethods: [{ type: "email" }], // required — recovery method config
    signers: [{ type: "device" }], // optional — defaults to device signer
  }}
>
```

`recoveryMethods` 接受每个链条上的方法列表,每个链条能够自行回收钱包:

```tsx
<CrossmintWalletProvider
  createOnLogin={{
    chain: "solana",
    recoveryMethods: [{ type: "email" }, { type: "external-wallet", address: "9WzD..." }],
  }}
>
```

## 钩子

### `useWallet()`

返回钱包实例和管理功能 :

```tsx
const {
  wallet,              // Wallet | undefined
  status,              // "not-loaded" | "in-progress" | "loaded" | "error"
  getWallet,           // (props: { chain, alias? }) => Promise<Wallet | undefined>
  createWallet,        // (props: ClientSideWalletCreateArgs) => Promise<Wallet | undefined>
  createDeviceSigner,  // () => Promise<DeviceSignerDescriptor> | undefined
  createPasskeySigner, // (name: string) => Promise<RegisterSignerPasskeyParams>
} = useWallet();
```

### `useWalletOtpSigner()`

对于使用电子邮件/电话回收方法时的自定义OTP UI:

```tsx
const { needsAuth, sendOtp, verifyOtp, reject } = useWalletOtpSigner();
```

### `useAuth()`

认证状态和登录方法 :

```tsx
const { login, logout, user, status } = useAuth();
```

## 构成部分

### `ExportPrivateKeyButton`

通过TEE对钱包的私钥导出按钮 。 只为电子邮件/手机签名人制作 .

```tsx
import { ExportPrivateKeyButton } from "@crossmint/client-sdk-react-ui";

<ExportPrivateKeyButton appearance={{ borderRadius: "12px" }} />
```

## 原生反应

关于反应原生应用程序,参见 [`@crossmint/client-sdk-react-native-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui)。 。 。 .

## 钱包 SDK

这个 `wallet` 对象返回 `useWallet()` 是一个 [`Wallet`](https://www.npmjs.com/package/@crossmint/wallets-sdk) 举个例子 钱包方法文档(端出、余额、符号等)见 [`@crossmint/wallets-sdk` 读取](https://www.npmjs.com/package/@crossmint/wallets-sdk)。 。 。 .

## 文档

-   [交叉薄荷钱包文档](https://docs.crossmint.com/)
-   [SDK 参考](https://docs.crossmint.com/sdk-reference/wallets/react)
-   [自定义认证指南](https://docs.crossmint.com/wallets/guides/bring-your-own-auth)

## SDK 参考文件生成

```
Source JSDoc -> TypeDoc -> api.json -+
                                    +-> generate-reference.mjs -> MDX pages (docs/<product>/)
                     examples.json -+
```

运行 `pnpm generate:docs` 或者说 `node scripts/generate-reference.mjs --product wallets`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 受保护买方领域(开发中)

独立渲染每个受保护的 UC 字段; HTML 窗体和 Crossmint 认证提供者 无需这样做。 提供者提供浏览器客户端密钥; `jwt` 可能来自 外部认证.

```tsx
const codeRef = useRef<CrossmintProtectedInputRef>(null);

<CrossmintProvider apiKey={clientApiKey}>
  <CrossmintProtectedInput ref={codeRef} field={codeField} jwt={buyerJwt} />
</CrossmintProvider>

const result = await codeRef.current.collect();
if (result.status === "collected") {
  // Combine with ordinary answers in the application's complete UC response.
  answers[codeField.key] = result.input;
} else {
  showError(result.message);
}
```

收藏返回 `collected`, (中文(简体) ), `invalid`, (中文(简体) ), `unavailable` 或者说 `superseded`。开发者 拥有提交和错误渲染。 认证更改和帧重装无效 等待东道方结果。 只有参考/结果元数据从主机iframe上交叉回. 认证跨越已验证的窗口通道,而不是iframe URL.

所支持的被保护输入是单行文本(可见或被遮蔽),数字和整数. 全部使用嵌入式基础理论文字元素; 符号化从不读取纯文本 Crossmint浏览器代码. 代码和标识符使用文本来保存准确的拼写. 未更改的引用被缓存到过期; 编辑、 清除、 认证或描述更改 无效收藏。 已禁用控件仍可被锁定提交时收集 .

这只取代密码 `merchantUrl`编号 :`onCreated` 接口。 匹配主机 iframe和每个外地的收集在当地实施。 SDK出版物,反应堆 部署和由供应商/浏览员组成的资格仍然是释放门。 追踪AGENT-473.

## 常见问题

### @crossmint/client-sdk-react-ui 是什么？

反应 SDK 集成 十字薄荷钱包 在您的申请。 提供供应商、钩子和内置UI,用于钱包的创建、签名、检察官办公室的核查和密码流\.

### 如何安装 @crossmint/client-sdk-react-ui？

在项目目录运行 npm install @crossmint/client-sdk-react-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17\.0\.2）、react-dom（\>=17\.0\.2）、@solana/web3\.js（^1\.98\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @crossmint/client-sdk-react-ui 支持 TypeScript 吗？

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

### @crossmint/client-sdk-react-ui 支持 ESM 还是 CommonJS？

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

### @crossmint/client-sdk-react-ui 可以商用吗？

@crossmint/client-sdk-react-ui 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @crossmint/client-sdk-react-ui 的下载量有多少？

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

### @crossmint/client-sdk-react-ui 还在维护吗？

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