链眼社区:专注于区块链安全,区块链数据分析, 区块链信息整合,区块链技术服务和区块链技术咨询。

web3.js 1.0中文手册:web3.eth.subscribe
清风慕竹
2021-10-12 22:01:58

web3.eth.subscribe

使用web3.eth.subscribe()方法来订阅区块链上的指定事件。

调用:

web3.eth.subscribe(type [, options] [, callback]);

参数:

  • type:String - 订阅类型
  • options:Mixed - 可选的额外参数,依赖于订阅类型
  • callback:Function - 可选的回调函数,其第一个参数为错误对象,第二个参数为结果 返回值:

EventEmitter - 订阅实例对象,具有以下字段:

  • subscription.id: 订阅id编号,用于标识一个订阅以及进行后续的取消订阅操作
  • subscription.subscribe([callback]): 可用于使用相同的参数进行再次订阅
  • subscription.unsubscribe([callback]): 取消订阅,如果成功取消的话,在回调函数中返回true
  • subscription.arguments: 订阅参数,当重新订阅时使用
  • on("data") 返回 Object: 每次有新的日志时都触发该事件,参数为日志对象
  • on("changed") 返回 Object: 每次有日志从区块链上移除时触发该事件,被移除的日志对象将添加额外的属性:"removed: true"
  • on("error") 返回 Object: 当订阅中发生错误时,触发此事件 通知返回值:

Mixed - 取决于具体的订阅类型

示例代码:

var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(log);
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.eth.clearSubscriptions

web3.eth.clearSubscriptions()方法用来复位订阅状态。注意该方法不能 复位其他包的订阅,例如web3-shh,因为这些包有自己的请求管理器。

调用:

web3.eth.clearSubscriptions(flag)

参数:

  • flag:Boolean - 值为true则表示保持同步订阅 返回值:

Boolean:复位成功返回true,否则返回false

示例代码:

web3.eth.subscribe('logs', {} ,function(){ ... });

...

web3.eth.clearSubscriptions();

web3.eth.subscribe("pendingTransactions")

参数pendingTransactions表示订阅处于pending状态的交易。

调用:

web3.eth.subscribe('pendingTransactions' [, callback]);

参数:

  • type:String - "pendingTransactions",订阅类型
  • callback:Function - 可选的回调函数,其第一个参数为错误对象,第二个参数为结果 返回值:

EventEmitter: 订阅实例对象,是一个事件发生器,定义有以下事件:

  • "data" 返回 Object: 当接收到pending状态的交易时触发
  • "error" 返回 Object: 当订阅中发生错误时触发 返回对象的结构,参见web3.eth.getTransaction()的返回值。

通知返回值:

  • Object|Null - 第一个参数是一个错误对象,如果订阅成功则为null
  • Object - 块头对象 示例代码:
var subscription = web3.eth.subscribe('pendingTransactions', function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(transaction){
    console.log(transaction);
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.eth.subscribe('newBlockHeaders')

使用newBlockHeaders参数订阅新的区块头生成事件。可用做检查区块链上变化的计时器。

调用:

web3.eth.subscribe('newBlockHeaders' [, callback]);

参数:

  • type:String - "newBlockHeaders", 订阅类型
  • callback:Function - 可选的回调函数,其第一个参数为错误对象,第二个参数为结果 返回值:

EventEmitter: 订阅对象实例,是一个事件发生器,定义有如下事件:

  • "data" 返回 Object: 当收到新的区块头时触发
  • "error" 返回 Object: 当订阅中出现错误时触发 返回的区块头对象结构如下:

  • number - Number: 区块编号,对于pending的块该值为null

  • hash 32 Bytes - String: 块的哈希值,挂起的块该值为null
  • parentHash 32 Bytes - String: 父区块的哈希值
  • nonce 8 Bytes - String: 生成的proof-of-work的哈希值。挂起块该值为null、
  • sha3Uncles 32 Bytes - String: 块中叔伯数据的SHA3值
  • logsBloom 256 Bytes - String: 块日志的bloom filter,块处于挂起状态时该值为null
  • transactionsRoot 32 Bytes - String: 块交易树的根节点
  • stateRoot 32 Bytes - String: 块状态树的根节点
  • receiptRoot 32 Bytes - String: 收据根节点
  • miner - String: 接收挖矿奖励的矿工地址
  • extraData - String: 区块的额外数据字段
  • gasLimit - Number: 该块允许的最大gas用量
  • gasUsed - Number: 该块中所有交易使用的gas总用量
  • timestamp - Number: 出块的unix时间戳 通知返回值:

  • Object|Null - 如果订阅失败,则该参数为错误对象,否则为null

  • Object - 区块头对象 示例代码:
var subscription = web3.eth.subscribe('newBlockHeaders', function(error, result){
    if (error)
        console.log(error);
})
.on("data", function(blockHeader){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.eth.subscribe('syncing')

使用syncing参数订阅同步事件。当节点同步时将返回一个同步对象,否则返回false。

调用:

web3.eth.subscribe('syncing' [, callback]);

参数:

  • type:String - "syncing", 订阅类型
  • callback:Function - 可选的回调函数,其第一个参数为错误对象,第二个参数为结果 返回值:

EventEmitter: 订阅对象实例,是一个事件发生器,定义有如下事件:

  • "data" 返回 Object: 收到同步对象时触发
  • "changed" 返回 Object: 当节点从同步状态转换为非同步状态时触发
  • "error" 返回 Object: 当订阅中出现错误时触发 要了解返回的事件对象的结构,可以查看web3.eth.isSyncing()方法的返回值。

通知返回值:

  • Object|Null - 当订阅失败时,该值为错误对象,否则为null
  • Object|Boolean - 同步对象 示例代码:
var subscription = web3.eth.subscribe('syncing', function(error, sync){
    if (!error)
        console.log(sync);
})
.on("data", function(sync){
    // show some syncing stats
})
.on("changed", function(isSyncing){
    if(isSyncing) {
        // stop app operation
    } else {
        // regain app operation
    }
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.eth.subscribe('logs')

使用logs参数订阅日志,并且可以指定条件进行过滤。

调用:

web3.eth.subscribe('logs', options [, callback]);

参数:

  • "logs" :String, 订阅类型
  • options:Object - 订阅选项,该对象包含如下字段:
  • fromBlock - Number: 最早块的编号,默认值为null
  • address - String|Array: 地址或地址列表,仅订阅来自这些账户地址的日志
  • topics - Array: 主题数组,仅订阅日志中包含这些主题的日志。
  • callback - Function: 可选的回调函数,其第一个参数为错误对象,第二个参数为结果 返回值:

EventEmitter: 订阅实例对象,是一个事件发生器,定义有如下事件:

  • "data" 返回 Object: 接收到新日志时触发,参数为日志对象
  • "changed" 返回 Object: 日志从链上移除时触发,该日志同时添加属性 "removed: true"
  • "error" 返回 Object: 当订阅中出现错误时触发 要了解返回的事件对象的结果,可查阅web3.eth.getPastEvents()方法的返回值。

通知返回值:

  • Object|Null - 订阅失败时该值为错误对象,否则为null
  • Object - 日志对象,类似于web3.eth.getPastEvents()方法的返回值 示例代码:
var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(log){
    console.log(log);
})
.on("changed", function(log){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

合作伙伴