Skip to content

Commit

Permalink
docs: add adapter docs (#165)
Browse files Browse the repository at this point in the history
* docs: add adapter docs

* fix: doc link bug

---------

Co-authored-by: yutingzhao1991 <[email protected]>
  • Loading branch information
yutingzhao1991 and yutingzhao1991 authored Dec 4, 2023
1 parent 70ec13f commit c30480e
Show file tree
Hide file tree
Showing 5 changed files with 132 additions and 10 deletions.
40 changes: 35 additions & 5 deletions docs/guide/adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,39 @@ group:
order: 2
---

# Develope Adapter
# Adapter

<!-- prettier-ignore -->
:::warning
Waiting for writing...
:::
## What is an adapter

In order to make Ant Design Web3 more flexible, and to support more types of blockchains, as well as better maintenance. We split Ant Design Web3 into multiple packages.

Among them, `@ant-design/web3` is the most core module, which contains a series of UI components. These UI components are pure React components, you can use them directly.

But if the developer only uses this part of the UI components, then the part that interacts with the blockchain still needs to be implemented by the developer. For example, the interface for connecting to the blockchain, getting blockchain information, etc. need to be implemented by the developer.

Therefore, we put forward the concept of an adapter, which can connect Ant Design Web3 UI components and the blockchain, so that these UI components can quickly connect to the blockchain. For example, when you use [@ant-design/web3-wagmi](../../packages/web3/src/wagmi/index.md), the `Connector`, `NFTCard` and other components can be directly connected to Ethereum.

## How does the adapter work?

In the [types](https://github.com/ant-design/ant-design-web3/blob/main/packages/common/src/types.ts) of `@ant-design/web3-common`, we define `UniversalWeb3ProviderInterface`, which contains the following types:

| Name | Type | Description |
| --- | --- | --- |
| account | [Account](../../packages/web3/src/types/index.md#account) | The currently connected account |
| chain | [Chain](../../packages/web3/src/types/index.md#chain) | The currently connected chain |
| availableWallets | [Wallet](../../packages/web3/src/types/index.md#wallet)\[\] | Available wallets |
| availableChains | `Chain[]` | Available chains |
| connect | `(wallet?: Wallet) => Promise<void>` | Connect wallet |
| disconnect | `() => Promise<void>` | Disconnect |
| switchChain | `(chain: Chain) => Promise<void>` | Switch chain |
| getNFTMetadata | `(params: { address: string; tokenId: bigint }) => Promise<NFTMetadata>` | Get NFT metadata |

In `@ant-design/web3` you can use [Web3ConfigProvider](../../packages/web3/src/web3-config-provider/index.md) to globally configure these properties, and Ant Design Web3 components will get the relevant content through React Context and use it. The adapter configures these properties for you to implement related functions, and of course you can also implement similar functions to the adapter by globally configuring `Web3ConfigProvider`. In fact, developing an adapter is based on this logic.

## Develop an adapter

As mentioned in the above section, you can use [Web3ConfigProvider](../../packages/web3/src/web3-config-provider/index.md) to provide UI components with related functions for interacting with the chain. We have currently implemented the adaptation of Ethereum based on [wagmi](https://wagmi.sh/). You can refer to its implementation to help Ant Design Web3 adapt to more blockchains. The following code is a simple implementation example of an adapter:

<code src="./demos/adapter.tsx"></code>

For more content, you can refer to the [code](https://github.com/ant-design/ant-design-web3/tree/main/packages/wagmi) of `@ant-design/web3-wagmi`.
40 changes: 35 additions & 5 deletions docs/guide/adapter.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,39 @@ group:
order: 2
---

# 开发适配器
# 适配器

<!-- prettier-ignore -->
:::warning
Waiting for writing...
:::
## 什么是适配器

为了让 Ant Design Web3 更加灵活,也为了可以支持更多类型的区块链,以及更好维护。我们将 Ant Design Web3 拆分为了多个包。

其中 `@ant-design/web3` 作为最核心的模块,它包含了一系列 UI 组件。这些 UI 组件是纯粹的 React 组件,你可以直接使用它们.

但是如果开发者仅仅是使用这部分 UI 组件,那么和区块链交互的部分还需要开发者自行实现。比如连接区块链,获取区块链信息等接口都需要开发者自行实现。

所以,我们提出了适配器的概念,适配器可以连接 Ant Design Web3 UI 组件和区块链,让这些 UI 组件可以快速连接上区块链。比如,当你使用了 [@ant-design/web3-wagmi](../../packages/web3/src/wagmi/index.zh-CN.md)后,`Connector``NFTCard` 等组件就可以直接连接上以太坊了。

## 适配器是如何工作的?

`@ant-design/web3-common`[类型](https://github.com/ant-design/ant-design-web3/blob/main/packages/common/src/types.ts)中,我们定义了 `UniversalWeb3ProviderInterface`,它包含了如下类型:

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| account | [Account](../../packages/web3/src/types/index.zh-CN.md#account) | 当前连接的账户 |
| chain | [Chain](../../packages/web3/src/types/index.zh-CN.md#chain) | 当前连接的链 |
| availableWallets | [Wallet](../../packages/web3/src/types/index.zh-CN.md#wallet)\[\] | 可用的钱包列表 |
| availableChains | `Chain[]` | 可用的链列表 |
| connect | `(wallet?: Wallet) => Promise<void>` | 连接钱包 |
| disconnect | `() => Promise<void>` | 断开连接 |
| switchChain | `(chain: Chain) => Promise<void>` | 切换链 |
| getNFTMetadata | `(params: { address: string; tokenId: bigint }) => Promise<NFTMetadata>` | 获取 NFT 元数据 |

`@ant-design/web3` 中你可以通过 [Web3ConfigProvider](../../packages/web3/src/web3-config-provider/index/zh-CN.md) 全局配置这些属性,Ant Design Web3 的组件会通过 React Context 获取到相关内容并使用。而适配器则是通过帮你配置了这些属性而实现相关功能,当然你也可以自己通过全局配置 `Web3ConfigProvider` 来实现和适配器类似的功能。实际上,开发适配器便是基于这个逻辑。

## 开发适配器

如上面部分所说,你可以通过 [Web3ConfigProvider](../../packages/web3/src/web3-config-provider/index/zh-CN.md) 来给 UI 组件提供和链交互的相关功能。我们目前基于 [wagmi](https://wagmi.sh/) 实现了以太坊的适配,你可以参考它的实现来帮组 Ant Design Web3 适配更多的区块链。下面的代码就是一个简单的适配器的简单实现示例:

<code src="./demos/adapter.tsx"></code>

更多内容你可以参考 `@ant-design/web3-wagmi`[实现代码](https://github.com/ant-design/ant-design-web3/tree/main/packages/wagmi)
58 changes: 58 additions & 0 deletions docs/guide/demos/adapter.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import React from 'react';
import { type Account, type Wallet, type Chain, Web3ConfigProvider } from '@ant-design/web3-common';
import { Connector, ConnectButton } from '@ant-design/web3';

export interface YourAdapterProps {
wallets?: Wallet[];
children?: React.ReactNode;
availableChains?: Chain[];
}

export const YourAdapterPropsProvider: React.FC<YourAdapterProps> = (props) => {
const { children, availableChains, wallets } = props;
const [account, setAccount] = React.useState<Account>({
address: '0xtestaccount',
});
const [currentChain, setCurrentChain] = React.useState<Chain>();

return (
<Web3ConfigProvider
availableChains={availableChains}
chain={currentChain}
account={account}
availableWallets={wallets}
connect={async (wallet) => {
// 这里可以实现连接钱包的逻辑
return;
}}
disconnect={async () => {
// 这里可以实现断开连接的逻辑
return;
}}
switchChain={async (c: Chain) => {
// 这里可以实现切换链的逻辑
return;
}}
getNFTMetadata={async ({ address: contractAddress, tokenId }) => {
// 这里可以实现获取 NFT 元数据的逻辑
return {
name: 'NFT',
description: 'NFT description',
image: 'https://avatars.githubusercontent.com/u/1061968',
};
}}
>
{children}
</Web3ConfigProvider>
);
};

export default () => {
return (
<YourAdapterPropsProvider>
<Connector>
<ConnectButton />
</Connector>
</YourAdapterPropsProvider>
);
};
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
"@ant-design/web3": "workspace:*",
"@ant-design/web3-ethereum": "workspace:*",
"@ant-design/web3-wagmi": "workspace:*",
"@ant-design/web3-common": "workspace:*",
"@biomejs/biome": "^1.0.0",
"@changesets/changelog-git": "^0.1.14",
"@changesets/cli": "^2.26.2",
Expand Down
3 changes: 3 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit c30480e

Please sign in to comment.