From a5d903fa9c9bad5357d6ee3d7d65ee7117f224c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=84=9A=E6=8C=87=E5=AF=BC?= Date: Tue, 28 Nov 2023 09:51:45 +0800 Subject: [PATCH] docs: init guide and quick start doc (#128) Co-authored-by: yutingzhao1991 --- docs/guide/adapter.md | 13 ++++++ docs/guide/adapter.zh-CN.md | 13 ++++++ docs/guide/demos/guide.tsx | 38 +++++++++++++++++ docs/guide/demos/quick-start.tsx | 27 +++++++++++++ docs/guide/index.md | 50 +---------------------- docs/guide/index.zh-CN.md | 54 +++++-------------------- docs/guide/{wagmi.md => quick-start.md} | 6 +-- docs/guide/quick-start.zh-CN.md | 42 +++++++++++++++++++ docs/guide/sdk.md | 25 ------------ docs/guide/sdk.zh-CN.md | 25 ------------ docs/guide/wagmi.zh-CN.md | 38 ----------------- 11 files changed, 149 insertions(+), 182 deletions(-) create mode 100644 docs/guide/adapter.md create mode 100644 docs/guide/adapter.zh-CN.md create mode 100644 docs/guide/demos/guide.tsx create mode 100644 docs/guide/demos/quick-start.tsx rename docs/guide/{wagmi.md => quick-start.md} (51%) create mode 100644 docs/guide/quick-start.zh-CN.md delete mode 100644 docs/guide/sdk.md delete mode 100644 docs/guide/sdk.zh-CN.md delete mode 100644 docs/guide/wagmi.zh-CN.md diff --git a/docs/guide/adapter.md b/docs/guide/adapter.md new file mode 100644 index 000000000..bfa6d2181 --- /dev/null +++ b/docs/guide/adapter.md @@ -0,0 +1,13 @@ +--- +nav: Guide +group: + title: Advance + order: 2 +--- + +# Develope Adapter + + +:::warning +Waiting for writing... +::: diff --git a/docs/guide/adapter.zh-CN.md b/docs/guide/adapter.zh-CN.md new file mode 100644 index 000000000..49e242666 --- /dev/null +++ b/docs/guide/adapter.zh-CN.md @@ -0,0 +1,13 @@ +--- +nav: 指南 +group: + title: 高级 + order: 2 +--- + +# 开发适配器 + + +:::warning +Waiting for writing... +::: diff --git a/docs/guide/demos/guide.tsx b/docs/guide/demos/guide.tsx new file mode 100644 index 000000000..fd93e9f2a --- /dev/null +++ b/docs/guide/demos/guide.tsx @@ -0,0 +1,38 @@ +import { createConfig, configureChains } from 'wagmi'; +import { mainnet, polygon } from 'wagmi/chains'; +import { publicProvider } from 'wagmi/providers/public'; +import { MetaMaskConnector } from 'wagmi/connectors/metaMask'; +import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'; +import { WagmiWeb3ConfigProvider } from '@ant-design/web3-wagmi'; +import { ConnectButton, Connector } from '@ant-design/web3'; + +const { publicClient, chains } = configureChains([mainnet, polygon], [publicProvider()]); + +const config = createConfig({ + autoConnect: true, + publicClient, + connectors: [ + new MetaMaskConnector({ + chains, + }), + new WalletConnectConnector({ + chains, + options: { + showQrModal: false, + projectId: YOUR_WALLET_CONNET_PROJECT_ID, + }, + }), + ], +}); + +const App: React.FC = () => { + return ( + + + + + + ); +}; + +export default App; diff --git a/docs/guide/demos/quick-start.tsx b/docs/guide/demos/quick-start.tsx new file mode 100644 index 000000000..101c8199c --- /dev/null +++ b/docs/guide/demos/quick-start.tsx @@ -0,0 +1,27 @@ +import { createConfig, configureChains, mainnet } from 'wagmi'; +import { infuraProvider } from 'wagmi/providers/infura'; +import { WagmiWeb3ConfigProvider } from '@ant-design/web3-wagmi'; +import { NFTImage } from '@ant-design/web3'; + +const { publicClient } = configureChains( + [mainnet], + [ + infuraProvider({ + apiKey: YOUR_INFURA_API_KEY, + }), + ], +); + +const config = createConfig({ + publicClient, +}); + +const App: React.FC = () => { + return ( + + + + ); +}; + +export default App; diff --git a/docs/guide/index.md b/docs/guide/index.md index 805883f8a..71825a869 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,56 +1,10 @@ --- nav: Guide -group: Basic --- -# Quick Start +# Ant Design Web3 :::warning -Ant Design Web3 is still in *ALPHA*, and we are continuously improving it. If you have any suggestions, please feel free to provide them to us through [Github Issue](https://github.com/ant-design/ant-design-web3/issues). +Waiting for translation... ::: - -## Install Dependencies - -You can install the necessary dependencies using package management tools such as `npm` or `pnpm`. Here's an example: - -```shell -npm i @ant-design/web3 @ant-design/web3-ethereum --save -``` - -## Using UI Components - -`@ant-design/web3` is a pure UI component library that you can directly use. For example, you can use the `BrowserLink` component: - -```tsx | pure -import { BrowserLink } from '@ant-design/web3'; - -export default () => { - return ; -}; -``` - -## Connecting to the Blockchain - -You can also connect certain UI components to the blockchain by importing the `EthereumProvider` from `@ant-design/web3-ethereum`. The following example demonstrates how to display an NFT image using the `NFTImage` component. In this example, you can request NFT data through the blockchain node service provided by [zan.top](https://zan.top/). All you need to do is pass the `address` and `tokenId` to the component. - -```tsx | pure -import { EthereumProvider, createProvider, ZANJsonRpcProvider } from '@ant-design/web3-ethereum'; -import { NFTImage } from '@ant-design/web3'; - -const provider = createProvider({ - rpcs: [ - new ZANJsonRpcProvider({ - apiKey: 'd0eeefc2a4da4a8ba707889259b437d6', - }), - ], -}); - -export default () => { - return ( - - - - ); -}; -``` diff --git a/docs/guide/index.zh-CN.md b/docs/guide/index.zh-CN.md index fba567291..c10d32ee7 100644 --- a/docs/guide/index.zh-CN.md +++ b/docs/guide/index.zh-CN.md @@ -1,56 +1,24 @@ --- -nav: 指南 -group: 基础 +nav: Guide --- -# 快速开始 +# Ant Design Web3 :::warning -Ant Design Web3 还在 *ALPHA* 中，我们正在不断完善，如有建议欢迎通过 [Github Issue](https://github.com/ant-design/ant-design-web3/issues) 给我们提建议。 +Ant Design Web3 还在 *ALPHA* 中，我们正在不断完善，如有建议欢迎通过 [Github issues](https://github.com/ant-design/ant-design-web3/issues) 给我们提建议。 ::: -## 安装依赖 +Ant Design Web3 是一个基于 [Ant Design](https://ant.design/index-cn) 的 Web3 React 组件库，它提供了一系列的组件，可以帮助你快速构建去中心化应用（DApp）。 -你可以通过 `npm` 或者 `pnpm` 等包管理工具安装相关依赖，示例如下： +你可以通过以下任意方式使用 Ant Design Web3： -```shell -npm i @ant-design/web3 @ant-design/web3-ethereum --save -``` +- 仅仅通过 `@ant-design/web3` 直接使用 UI 组件，比如 `ConnectButton`、`Address` 等。连接区块链的部分你可以选择你喜欢的任何方式，比如 [ether](https://docs.ethers.org/v6/)、[viem](https://viem.sh/) 和 [web3.js](https://web3js.org/)。以及其它任何链的 SDK，包括非 EVM 兼容的区块链也可以使用这种方式来使用 Ant Design Web3。 +- 通过我们官方提供的 `@ant-design/web3-wagmi` 适配器配合 `@ant-design/web3` 使用，它基于 [wagmi](https://wagmi.sh/) 内置了和 EVM 兼容链的连接能力，你可以更加简单的使用 Ant Design Web3，不需要自己处理和区块链连接的相关逻辑。 +- 参考 `@ant-design/web3-wagmi` 的实现，自己实现一个类似的适配器，这样你就可以使用 wagmi 以外的其它方式连接不同的区块链了。具体实现方式可以参考[开发适配器](adapter.zh-CN.md)。 -## 使用 UI 组件 +下面是通过 `@ant-design/web3-wagmi` 的方式使用 Ant Design Web3 的一个例子： -`@ant-design/web3` 是一个纯 UI 组件，你可以直接使用它，比如你可以用 `BrowserLink`： + -```tsx | pure -import { BrowserLink } from '@ant-design/web3'; - -export default () => { - return ; -}; -``` - -## 连接区块链 - -你也可以通过引入 `@ant-design/web3-ethereum` 中的 `EthereumProvider` 让一些 UI 组件可以连接到区块链。比如下面的示例展示了如何通过 `NFTImage` 组件显示一个 NFT 图片。示例中，通过 [zan.top](https://zan.top/) 提供的区块链节点服务可以请求 NFT 数据，你只需要向组件传入 `address` 和 `tokenId` 即可。 - -```tsx | pure -import { EthereumProvider, createProvider, ZANJsonRpcProvider } from '@ant-design/web3-ethereum'; -import { NFTImage } from '@ant-design/web3'; - -const provider = createProvider({ - rpcs: [ - new ZANJsonRpcProvider({ - apiKey: 'd0eeefc2a4da4a8ba707889259b437d6', - }), - ], -}); - -export default () => { - return ( - - - - ); -}; -``` +如果你想要进一步尝试如何在自己的项目中使用 Ant Design Web3，或者想要从 0 创建一个基于 Ant Design Web3 的项目，你可以继续阅读[快速开始](quick-start.zh-CN.md)，祝你在 Web3 冲浪愉快！🌊🌊🌊 diff --git a/docs/guide/wagmi.md b/docs/guide/quick-start.md similarity index 51% rename from docs/guide/wagmi.md rename to docs/guide/quick-start.md index 4598ff698..30068df9e 100644 --- a/docs/guide/wagmi.md +++ b/docs/guide/quick-start.md @@ -1,11 +1,11 @@ --- nav: Guide -group: Advance +group: Basic --- -# Using with wagmi +# Quick Start :::warning -Waiting for translation +Waiting for translation... ::: diff --git a/docs/guide/quick-start.zh-CN.md b/docs/guide/quick-start.zh-CN.md new file mode 100644 index 000000000..26dccc413 --- /dev/null +++ b/docs/guide/quick-start.zh-CN.md @@ -0,0 +1,42 @@ +--- +nav: 指南 +group: 基础 +--- + +# 快速开始 + +> 在开始之前，推荐先学习 [React](https://react.dev)，并正确安装和配置了 [Node.js](https://nodejs.org/) v16 或以上。官方指南假设你已了解关于 HTML、CSS 和 JavaScript 的中级知识，并且已经基本掌握了 React 全家桶的正确开发方式。 + +## 安装依赖 + +你可以通过 `npm` 或者 `pnpm` 等包管理工具安装相关依赖，示例如下： + +```shell +npm i @ant-design/web3 @ant-design/web3-wagmi --save +``` + +## 使用 UI 组件 + +`@ant-design/web3` 是一个纯 UI 组件，你可以直接使用它，比如你可以用 `Address`： + +```tsx +import { Address } from '@ant-design/web3'; + +export default () => { + return
; +}; +``` + +## 连接以太坊 + +`@ant-design/web3` 本身不提供连接区块链的能力，它是一个纯粹的 UI 组件库，我们设计之初就考虑了它未来可以适配不同的区块链。但是我们官方基于 [wagmi](https://wagmi.sh/) 实现了一个适配器 `@ant-design/web3-wagmi`，它内置了和 EVM 兼容链的连接能力，你可以通过它来连接上以太坊。 + +在 `@ant-design/web3-wagmi` 中，我们暴露了一个组件 `WagmiWeb3ConfigProvider`，它封装了 wagmi 的 `WagmiConfig`。 + +你只要把 `WagmiWeb3ConfigProvider` 当做 `WagmiConfig` 来使用，这样在你的应用中的 Ant Design Web3 组件就可以自动连接上区块链了。 + +下面是一个例子，当你在 React 应用的最外层使用 `WagmiWeb3ConfigProvider` 后，你的应用中的 `NFTImage` 就可以自动从以太坊上获取 NFT 的相关信息并展示了。 + + + +当然，相比 `NFTImage`，可能我们使用更多的是连接区块链按钮的组件，你可以阅读 [Connector](/zh-CN/components/connector) 组件的具体文档来学习如何使用它。 diff --git a/docs/guide/sdk.md b/docs/guide/sdk.md deleted file mode 100644 index b9a55271d..000000000 --- a/docs/guide/sdk.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -nav: Guide -group: - title: Advance - order: 2 ---- - -# Using with SDKs - -The Provider created by `createProvider` in `@ant-design/web3-ethereum` conforms to the EIP1193 specification, allowing you to easily integrate it with various popular blockchain SDKs. For example, you can combine it with `ethers.js` as follows: - -```tsx | pure -import { createProvider } from '@ant-design/web3-ethereum'; -import { ethers } from 'ethers'; - -const provider = createProvider({ - rpcs: [ - new ZANJsonRpcProvider({ - apiKey: 'd0eeefc2a4da4a8ba707889259b437d6', - }), - ], -}); - -const etherProvider = new ethers.BrowserProvider(provider); -``` diff --git a/docs/guide/sdk.zh-CN.md b/docs/guide/sdk.zh-CN.md deleted file mode 100644 index 25fb98135..000000000 --- a/docs/guide/sdk.zh-CN.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -nav: 指南 -group: - title: 高级 - order: 2 ---- - -# 和 SDK 一起使用 - -`@ant-design/web3-ethereum` 中的 `createProvider` 创建出来的 Provider 满足 EIP1193 的规范，你可以很方便的和各种流行的区块链 SDK 结合使用。比如和 `ethers.js` 结合使用如下： - -```tsx | pure -import { createProvider } from '@ant-design/web3-ethereum'; -import { ethers } from 'ethers'; - -const provider = createProvider({ - rpcs: [ - new ZANJsonRpcProvider({ - apiKey: 'd0eeefc2a4da4a8ba707889259b437d6', - }), - ], -}); - -const etherProvider = new ethers.BrowserProvider(provider); -``` diff --git a/docs/guide/wagmi.zh-CN.md b/docs/guide/wagmi.zh-CN.md deleted file mode 100644 index 302cfaa29..000000000 --- a/docs/guide/wagmi.zh-CN.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -nav: 指南 -group: 高级 ---- - -# 和 wagmi 一起使用 - -你可以通过我们提供的 `@ant-design/web3-wagmi` 简单便捷地和 [wagmi](https://wagmi.sh/) 一起使用。wagmi 是一个面向以太坊的 React Hooks 库，它不提供 UI，Ant Design Web3 可以作为它的一个很好的补充。 - -另外通过 `@ant-design/web3-wagmi`，Ant Design Web3 的组件可以基于 wagmi 提供的 Hooks 更加便捷可靠地连接到区块链，使用的示例如下： - -```tsx | pure -import { WagmiConfig, createConfig, configureChains, mainnet } from 'wagmi'; -import { publicProvider } from 'wagmi/providers/public'; -import { WagmiWeb3ConfigProvider } from '@ant-design/web3-wagmi'; -import { NFTImage } from '@ant-design/web3'; - -const { chains, publicClient } = configureChains([mainnet], [publicProvider()]); - -const config = createConfig({ - autoConnect: true, - publicClient, -}); - -function App() { - return ( - - - - ); -} -``` - -除了需要引入 `WagmiWeb3ConfigProvider` 替代 `WagmiConfig` 外，你完全不需要改变 wagmi 的任何用法。 - -## 使用示例 - -