# @gearbox-protocol/ui-kit 中文文档

规范地址：https://npmcn.com/package/%40gearbox-protocol/ui-kit/

版本：4\.12\.1
npm 元数据更新时间：2026-11-16T14:36:21.872Z
中文译文更新时间：2026-11-16T14:37:49.905Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，1536 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：24 个
- peer 依赖：viem ^2\.0\.0，react ^18 \|\| ^19，wagmi ^2\.0\.0 \|\| ^3\.0\.0，sonner ^2\.0\.0，react-intl ^6\.0\.0 \|\| ^7\.0\.0 \|\| ^10\.0\.0，tailwindcss ^4\.0\.0，@types/react ^18 \|\| ^19，react-router-dom ^6\.0\.0 \|\| ^7\.0\.0，@gearbox-protocol/sdk \*，@tanstack/react-query ^5\.0\.0
- 首次发布：2026-04-03T12:35:46.088Z
- 最新版本发布：2026-11-16T14:36:21.625Z
- 近 30 天下载量：4479（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：244（近 12 个月 244 个）

## 中文简介

内部用户界面组件

## 安装

```sh
npm install @gearbox-protocol/ui-kit
```

也可以使用：`pnpm add @gearbox-protocol/ui-kit`、`yarn add @gearbox-protocol/ui-kit`、`bun add @gearbox-protocol/ui-kit`

## README

# 无权限 UI

内部使用的UI组件 - 框架- 不可知反应组件库由 Tailwind CSS 4.

## 安装

```bash
pnpm install @gearbox-protocol/ui-kit
```

对于 Next.js 项目,也安装 Next.js :

```bash
pnpm install next
```

## 设置

### 1\. 配置尾风CSS

创建或更新您的 `tailwind.config.ts`数字 :

```typescript
import type { Config } from "tailwindcss";
import { preset } from "@gearbox-protocol/ui-kit/preset";

const config: Config = {
  presets: [preset],
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@gearbox-protocol/ui-kit/dist/**/*.js",
  ],
};

export default config;
```

### 2\. 导入全局样式

在您的主条目文件中 :

```typescript
import "@gearbox-protocol/ui-kit/globals.css";
```

### 3\. 添加主题提供者(可选)

对于暗模式支持 :

```tsx
import { ThemeProvider, ThemeScript } from "@gearbox-protocol/ui-kit";

// For Next.js App Router
export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <head>
        {/* Prevents flash of white cards on page load */}
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

// For other frameworks (CRA, Vite, etc.)
function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* Your app */}
    </ThemeProvider>
  );
}
```

## 使用量

### 基本组成部分系统

这个 `base/` 层`src/components/base/`)是犬科组件系统 由所有 Gearbox 前端共享 。 其合同居住在 [`docs/component-registry.md`](https://npmcn.com/package/%40gearbox-protocol/ui-kit/docs/component-registry.md)。要点:

-   **SDK型道具** - 组成部分接受 `@gearbox-protocol/sdk/model` 实体`Token`, (中文(简体) ), `TokenAmount`, (中文(简体) ), `HistorySeries`, (中文(简体) ), `PnlBreakdown`,而不是一个 铺起平板.
-   **仅设计** ——道具入出,JSX出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出.
-   **一个名字——一个执行** - 取代旧的基部分 `StatBadge`, (中文(简体) ), `PageTitle` 财务报告和审定财务报表 `DetailedPageTitle` 出口,以及 `VSpace` 现在 带 `size` 在共享间隔尺度上(数字是像素逃生) 舱门, `mobileSize` 覆盖移动半个).

```tsx
import {
  AmountInput,
  InfoLine,
  InfoList,
  ReviewButton,
  Stack,
  TokenAmount,
  VSpace,
} from '@gearbox-protocol/ui-kit';

function DepositDialog({ token, balance }) {
  const [amount, setAmount] = useState(0n);
  return (
    <Stack gap="md">
      <AmountInput amount={amount} onAmount={setAmount} token={token} balance={balance} />
      <VSpace size="md" />
      <InfoList>
        <InfoLine title={<span>You deposit</span>} value={<TokenAmount data={{ value: amount, valueUsd: null, token }} />} />
      </InfoList>
      <ReviewButton disabled={amount === 0n} error={null} onClick={openVerify} />
    </Stack>
  );
}
```

基本部件的测试标识通过节点安全 `@gearbox-protocol/ui-kit/test-ids`。 。 。 .

### 框架不可知性(各地的工作)

```tsx
import { Button, Input, Card } from '@gearbox-protocol/ui-kit';

function MyComponent() {
  return (
    <Card>
      <Input placeholder="Enter text" />
      <Button variant="default">Submit</Button>
    </Card>
  );
}
```

### 下一个.js 优化

```tsx
import { TokenIcon, BackButton, SIWEClientProvider } from '@gearbox-protocol/ui-kit/next';

// Uses Next.js Image, Link and useRouter
<TokenIcon symbol="ETH" size={48} />
<BackButton href="/dashboard" text="Back" />
```

### 钱包 UI 和 SIWE( 可选的连接 Kit)

`ConnectRequired`, (中文(简体) ), `SignInRequired`,并使用小的 **钱包 UI 适配器** 通过 `WalletUIProvider`您可以监听 **连接Kit** 或提供自己的适配器(例如 RainbowKit).

**连接Kit(当您已经使用 ConnectKit + SIWE 时推荐)**

安装 : `pnpm add connectkit` (可选的同伴依赖性).

```tsx
import { ConnectKitProvider } from "connectkit";
import {
  ConnectKitWalletAdapter,
  SIWEClientProvider,
} from "@gearbox-protocol/ui-kit/connectkit";

<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <SIWEClientProvider apiRoutePrefix="/api/auth" onRefresh={() => {}}>
      <ConnectKitProvider>
        <ConnectKitWalletAdapter>
          {children}
        </ConnectKitWalletAdapter>
      </ConnectKitProvider>
    </SIWEClientProvider>
  </QueryClientProvider>
</WagmiProvider>
```

**Next.js App路由器** - 使用下一种特定的SIWE包装器(呼叫) `router.refresh()` 注册/退出后:

```tsx
import { SIWEClientProvider } from "@gearbox-protocol/ui-kit/next/connectkit";
import { ConnectKitWalletAdapter } from "@gearbox-protocol/ui-kit/connectkit";

<SIWEClientProvider apiRoutePrefix="/api/auth">
  <ConnectKitProvider>
    <ConnectKitWalletAdapter>{children}</ConnectKitWalletAdapter>
  </ConnectKitProvider>
</SIWEClientProvider>
```

**彩虹Kit 或自定义钱包模式**

你不需要这样 `connectkit` 仅使用 `WalletUIProvider` 与你自己 `openConnectModal` (和可选的SIWE字段). 彩虹 Kit 示例:

```tsx
import { useConnectModal } from "@rainbow-me/rainbowkit";
import { WalletUIProvider } from "@gearbox-protocol/ui-kit";

function RainbowKitWalletAdapter({ children }: { children: React.ReactNode }) {
  const { openConnectModal } = useConnectModal();
  return (
    <WalletUIProvider
      value={{
        openConnectModal: openConnectModal ?? (() => {}),
      }}
    >
      {children}
    </WalletUIProvider>
  );
}
```

没有 `WalletUIProvider`, (中文(简体) ), `ConnectRequired` 编号 : `SignInRequired` 跳过他们的连接/ 签名UI 并让孩子( gracedality) .

### 用户协议

`@gearbox-protocol/ui-kit/user-agreements` 让钱包连接的 Gearbox apps 检查账户是否已经签署当前法律协议,请用户签名,并检测被封禁的区域. 它包含法律信息文本, `AgreementService` 用于与协议服务器交谈,以及 `useAgreement` 财务报告和审定财务报表 `useBlockedRegion` 钩子,需要 `wagmi` 财务报告和审定财务报表 `@tanstack/react-query`。这是一个单独的切入点,主要条目从不进口,所以不使用协议的应用程序既不装入,也不需要这些包。 见 [用户协议](https://npmcn.com/package/%40gearbox-protocol/ui-kit/docs/user-agreements.md) 完整文件,以及 [从亲吻移走](https://npmcn.com/package/%40gearbox-protocol/ui-kit/docs/migration-from-auth-kit.md) 如果你用过 `@gearbox-protocol/auth-kit`。 。 。 .

### 自定义组件

```tsx
import { TokenIcon, BackButton } from '@gearbox-protocol/ui-kit';
import MyImage from './MyImage';
import { Link } from 'react-router-dom';

<TokenIcon symbol="ETH" ImageComponent={MyImage} />
<BackButton href="/back" LinkComponent={Link} />
```

## 依赖关系

### 所需同伴依赖

这些依赖关系必须安装在您的工程中 :

```bash
pnpm install react react-dom @gearbox-protocol/sdk @tanstack/react-query viem wagmi reactochart
```

| 软件包 | 版本 | 说明 |
| --- | --- | --- |
| `react` | ^ 18 || 19 | 反应库 |
| `react-dom` | ^ 18 || 19 | 反应 DOM |
| `@gearbox-protocol/sdk` | \* 联合国 | Gearbox 协议 SDK |
| `@tanstack/react-query` | ^ 5.64.1 (中文(简体) ) | 数据获取和缓存 |
| `viem` | ^ 2. 0 | Ethereum 图书馆 |
| `wagmi` | ^ 2. 0 | Ethereum 的反应钩 |
| `reactochart` | ^6.1.1 (中文(简体) ) | 图表库(用于图表组件) |

### 可选同伴依赖关系

仅在使用特定特性时安装 :

| 软件包 | 版本 | 何时安装 |
| --- | --- | --- |
| `connectkit` | ^ 1.8.0 (韩语) | 连接 基特大学, `@gearbox-protocol/ui-kit/connectkit`,或者通过 ConnectKit 实现SIWE |
| `next` | \>=13 | 使用 `@gearbox-protocol/ui-kit/next` 出口 |
| `react-intl` | ^ 6. 0. ^ 7. 0 | 使用国际化特征 |
| `react-router-dom` | ^ 6. 0. ^ 7. 0 | 使用基于路由器的导航(非Next.js) |
| `sonner` | ^ 2. 0 | 使用土司通知 |

### 安装示例

**最小设置( 仅基本组件):**

```bash
pnpm install @gearbox-protocol/ui-kit react react-dom
```

**完整 Web3 设置( wagmi; 无连接Kit) :**

```bash
pnpm install @gearbox-protocol/ui-kit \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart
```

**完整 Web3 + 连接 Kit 适配器 :**

```bash
pnpm install @gearbox-protocol/ui-kit \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart
```

**与下一个.js:**

```bash
pnpm install @gearbox-protocol/ui-kit \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart
```

**与 Next.js 和 ConnectKit 的切入点 :**

```bash
pnpm install @gearbox-protocol/ui-kit \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart
```

**带有路由( 反应路由器) :**

```bash
pnpm install @gearbox-protocol/ui-kit \
  react react-dom react-router-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart
```

**随着国际化:**

```bash
pnpm install @gearbox-protocol/ui-kit react-intl
```

## 软件包导出

该图书馆提供几个切入点:

| 导出 | 说明 |
| --- | --- |
| `@gearbox-protocol/ui-kit` | 主要条目 - 所有框架不可知性组件 |
| `@gearbox-protocol/ui-kit/next` | Next.js 优化组件(图像、链接、路由器) |
| `@gearbox-protocol/ui-kit/connectkit` | 连接 基特桥: `ConnectKitWalletAdapter`, (中文(简体) ), `SIWEClientProvider` |
| `@gearbox-protocol/ui-kit/next/connectkit` | 下一个.js `SIWEClientProvider` 与 `router.refresh()` |
| `@gearbox-protocol/ui-kit/user-agreements` | 法律协议的签署和检查,见 [用户协议](https://npmcn.com/package/%40gearbox-protocol/ui-kit/docs/user-agreements.md) |
| `@gearbox-protocol/ui-kit/preset` | 尾风 CSS 预设 |
| `@gearbox-protocol/ui-kit/tailwind` | 尾风 CSS 配置 |
| `@gearbox-protocol/ui-kit/globals.css` | 全球CSS样式 |
| `@gearbox-protocol/ui-kit/grid-safelist.css` | 网格安全列表 CSS |
| `@gearbox-protocol/ui-kit/tx-preview` | 交易预览+确认模式(同化 WIP 模块) |

## 解决问题

### 模块未找到出错

如果你看到这样的错误 `Cannot find module '@gearbox-protocol/sdk'`,安装缺失的对等依赖 :

```bash
pnpm install @gearbox-protocol/sdk
```

### 类型脚本出错

安装反应类型定义 :

```bash
pnpm install -D @types/react @types/react-dom
```

### 尾风样式不起作用

1.  确定您已经将库的 dist 文件夹添加到您的 Tailwind 内容配置 :

```typescript
content: [
  "./node_modules/@gearbox-protocol/ui-kit/dist/**/*.js",
]
```

2.  导入条目文件中的全局样式 :

```typescript
import "@gearbox-protocol/ui-kit/globals.css";
```

### 下一个.j 特定部件不起作用

确定您已经安装了 Next.js 并从正确的路径导入 :

```typescript
// ✅ Correct
import { TokenIcon } from '@gearbox-protocol/ui-kit/next';

// ❌ Wrong - these won't have Next.js optimizations
import { TokenIcon } from '@gearbox-protocol/ui-kit';
```

### 向撰稿人提供的重要资料

作为Gearbox协议 GitHub 仓库的出资人, 您的拉动请求表示接受我们的 Gearbox 贡献协议 。 这份协议概述,你将你对Gearbox基金会的捐款指定为知识产权。 这有助于保护Gearbox协议并确保其知识产权的积累。 捐款成为储存库的一部分,可用于各种目的,包括商业目的。 作为对你专门知识和工作的表彰,你有机会参与议定书的制定,并有可能看到你的工作融入其中。 完整的Gearbox捐款协议可在 [仓库](https://npmcn.com/ContributionAgreement) 供全面理解。 \[一起创新

## 常见问题

### @gearbox-protocol/ui-kit 是什么？

内部用户界面组件

### 如何安装 @gearbox-protocol/ui-kit？

在项目目录运行 npm install @gearbox-protocol/ui-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.0\.0）、react（^18 \|\| ^19）、sonner（^2\.0\.0）、@types/react（^18 \|\| ^19）、@gearbox-protocol/sdk（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gearbox-protocol/ui-kit 支持 TypeScript 吗？

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

### @gearbox-protocol/ui-kit 支持 ESM 还是 CommonJS？

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

### @gearbox-protocol/ui-kit 可以商用吗？

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

### @gearbox-protocol/ui-kit 的下载量有多少？

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

### @gearbox-protocol/ui-kit 还在维护吗？

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

