Web3

Web3 是 web3.js 库的主类。

var Web3 = require('web3');

> Web3.utils
> Web3.version
> Web3.givenProvider
> Web3.providers
> Web3.modules

Web3.modules

Web3.modules

将返回所有主要子模块类的对象,以便能够手动实例化它们。

返回值

Object: 模块构造函数列表:
  • Eth - Constructor: 与以太坊网络交互的 Eth 模块,查看 web3.eth 了解更多。

  • Net - Constructor: 与网络属性进行交互的 Net 模块,查看 web3.eth.net 了解更多。

  • Personal - Constructor: 与以太坊账户交互的 Personal 模块,查看 web3.eth.personal 了解更多。

  • Shh - Constructor: 与whisper协议交互的 Shh 模块,查看 web3.shh 了解更多。

  • Bzz - Constructor: 与swarm网络交互的 Bzz 模块,查看 web3.bzz 了解更多。

例子

Web3.modules
> {
    Eth: Eth(provider),
    Net: Net(provider),
    Personal: Personal(provider),
    Shh: Shh(provider),
    Bzz: Bzz(provider),
}

Web3 实例

Web3类是一个“伞”包,在Web3类下包含所有与以太坊相关的模块。

var Web3 = require('web3');

// 创建实例,如果在支持以太坊的浏览器 "Web3.providers.givenProvider" 会被设置。
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

> web3.eth
> web3.shh
> web3.bzz
> web3.utils
> web3.version

version

version 即是Web3类的静态可访问属性也Web3实例的属性。

Web3.version
web3.version

返回当前 web3.js 库的软件包版本。

返回值

String: 当前版本。

例子

web3.version;
> "1.2.3"

utils

utils 即是Web3类的静态可访问属性也Web3实例的属性。

Web3.utils
web3.utils

web3.utils的工具方法也直接在Web3类对象上公开(译者注:即可以直接通过 Web3 来访问工具方法)。

查看 web3.utils 了解更多。


setProvider

web3.setProvider(myProvider)
web3.eth.setProvider(myProvider)
web3.shh.setProvider(myProvider)
web3.bzz.setProvider(myProvider)
...

将改变相应模块的 provider。

注解

当我们通过 web3 包调用它的时候,web3.eth, web3.shh 等子模块的 provider 也会被设置,web3.bzz 这货是个例外,它总是需要一个单独的 provider。

参数

  1. Object - myProvider: 一个有效的 provider.

返回值

Boolean

例子

var Web3 = require('web3');
var web3 = new Web3('http://localhost:8545');
// 或
var web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));

// 改变 provider
web3.setProvider('ws://localhost:8546');
// 或
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

// 在 node.js 中使用 IPC provider
var net = require('net');
var web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os 路径
// 或
var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os 路径
// 在 windows 中路径为: "\\\\.\\pipe\\geth.ipc"
// 在 linux 中路径为: "/users/myuser/.ethereum/geth.ipc"

providers

web3.providers
web3.eth.providers
web3.shh.providers
web3.bzz.providers
...

包含当前可用的 providers.

返回值

具有以下 provider 的 Object:

  • Object - HttpProvider: The HTTP provider is deprecated, as it won’t work for subscriptions.

  • Object - WebsocketProvider: The Websocket provider is the standard for usage in legacy browsers.

  • Object - IpcProvider: The IPC provider is used node.js dapps when running a local node. Gives the most secure connection.

  • Object - HttpProvider: 因为不能用于订阅,HTTP provider 已经**不推荐使用**。

  • Object - WebsocketProvider: Websocket provider 是用于传统的浏览器中的标准方法.

  • Object - IpcProvider: 当运行一个本地节点时,IPC provider 用于 node.js 下的D App 环境,提供最为安全的连接。.

例子

var Web3 = require('web3');
// 使用指定的 Provider (e.g 比如在 Mist 中) 或者实例化一个新的 websocket provider
var web3 = new Web3(Web3.givenProvider || 'ws://remotenode.com:8546');
// 或者
var web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://remotenode.com:8546'));

// 在 node.js 中使用 IPC provider
var net = require('net');

var web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os 路径
// 或者
var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os 路径
// windows 上的路径为: "\\\\.\\pipe\\geth.ipc"
// linux 上的路径为: "/users/myuser/.ethereum/geth.ipc"

givenProvider

web3.givenProvider
web3.eth.givenProvider
web3.shh.givenProvider
web3.bzz.givenProvider
...

在和以太坊兼容的浏览器中使用 web3.js 时,当前环境的原生 provider 会被浏览器设置。 web3.givenProvider 将返回浏览器设置的原生 provider ,否则返回 null

返回值

Object: 浏览器设置好的 provider 或者 null;

例子


currentProvider

web3.currentProvider
web3.eth.currentProvider
web3.shh.currentProvider
web3.bzz.currentProvider
...

返回值

Object: 当前在用的 provider 或者 null;

例子


BatchRequest

new web3.BatchRequest()
new web3.eth.BatchRequest()
new web3.shh.BatchRequest()
new web3.bzz.BatchRequest()

用来创建并执行批量请求的类

参数

none

返回值

Object: 具有如下方法的一个对象:

  • add(request): To add a request object to the batch call.

  • execute(): Will execute the batch request.

  • add(request): 添加请求对象到批量调用中。

  • execute(): 执行批量请求。

例子

var contract = new web3.eth.Contract(abi, address);

var batch = new web3.BatchRequest();
batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}, callback2));
batch.execute();

extend

web3.extend(methods)
web3.eth.extend(methods)
web3.shh.extend(methods)
web3.bzz.extend(methods)
...

用来扩展 web3 模块

注解

你也可以使用 *.extend.formatters 作为额外的格式化函数进行输入输出参数的格式化. 更多详情请看 源文件

参数

  1. methods - Object: 扩展对象,带有一组如下所示的方法描述对象:
    • property - String: (可选) 要添加到模块上的属性名称。如果没有设置属性,则直接添加到模块上。

    • methods - Array: 方法描述对象数组:
      • name - String: 要添加的方法名称。

      • call - String: RPC 方法名称。

      • params - Number: (可选) 方法的参数个数,默认值为 0。

      • inputFormatter - Array: (可选) 输入格式化函数数组,每个成员对应一个函数参数,或者使用 null 来对应不需要进行格式化处理的参数。

      • outputFormatter - ``Function: (可选) 用来格式化方法输出。

返回值

Object: 扩展模块.

例子

web3.extend({
    property: 'myModule',
    methods: [{
        name: 'getBalance',
        call: 'eth_getBalance',
        params: 2,
        inputFormatter: [web3.extend.formatters.inputAddressFormatter, web3.extend.formatters.inputDefaultBlockNumberFormatter],
        outputFormatter: web3.utils.hexToNumberString
    },{
        name: 'getGasPriceSuperFunction',
        call: 'eth_gasPriceSuper',
        params: 2,
        inputFormatter: [null, web3.utils.numberToHex]
    }]
});

web3.extend({
    methods: [{
        name: 'directCall',
        call: 'eth_callForFun',
    }]
});

console.log(web3);
> Web3 {
    myModule: {
        getBalance: function(){},
        getGasPriceSuperFunction: function(){}
    },
    directCall: function(){},
    eth: Eth {...},
    bzz: Bzz {...},
    ...
}