# @0xsequence/connect 中文文档

规范地址：https://npmcn.com/package/%400xsequence/connect/

版本：5\.4\.12
npm 元数据更新时间：2026-07-13T13:06:22.788Z
中文译文更新时间：2026-11-06T08:31:42.504Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%400xsequence/connect
原文对照：https://npmcn.com/package/%400xsequence/connect/?lang=original
项目主页：https://github.com/0xsequence/web-sdk/tree/master#readme
源码仓库：https://github.com/0xsequence/web-sdk#master

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

- 包体积（解压后）：1.9 MB，1188 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：15 个
- peer 依赖：0xsequence \>= 2\.3\.43，@databeat/tracker ^0\.9\.3，@react-oauth/google ^0\.11\.1，@tanstack/react-query \>= 5，ethers \>=6\.13\.0，react \>= 17，react-apple-signin-auth ^1\.1\.0，react-dom \>= 17，viem \>= 2\.44\.0，wagmi \>= 2\.19\.0，@0xsequence/hooks 5\.4\.12
- 首次发布：2025-03-14T20:53:47.915Z
- 最新版本发布：2026-07-13T13:06:22.627Z
- 近 30 天下载量：3824（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：100（近 12 个月 34 个）

## 中文简介

序列 Web SDK 的连接软件包

## 安装

```sh
npm install @0xsequence/connect
```

也可以使用：`pnpm add @0xsequence/connect`、`yarn add @0xsequence/connect`、`bun add @0xsequence/connect`

## README

# 序列 Web SDK QQ

序列Week SDK QQ是一个库,使开发者能够轻松地将Web3钱包整合到他们的应用中. 这是基于 [华为](https://wagmi.sh/) 并且支持所有wagmi特性.

-   通过社交登录 eg: facebook, google, 不和等连接...
-   连接到流行的 Web3 钱包 : 钱包Connect, metamask! QQQ
-   硬币和收藏品的完整嵌入式钱包
-   菲亚特·翁兰普(英语:Fiat onramp (film))
-   内部连接用户界面用于自定义布局和嵌入式体验QQ

查看 [演示](https://0xsequence.github.io/web-sdk)!

## 快速启动

### 安装图书馆

`@0xsequence/connect` 是核心软件包。 任何额外的模块都需要先安装此软件包. 要安装此软件包 :

```bash
npm install @0xsequence/connect @0xsequence/hooks wagmi ethers@6.13.0 viem 0xsequence @tanstack/react-query
# or
pnpm install @0xsequence/connect @0xsequence/hooks wagmi ethers@6.13.0 viem 0xsequence @tanstack/react-query
# or
yarn add @0xsequence/connect @0xsequence/hooks wagmi ethers@6.13.0 viem 0xsequence @tanstack/react-query
```

### 设立图书馆

#### "轻松"的方式

-   `createConfig(walletType, options)` 用于创建初始配置并准备可以被推翻的合理默认值

`walletType` 是“ waas” 或“ 通用 ”

```ts
interface CreateConfigOptions {
  appName: string
  projectAccessKey: string
  chainIds?: number[]
  defaultChainId?: number
  disableAnalytics?: boolean
  defaultTheme?: Theme
  position?: ModalPosition
  customCSS?: string // Injected into shadow dom
  trailsCustomCSS?: string | { light?: string; dark?: string }
  signIn?: {
    logoUrl?: string
    projectName?: string
    useMock?: boolean
  }
  displayedAssets?: Array<{
    contractAddress: string
    chainId: number
  }>
  ethAuth?: EthAuthSettings
  onConnectSuccess?: (address: string) => void // callback fired when wallet connects

  wagmiConfig?: WagmiConfig // optional wagmiConfig overrides

  waasConfigKey: string
  enableConfirmationModal?: boolean

  walletConnect?:
    | boolean
    | {
        projectId: string
      }

  guest?: boolean

  google?:
    | boolean
    | {
        clientId: string
      }

  apple?:
    | boolean
    | {
        clientId: string
        redirectURI: string
      }

  X?:
    | boolean
    | {
        clientId: string
        redirectURI: string
      }

  email?:
    | boolean
    | {
        legacyEmailAuth?: boolean
      }
}
```

```js
import { SequenceConnect, createConfig } from '@0xsequence/connect'

import Content from './components/Content'

const config = createConfig('waas', {
  projectAccessKey: '<your-project-access-key>',
  chainIds: [1, 137],
  defaultChainId: 1,
  appName: 'Demo Dapp',
  waasConfigKey: '<your-waas-config-key>',

  guest: true,

  google: {
    clientId: '<your-google-client-id>'
  },

  apple: {
    clientId: '<your-apple-client-id>',
    redirectURI: '...'
  },

  X: {
    clientId: '<your-X-client-id>',
    redirectURI: '...'
  },

  walletConnect: {
    projectId: '<your-wallet-connect-id>'
  },

  email: true
})

function App() {
  return (
    <SequenceConnect config={config}>
      <Content />
    </SequenceConnect>
  )
}
```

#### 关于X(原Twitter)认证的说明. X认证特别需要回调路由;要么是前端页面,要么是后端端端. 前端示例回调页如下:

请确保重定向 uri 和 回调页面路由完全相同, 否则 X 将拒绝认证

```js
export function XAuthCallback() {
  useEffect(() => {
    const query = new URLSearchParams(window.location.search)

    const payload = {
      code: query.get('code'),
      state: query.get('state')
    }

    if (window.opener) {
      window.opener.postMessage({ type: 'OAUTH_RETURN', data: payload }, '*')
    }

    window.close()
  }, [])

  return (
    <h3>
      you may now close this window.
    </h3>
  )
}
```

#### 需要更多定制吗?

React App必须被Wagmi客户端和序列WalletProvider组件所包裹. 重要的是,Wagmi包装纸要先于序列Web SDK包装.

```js
import Content from './components/Content'
import { SequenceConnectProvider, getDefaultConnectors, getDefaultChains } from '@0xsequence/connect'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { createConfig, http, WagmiProvider } from 'wagmi'
import { mainnet, polygon, Chain } from 'wagmi/chains'

const projectAccessKey = 'xyz'

const chains = getDefaultChains(/* optional array of chain ids to filter */)

const transports = {}

chains.forEach(chain => {
  transports[chain.id] = http()
})

const connectors = getDefaultConnectors('universal', {
  projectAccessKey,
  appName: 'demo app',
  defaultChainId: 137,

  walletConnect: {
    projectId: '<your-wallet-connect-project-id>'
  }
})

const config = createConfig({
  chains,
  transports,
  connectors
})

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <SequenceConnectProvider>
          <Content />
        </SequenceConnectProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

### 在 Modal 打开标志

![](https://npmcn.com/package/%400xsequence/connect/public/docs/sign-in-modal.png)

钱包的选择是通过一种可称为方案模式的方式进行的.

```js
import { useOpenConnectModal } from '@0xsequence/connect'
import { useDisconnect, useAccount } from 'wagmi'

const MyReactComponent = () => {
  const { setOpenConnectModal } = useOpenConnectModal()

  const { isConnected } = useAccount()

  const onClick = () => {
    setOpenConnectModal(true)
  }

  return <>{!isConnected && <button onClick={onClick}>Sign in</button>}</>
}
```

### 内置连接 UI

![Inline Connect UI](https://npmcn.com/package/%400xsequence/connect/public/docs/inline-connect.png)

与其使用模式,不如使用 `SequenceConnectInline` 组件。 这最适合自定义布局,嵌入式钱包体验,或者当您希望连接的UI成为您页面流量的一部分时.

```js
import { SequenceConnectInline, createConfig } from '@0xsequence/connect'
import { useNavigate } from 'react-router-dom'

const config = createConfig('waas', {
  projectAccessKey: '<your-project-access-key>',
  chainIds: [1, 137],
  defaultChainId: 1,
  appName: 'Demo Dapp',
  waasConfigKey: '<your-waas-config-key>',

  // Optional: callback fired when wallet connects successfully
  onConnectSuccess: (address) => {
    console.log('Connected wallet:', address)
    // Redirect or perform other actions
  },

  google: { clientId: '<your-google-client-id>' },
  email: true
})

function InlinePage() {
  return (
    <div className="my-custom-layout">
      <h1>Connect Your Wallet</h1>
      <SequenceConnectInline config={config} />
    </div>
  )
}
```

#### 与 Modal UI 的关键差异 :

-   **无垫/边距**: 内置的 UI 取消了为模式显示而设计的默认编码
-   **全宽**: 组件填充其容器宽度
-   **无模式背景**: 在您的布局中直接显示
-   **自定义定位**: 您用您的 CSS/ layout 控制位置

#### 高级: 使用序列连接Inline提供

为了控制更多,可以使用下级 `SequenceConnectInlineProvider`数字 :

```js
import { SequenceConnectInlineProvider } from '@0xsequence/connect'
import { WagmiProvider } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SequenceConnectInlineProvider config={connectConfig}>
          <YourContent />
        </SequenceConnectInlineProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

## 钩子

### 使用 OpenConnect Modal 移动

使用 `useOpenConnectModal` 以打开或关闭连接模式.

```js
import { useOpenConnectModal } from '@0xsequence/connect'
// ...
const { setOpenConnectModal } = useOpenConnectModal()
setOpenConnectModal(true)
```

### 使用主题

使用 `useTheme` 钩来获取关于当前主题的信息,例如光或暗等,或者将其设定为其它的东西.

```js
import { useTheme } from '@0xsequence/connect'
const { theme, setTheme } = useTheme()

setTheme('light')
```

## 自定义

这个 `SequenceConnectProvider` 包装可以接受可选的配置对象.

在序列Web SDK文档中更详细地描述了这些设置.

```js

  const connectConfig =  {
    defaultTheme: 'light',
    position: 'top-left',
    signIn: {
      logoUrl: 'https://logo-dark-mode.svg',
      projectName: 'my app',
    },
    // limits the digital assets displayed on the assets summary screen
    displayedAssets: [
      {
        contractAddress: zeroAddress,
        chainId: 137,
      },
      {
        contractAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
        chainId: 137
      }
    ],
    readOnlyNetworks: [10],
    // callback fired when wallet connects successfully
    onConnectSuccess: (address) => {
      console.log('Wallet connected:', address)
      // Perform actions like redirecting, analytics tracking, etc.
    },
  }

  <SequenceConnectProvider config={connectConfig}>
    <App />
  <SequenceConnectProvider>
```

## 软件包

| 软件包 | 说明 | 文档 |
| --- | --- | --- |
| [@ 0x序列/ 连接](https://github.com/0xsequence/web-sdk/tree/master/packages/connect) | 序列 Web SDK 核心软件包 | [更多信息](https://github.com/0xsequence/web-sdk/blob/master/packages/connect/README.md) |
| [@ 0x序列/ wallet- widget](https://github.com/0xsequence/web-sdk/tree/master/packages/wallet-widget) | 用于取景和发送硬币和收藏品的嵌入式钱包 | [更多信息](https://github.com/0xsequence/web-sdk/blob/master/packages/wallet-widget/README.md) |
| [@ 0x序列/ 检查退出](https://github.com/0xsequence/web-sdk/tree/master/packages/checkout) | 使用fiat onramp的退出模式 | [更多信息](https://github.com/0xsequence/web-sdk/blob/master/packages/checkout/README.md) |
| [实例反应](https://github.com/0xsequence/web-sdk/tree/master/examples/react) | 显示签名、钱包和退出的应用程序示例 | [更多信息](https://github.com/0xsequence/web-sdk/blob/master/examples/react/README.md) |

## 地方发展

![](https://npmcn.com/package/%400xsequence/connect/public/docs/web-sdk-demo.png)

React 示例可用于本地测试库.

1.  `pnpm install`
2.  从根文件夹中运行 `pnpm build` 用来构建软件包.
3.  从根文件夹中运行 `pnpm dev:react` 或者说 `pnpm dev:next` 以运行示例.

## 接下来怎么办?

现在核心软件包已经安装,你可以安装 [嵌入的钱包](https://github.com/0xsequence/web-sdk/tree/master/packages/wallet-widget) 或看一个 [离职](https://github.com/0xsequence/web-sdk/tree/master/packages/checkout)。 。 。 .

## 自由主义

阿帕奇 - 2.0

版权 (c) 2017年至今 序列平台 ULC. / [https://sequence.xyz (英语)](https://sequence.xyz/)

## 常见问题

### @0xsequence/connect 是什么？

序列 Web SDK 的连接软件包

### 如何安装 @0xsequence/connect？

在项目目录运行 npm install @0xsequence/connect，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：0xsequence（\>= 2\.3\.43）、@databeat/tracker（^0\.9\.3）、@react-oauth/google（^0\.11\.1）、@tanstack/react-query（\>= 5）、ethers（\>=6\.13\.0）、react（\>= 17）、react-apple-signin-auth（^1\.1\.0）、react-dom（\>= 17）、viem（\>= 2\.44\.0）、wagmi（\>= 2\.19\.0）、@0xsequence/hooks（5\.4\.12）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @0xsequence/connect 支持 TypeScript 吗？

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

### @0xsequence/connect 支持 ESM 还是 CommonJS？

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

### @0xsequence/connect 可以商用吗？

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

### @0xsequence/connect 的下载量有多少？

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

### @0xsequence/connect 还在维护吗？

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