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。

参数¶

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 作为额外的格式化函数进行输入输出参数的格式化. 更多详情请看源文件。

参数¶

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 {...},
    ...
}