1. 主页
  2. 文档
  3. Web3.js 中文文档
  4. web3.eth.subscribe

web3.eth.subscribe

web3.eth.subscribe 方法让你可以订阅区块链中的指定事件

订阅调用

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

参数

  1. String – 订阅类型
  2. Mixed – (可选) 依赖于订阅类型的可选额外参数
  3. 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: 当订阅发生错误时,触发此事件
  • on("connected") 返回 String: 一旦订阅成功就会触发该事件,返回订阅 id

通知返回值

  • Mixed – 取决于订阅具体是什么,可以参考文档后面提到的不同订阅获取更多相关信息

例子

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

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

clearSubscriptions

web3.eth.clearSubscriptions()

重置订阅

注解

这不会重置像 web3-shh 这样其它包的订阅,因为这些包有自己的请求管理器

参数

1. Boolean: If true it keeps the "syncing" subscription. 1. Boolean: 值为 true 则表示保持 同步 订阅

返回值

Boolean

例子

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

...

web3.eth.clearSubscriptions();

subscribe(“pendingTransactions”)

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

订阅 pending 状态的交易。

参数

  1. String – "pendingTransactions", 订阅类型
  2. Function – (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。

返回值

EventEmitter: 下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 String: 当接收到 pending 状态的交易时触发并返回交易哈希
  • "error" 返回 Object: 当订阅中发生错误时触发

通知返回值

  1. Object|Null – 如果订阅失败第一个参数为错误对象
  2. String – 第二个参数为交易哈希

例子

var subscription = web3.eth.subscribe('pendingTransactions', function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(transaction){
    console.log(transaction);
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“newBlockHeaders”)

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

订阅新的区块头生成事件, 可用作检查链上变化的计时器。

参数

  1. String – "newBlockHeaders", 订阅类型。
  2. Function – (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 当收到新的区块头时触发
  • "error" 返回 Object: 当订阅中出现错误时触发
  • "connected" 返回 Number: 订阅成功后触发,返回订阅 id

返回的区块头对象结构如下:

  • number – Number: 区块编号,对于 pending 状态的块该值为“null“。
  • hash 32 Bytes – String: 块的哈希值,对于 pending 状态的块该值为“null“。
  • parentHash 32 Bytes – String: 父区块哈希值。
  • nonce 8 Bytes – String: 用来生成工作量证明的 nonce 值. 对于 pending 状态的块该值为“null“。
  • sha3Uncles 32 Bytes – String: 区块中叔块数据的 sha3哈希值。
  • logsBloom 256 Bytes – String: 区块日志数据的布隆过滤器。对于 pending 状态的块该值为“null“。
  • transactionsRoot 32 Bytes – String: 区块中交易 trie 树的根节点。
  • stateRoot 32 Bytes – String: 区块中状态 trie 树的根节点。
  • receiptsRoot 32 Bytes – String: 收据根节点。
  • miner – String: 接收挖矿奖励的矿工地址。
  • extraData – String: 区块的额外数据字段。
  • gasLimit – Number: 该块允许的最大 gas 用量。
  • gasUsed – Number: 该块中所有交易使用的 gas 总量。
  • timestamp – Number: 区块时间戳。

通知返回值

  1. Object|Null – 如果订阅失败第一个参数为错误对象
  2. Object – 像上面那样的区块头对象

例子

var subscription = web3.eth.subscribe('newBlockHeaders', function(error, result){
    if (!error) {
        console.log(result);

        return;
    }

    console.error(error);
})
.on("connected", function(subscriptionId){
    console.log(subscriptionId);
})
.on("data", function(blockHeader){
    console.log(blockHeader);
})
.on("error", console.error);

// 取消订阅
subscription.unsubscribe(function(error, success){
    if (success) {
        console.log('Successfully unsubscribed!');
    }
});

subscribe(“syncing”)

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

订阅同步事件。当节点正在同步数据时将返回一个同步对象,同步结束后返回 FALSE

参数

  1. String – "syncing", 订阅类型
  2. Function – (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 收到同步对象时触发
  • "changed" 返回 Object: 当同步状态由 true 变为 false 时触发
  • "error" 返回 Object: 当订阅中出现错误时触发

要了解返回事件对象的结构,可查看 web3.eth.isSyncing 返回值

通知返回值

  1. Object|Null – 如果订阅失败第一个参数为错误对象
  2. Object|Boolean – 同步对象, 同步开始后返回 true,同步结束后返回 false

例子

var subscription = web3.eth.subscribe('syncing', function(error, sync){
    if (!error)
        console.log(sync);
})
.on("data", function(sync){
    // 一些同步状态数据
})
.on("changed", function(isSyncing){
    if(isSyncing) {
        // 暂停应用操作
    } else {
        // 重启应用操作
    }
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“logs”)

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

订阅日志,并按指定条件进行过滤。 如果一个有效的 fromBlock 属性被指定,Web3 会提取从这个点开始的日志,必要时回填返回值。

参数

  1. "logs" – String, 订阅类型
  2. Object – 订阅选项
  • fromBlock – Number: 最早区块编号, 默认为 null
  • address – String|Array: 地址或地址列表,仅订阅来自这些指定账户地址的日志。
  • topics – Array: 一个主题数组,数组中每个元素都应出现在日志项中。 数组中主题的顺序是很重要的, 如果你不想监听某个主题可以用 null 值, 比如 [null, '0x00...']. 你也可以为每个主题传入另外一个数组来表示主题选项, 比如 [null, ['option1', 'option2']]
  1. callback – Function: (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 接收到新日志时触发,参数为日志对象
  • "changed" 返回 Object: 日志从链上移除时触发,该日志同时带有附加属性 "removed: true"
  • "error" 返回 Object: 当订阅中出现错误时触发
  • "connected" 返回 Number: 订阅成功后触发,返回订阅 id

要了解返回的事件对象结构,可查看 web3.eth.getPastEvents 返回值.

通知返回值

  1. Object|Null – 如果订阅失败第一个参数为错误对象
  2. Object – 日志对象,类似于 web3.eth.getPastEvents 返回值.

例子

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

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});
这篇文章对您有用吗?

我们要如何帮助您?