# 注入对象

提示

阅读我们建议所有 web3 网站开发人员阅读基本用法部分。

Coinhub App 会将全局的 window.ethereum 变量注入用户访问的网站中。

该 API 允许网站请求用户的以太坊帐户，从用户连接的区块链中读取数据，并建议用户签署消息和交易。ethereum 对象的存在指示以太坊用户。我们建议在任何平台或浏览器上使用 typeof window !== 'undefined' && window.ethereum 来检测是否存在 Coinhub App。

以太坊 JavaScript 注入的对象 API 内容由 EIP-1193 (opens new window) 指定。

if (typeof window !== 'undefined' && window.ethereum) {
  startApp(provider); // 初始化 APP
} else {
  console.log('请链接钱包');
}

# 基本用法

为了使任何 Dapp Web 应用程序和网站正常工作，您必须：

检测 ethereum 对象是否注入（window.ethereum）
检测用户连接到哪个以太坊网络
获取用户连接的以太坊账户

此页面顶部的代码段足以检测对象是否正确注入。

创建完整功能的 web3 应用程序所需的全部是提供者 API。

就是说，许多开发人员使用第三方模块，例如 ethers (opens new window) ，而不是直接使用注入对象。如果您需要比此 API 提供的抽象更高的抽象，我们建议您使用第三方库。

# 链 ID

这些是默认情况下 Coinhub App 支持的 EVM 链的 ID，有关更多信息，请查阅 chainid.network (opens new window)。

十六进制	十进制	网络
0x1	1	Ethereum 以太坊主网
0x38	56	BSC 币安智能链主网
0x80	128	HECO 火币生态链主网
0x41	65	OEC 欧易交易链主网
0x89	137	Polygon 主网
0xfa	250	Fantom 主网
0x64	100	xDai 主网
0x3	3	Ropsten 测试网
0x2a	42	kovan 测试网
0x4	4	Rinkeby 测试网

# 方法

# ethereum.isConnected()

提示

请注意，此方法与用户帐户无关。

关于一个 web3 网站是否可以访问该用户的帐户，您可能经常遇到「已连接」一词。但是，在注入对象界面中，「已连接」和「已断开连接」是指注入对象是否可以向当前链发出 RPC 请求。

ethereum.isConnected(): boolean;

如果注入对象已连接到当前链，则返回true，否则返回false 。

如果未连接注入对象，则必须重新加载页面才能重新建立连接。有关更多信息，请参见连接和断开连接事件。

# ethereum.request(args)

interface RequestArguments {
  method: string;
  params?: unknown[] | object;
}
ethereum.request(args: RequestArguments): Promise<unknown>;

使用 request 通过 Coinhub App 将 RPC 请求提交给以太坊链。它返回一个 Promise，解析为 RPC 方法调用的结果。

参数和返回值将因 RPC 方法而异。实际上，如果一个方法具有 params 参数，则它们几乎总是类型为Array<any>。

如果请求由于任何原因而失败，则 Promise 将拒绝并返回以太坊 RPC 错误。

除了许多可能不支持的方法外，Coinhub App 还支持大多数标准化的以太坊 RPC 方法。其他钱包支持。有关详细信息，请参见 RPC API 。

# 示例

params: [
  {
    from: '0xb60e8dd61c5d32be8058bb8eb970870f07233155',
    to: '0xd46e8dd67c5d32be8058bb8eb970870f07244567',
    gas: '0x76c0', // 30400
    gasPrice: '0x9184e72a000', // 10000000000000
    value: '0x9184e72a', // 2441406250
    data: '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675',
  },
];
ethereum
  .request({
    method: 'eth_sendTransaction',
    params,
  })
  .then((result) => {
    // RPC 返回的结果会作为 result
    // 当方法成功时，会返回一个十六进制的字符串作为交易哈希
  })
  .catch((error) => {
    // 如果交易失败，则 Promise 会 reject 并返回一个错误
  });

# 事件

Coinhub App 注入对象实现了Node.js EventEmitter (opens new window) API。本节详细介绍了通过该 API 发出的事件。在其他地方有无数的EventEmitter指南，但是您可以监听这样的事件：

ethereum.on('accountsChanged', (accounts) => {
  // 当有账户变化时，则会触发这个回调函数
  // "accounts" 永远是一个数组，但是有可能是空的
});
ethereum.on('chainChanged', (chainId) => {
  // 处理当有了一条新的选中的链时，会触发这里的回调函数
  window.location.reload();
});

# 连接

interface ConnectInfo {
  chainId: string;
}
ethereum.on('connect', handler: (connectInfo: ConnectInfo) => void);

当 Coinhub App 注入对象首次能够将 RPC 请求提交到链时，它将发出此事件。我们建议使用 connect 事件处理程序和ethereum.isConnected()方法，以确定何时 / 是否连接了注入 API。

# 断开连接

ethereum.on('disconnect', handler: (error: ProviderRpcError) => void);

如果 Coinhub App 注入对象无法将 RPC 请求提交到任何链，它将发出此事件。通常，这只会由于网络连接问题或某些无法预料的错误而发生。

一旦发出 “disconnect”，在重新建立与链的连接之前，API 将不接受任何新请求，这需要重新加载页面。您还可以使用ethereum.isConnected()方法来确定注入对象是否断开连接。

# accountsChanged 事件

ethereum.on('accountsChanged', handler: (accounts: Array<string>) => void);

每当 eth_accounts RPC 方法的返回值更改时，Coinhub App 都会发出此事件。 eth_accounts 返回一个为空或包含单个帐户地址的数组。返回的地址（如果有）是允许调用者访问的最近使用的帐户的地址。调用者通过其 URL origin 进行标识，这意味着所有具有相同来源的站点都共享相同的权限。

这意味着，每当用户的公开帐户地址发生更改时，就会发出 “accountsChanged” 事件。

提示

我们计划允许 eth_accounts 数组在不久的将来能够包含多个地址。

# chainChanged 事件

提示

有关 Coinhub App 的默认链及其链 ID，请参见链 ID。

ethereum.on('chainChanged', handler: (chainId: string) => void);

当前连接的链发生更改时，Coinhub App 将发出此事件。

所有 RPC 请求都将提交到当前连接的链。因此，通过监听此事件来跟踪当前链的 ID 是至关重要的。

ethereum.on('chainChanged', (_chainId) => window.location.reload());

# message 事件

interface ProviderMessage {
  type: string;
  data: unknown;
}
ethereum.on('message', handler: (message: ProviderMessage) => void);

当 Coinhub App 收到一些应通知消费者的消息时，它将发出此事件。消息的类型由 type 字符串标识。

RPC 订阅更新是 message 事件的常见用例。例如，如果您使用 eth_subscribe 创建订阅，则每个订阅更新将作为带有 eth_subscription 类型的 message 事件发出。

# 错误

Coinhub App 引发或返回的所有错误均遵循以下界面：

interface ProviderRpcError extends Error {
  message: string;
  code: number;
  data?: unknown;
}

ethereum.request(args)方法急切地抛出错误。您通常可以使用错误的 code 属性来确定请求失败的原因。常用代码及其含义包括：

有关错误的完整列表，请参阅 EIP-1193 (opens new window) 和 EIP-1474 (opens new window)。

← 简介 RPC API →