# @gooddollar/web3sdk-v2 中文文档

规范地址：https://npmcn.com/package/%40gooddollar/web3sdk-v2/

版本：0\.4\.49
npm 元数据更新时间：2026-11-05T15:18:41.298Z
中文译文更新时间：2026-11-16T19:19:19.185Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gooddollar/web3sdk-v2
原文对照：https://npmcn.com/package/%40gooddollar/web3sdk-v2/?lang=original
源码仓库：https://github.com/GoodDollar/GoodWeb3-mono/packages/sdk-v2

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

- 包体积（解压后）：4 MB，809 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：35 个
- peer 依赖：viem 2\.\*，react \>=17，wagmi 2\.\*，react-native \*，@reown/appkit 1\.\*，@usedapp/core \*，react-native-web \*，@tanstack/react-query 5\.\*，@reown/appkit-adapter-wagmi 1\.\*，@react-native-async-storage/async-storage 1\.17\.10
- 首次发布：2022-06-27T10:04:43.253Z
- 最新版本发布：2026-11-05T15:18:40.184Z
- 近 30 天下载量：3880（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：457（近 12 个月 16 个）

## 中文简介

基于 GoodDollar 协议的 useapp sdk 的醚和反应钩

## 安装

```sh
npm install @gooddollar/web3sdk-v2
```

也可以使用：`pnpm add @gooddollar/web3sdk-v2`、`yarn add @gooddollar/web3sdk-v2`、`bun add @gooddollar/web3sdk-v2`

## README

# GoodUI Web3 语句

一个环绕用过的应用的包装器,提供了使用web3的上下文. 所有废旧设备都可以使用,此外还有下列有用设备:

-   多呼特定链条
-   请求网络切换的顶端应用程序
-   发送 TXs 事件

## 如何使用

### Web3 语句

供应 `usedapp` 如平时相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

```
import { Web3Provider, Fuse } from "../contexts/Web3Context";
import { useMulticallAtChain, CallsResult } from './useMulticallAtChain'
import { Mainnet, Call } from "@usedapp/core";
...

<Web3Provider config={{ multicallVersion: 1, networks: [Fuse, Mainnet], readOnlyUrls: { 122: 'https://rpc.fuse.io' } }}>
  <YourAPP />
</Web3Provider>
```

## 保留限额QA模式

共享的选入 API 是 `qa?: { forceTradeLimits?: boolean }` 在SDK时 `Web3Provider`. 议定书UI应绘制地图 `REACT_APP_QA_FORCE_TRADE_LIMITS=true` 改为 `qa={{ forceTradeLimits: true }}` 并打开标有QA的门 `useWeb3Context().qa?.forceTradeLimits === true`。缺失或虚假的能力意味着活动中的SDK不支持这一模式.

SDK额外要求 `NODE_ENV === "development"`;生产建设总是将有效能力报告为虚假,不激活QA路径. 这一建设保障独立于 `env`,选择合同部署。 使用 Celo/XDC 主网只读的RPC数据,而不是改变部署环境. 在Celo/XDC上,互换In/swapOut的呼叫可以提高识别值 `L0Out Exceeded` 在不请求签名或提交交易的情况下,通过现有的分类器出错 。 直接批准和其他预备役提交通知被封存,另有QA-失效错误. 余额、津贴、成功/接收状态以及交易现场执行不模拟.

重建并使用 SDK `yarn workspace @gooddollar/web3sdk-v2 build`中运行 ctix 和 TypeScript 构建,然后是 `yalc publish --push --sig`; npm 发布对等QA工作流程不需要.

### 发射 TX

通知收听者关于TX 你的同事已经做了 其他组件收听 TX

```
import { Web3Context, TxDetails } from "../contexts/Web3Context";

const { txEmitter } = useContext(Web3Context)

txEmitter.emit({title: 'test tx',txhash:'0x0', from:'0x1', to:'0x2'}: TxDetails)
txEmitter.on((tx:TxDetails) = > console.log(tx))
```

## 钩子

### 使用网络交换器

如果您正在使用 GoodUI 组件, 他们需要能够请求网络切换 . 您可以通过调用来提供此函数 `setSwitchNetwork(() => (chainId) => Promise<Boolean | undefined>` 与你的功能. 您的应用程序需要在调用 funciton 时执行网络切换的逻辑 . 如果切换不全,则您的函数应当返回虚假.

```
import { useSwitchNetowrk } from "@gooddollar/web3context";
...
const { switchNetwork, setSwitchNetwork } = useSwitchNetowrk()
const switchit = useCallback(async (id: number) => {
        console.log("setting network:", id)
        return true
},[])
setSwitchNetwork(() => switchit) //this is required, you need to pass a function that returns your functions
```

如果您正在构建一个组件, 那么组件可以通过调用来信号它需要网络切换的附加应用程序 `switchNetwork(chainId):Promise<Boolean | undefined>`

### 使用多CallAtChain系统

使用在 useapp 配置中为该链定义的 rpc 对特定链进行多调用 `readOnlyUrls`

```
import { ERC20Interface } from "@usedapp/core";
import { Contract } from "ethers"
import { useMulticallAtChain, CallsResult } from './useMulticallAtChain'

...
const callMulti = useMulticallAtChain(122)
const [results, setResults] = useState<CallsResult>()
const calls: Call[] = [
  {
      contract: new Contract("0x495d133B938596C9984d462F007B676bDc57eCEC", ERC20Interface),
      method: 'balanceOf',
      args: ['0x66582D24FEaD72555adaC681Cc621caCbB208324']
  },
  {
      contract: new Contract("0x495d133B938596C9984d462F007B676bDc57eCEC", ERC20Interface),
      method: 'totalSupply',
      args: []
  }]

const results = await callMulti(calls)
```

## 常见问题

### @gooddollar/web3sdk-v2 是什么？

基于 GoodDollar 协议的 useapp sdk 的醚和反应钩

### 如何安装 @gooddollar/web3sdk-v2？

在项目目录运行 npm install @gooddollar/web3sdk-v2，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（2\.\*）、react（\>=17）、wagmi（2\.\*）、react-native（\*）、@reown/appkit（1\.\*）、@usedapp/core（\*）、react-native-web（\*）、@tanstack/react-query（5\.\*）、@reown/appkit-adapter-wagmi（1\.\*）、@react-native-async-storage/async-storage（1\.17\.10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gooddollar/web3sdk-v2 支持 TypeScript 吗？

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

### @gooddollar/web3sdk-v2 支持 ESM 还是 CommonJS？

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

### @gooddollar/web3sdk-v2 可以商用吗？

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

### @gooddollar/web3sdk-v2 的下载量有多少？

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

### @gooddollar/web3sdk-v2 还在维护吗？

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

