智能合约与以太坊 / 系统课时
监听事件并更新页面数据
监听事件并更新页面数据
合约交易成功后,DApp 需要及时展示新的业务状态。本课使用 ethers v6 查询 ERC-20 历史 Transfer 日志、订阅新事件,并将事件记录与账户余额同步到浏览器页面,同时处理重复通知、异步更新和监听清理。
学习目标
- 使用
queryFilter查询指定区块范围内的历史事件,并通过on接收新事件。 - 根据事件更新页面记录,重新读取链上余额,避免重复展示与异步覆盖。
- 正确移除监听器,理解断线补查和链重组对页面状态的影响。
区分历史日志、实时通知与链上状态
Solidity 合约可以通过 emit 写入事件日志。例如 ERC-20 的标准转账事件:
event Transfer(address indexed from, address indexed to, uint256 value);这是事件声明片段,依赖实现 ERC-20 的 Solidity 合约。from 和 to 是可按主题过滤的索引参数,value 表示以代币最小单位计量的数量。
ethers v6 提供两种主要访问方式:
contract.queryFilter(filter, fromBlock, toBlock):查询已有区块内的匹配日志,适合初始化历史记录、分页和断线补查。contract.on(filter, listener):注册持续监听器,在 Provider 检测到匹配日志时执行回调,适合实时刷新页面。
事件日志说明发生过什么,但并不直接代表账户的当前余额。页面应通过 balanceOf(account) 读取余额,而不是只根据已收到的 Transfer 数量进行加减。
例如用户原有 10 个代币,发生一次转入 3 个、一次转出 2 个,正确余额为 11。如果监听器只观察转入事件并自行累加,就会错误显示 13。

使用 ethers v6 查询和订阅事件
下面制作一个可运行的浏览器示例,观察 Sepolia 测试网上指定 ERC-20 合约与某个账户相关的转账,并同步展示当前余额。
准备 Node.js 20.19+ 或 22.12+、npm、可从浏览器访问且允许跨域请求的 Sepolia HTTPS RPC,以及真实部署的 ERC-20 合约地址。这里使用 Vite 创建原生 JavaScript 项目。
npm create vite@latest event-ui -- --template vanilla
cd event-ui
npm install
npm install ethers@6
npm run dev预期输出包含本地开发服务器访问地址,具体端口可能不同:
Local: http://localhost:<PORT>/<PORT> 表示实际端口。打开该地址后,将项目根目录的 main.js 替换为以下完整代码。示例使用标准 ERC-20 ABI,分别过滤转入和转出事件,不要求账户拥有发送交易的私钥。
import {
Contract,
JsonRpcProvider,
formatUnits,
isAddress
} from 'ethers';
const abi = [
'event Transfer(address indexed from, address indexed to, uint256 value)',
'function balanceOf(address) view returns (uint256)',
'function decimals() view returns (uint8)'
];
document.querySelector('#app').innerHTML = `
<h1>ERC-20 账户事件</h1>
<form id="config">
<input name="rpc" placeholder="Sepolia HTTPS RPC" required>
<input name="token" placeholder="代币合约地址" required>
<input name="account" placeholder="观察账户地址" required>
<button type="submit">开始监听</button>
</form>
<button id="stop" type="button">停止监听</button>
<p id="status">未连接</p>
<p id="balance">余额:--</p>
<ol id="events"></ol>
`;
const status = document.querySelector('#status');
const balance = document.querySelector('#balance');
const list = document.querySelector('#events');
let active = null;
async function stop() {
const old = active;
active = null;
if (!old) return;
// 只移除本页面注册的回调,不影响其他模块。
await Promise.all(
old.filters.map((filter) => old.contract.off(filter, old.listener))
);
old.provider.destroy();
}
async function start(rpc, token, account) {
await stop();
if (!isAddress(token) || !isAddress(account)) {
throw new Error('合约地址或账户地址无效');
}
const provider = new JsonRpcProvider(rpc);
try {
const network = await provider.getNetwork();
if (network.chainId !== 11155111n) {
throw new Error('RPC 必须连接 Sepolia');
}
const contract = new Contract(token, abi, provider);
const decimals = Number(await contract.decimals());
const filters = [
contract.filters.Transfer(null, account),
contract.filters.Transfer(account, null)
];
const records = new Map();
const session = { provider, contract, filters, listener: null, serial: 0 };
active = session;
function render() {
const sorted = [...records.values()]
.sort((a, b) => b.block - a.block || b.index - a.index)
.slice(0, 10);
list.replaceChildren(...sorted.map((item) => {
const li = document.createElement('li');
li.textContent = item.text;
return li;
}));
}
function ingest(log) {
if (!log.args || !log.blockHash) return;
// 相同日志可能同时命中两个过滤器或被历史查询再次返回。
const key = `${log.blockHash}:${log.index}`;
if (records.has(key)) return;
const [from, to, value] = log.args;
records.set(key, {
block: log.blockNumber,
index: log.index,
text: `区块 ${log.blockNumber}:${from.slice(0, 8)} → ${to.slice(0, 8)},${formatUnits(value, decimals)}`
});
render();
}
async function refreshBalance() {
const serial = ++session.serial;
const raw = await contract.balanceOf(account);
// 忽略已经失效的请求和较早返回的查询结果。
if (active === session && serial === session.serial) {
balance.textContent = `余额:${formatUnits(raw, decimals)}`;
}
}
function showError(error) {
if (active === session) {
status.textContent = `读取失败:${error.shortMessage ?? error.message}`;
}
}
session.listener = (_from, _to, _value, payload) => {
if (active !== session) return;
ingest(payload.log);
void refreshBalance().catch(showError);
};
// 先订阅,再补查历史范围,降低初始化期间漏事件的风险。
await Promise.all(filters.map((filter) => contract.on(filter, session.listener)));
const tip = await provider.getBlockNumber();
const fromBlock = Math.max(0, tip - 99);
const batches = await Promise.all(
filters.map((filter) => contract.queryFilter(filter, fromBlock, tip))
);
if (active !== session) return;
for (const batch of batches) {
for (const log of batch) ingest(log);
}
await refreshBalance();
if (active === session) status.textContent = '正在监听 Sepolia';
} catch (error) {
if (active?.provider === provider) await stop();
else provider.destroy();
throw error;
}
}
document.querySelector('#config').addEventListener('submit', async (event) => {
event.preventDefault();
const form = new FormData(event.currentTarget);
status.textContent = '连接中';
balance.textContent = '余额:--';
list.replaceChildren();
try {
await start(
String(form.get('rpc')).trim(),
String(form.get('token')).trim(),
String(form.get('account')).trim()
);
} catch (error) {
status.textContent = `连接失败:${error.shortMessage ?? error.message}`;
}
});
document.querySelector('#stop').addEventListener('click', async () => {
await stop();
status.textContent = '已停止监听';
});
window.addEventListener('pagehide', () => {
void stop();
});预期结果:在页面依次填入 Sepolia RPC、真实 ERC-20 合约地址和观察账户地址,点击“开始监听”,页面显示“正在监听 Sepolia”、从链上读取的余额,以及最近 100 个区块范围内最多 10 条相关转账记录。实际余额、区块高度和事件数量由链上数据决定,可能没有历史事件。
向观察账户转入代币,或者由观察账户转出代币,在交易被区块收录且 Provider 检测到事件后,最近事件列表会出现对应记录,并触发一次 balanceOf 读取。单纯启动监听不会产生新的链上交易。
处理重复通知与页面更新顺序
示例中的账户转入和转出过滤器可能同时匹配同一条事件。例如从账户 A 向账户 A 转账 5 个代币,两条过滤器都会命中,但页面应只显示一条事件,而且账户净余额不变。
ethers v6 的事件日志提供 blockNumber、blockHash、transactionHash 和 index 等信息。index 是日志在区块内的索引。同一笔交易可能产生多条 Transfer,因此不能只使用交易哈希去重。
| 情况 | 处理方式 |
|---|---|
| 历史查询与实时监听返回同一日志 | 使用 blockHash + index 判断重复 |
| 同一交易包含多条 Transfer | 保留不同日志索引对应的记录 |
| 新事件先到,旧查询后完成 | 使用区块高度和日志索引排序展示 |
| 多次余额查询返回顺序颠倒 | 使用请求序号丢弃旧请求结果 |
| 页面重新进入或切换合约 | 清理旧监听器,并重建新会话 |
例如余额查询 A 开始时链上为 10,查询 B 开始后链上变成 15。假如 B 先返回 15、A 后返回 10,直接写入 DOM 会让页面倒退。示例使用递增的 serial,只接受当前会话最近一次发起的查询结果。
这里仍有一个边界:请求序号仅保证较旧的请求不会覆盖较新的请求,并不保证两个 RPC 响应使用同一链上区块。要求严格一致的业务页面,可以固定 blockTag 查询快照,并根据区块高度决定是否接受更新。
清理监听器与补查遗漏区块
contract.on 注册的是持续监听器。若页面组件每次挂载都调用 on,卸载时却没有取消,重新进入页面后可能出现同一事件重复处理、后台持续请求以及内存占用增加的问题。
ethers v6 中,on 和 off 返回 Promise,示例通过 await contract.off(filter, listener) 清理指定监听函数。不要在多个页面共用同一个 Contract 时随意调用 removeAllListeners(),否则会把其他模块注册的回调一并移除。
如果使用 React,可以将订阅放在 useEffect 中,并在清理函数中调用 off;如果使用 Vue,可以在 onMounted 中注册,在 onUnmounted 中注销。合约地址、链 ID 或观察账户发生变化时,也必须注销旧监听并重新建立过滤器。
不过,注销和重新注册监听器只能管理生命周期,不能解决网络中断期间遗漏事件的问题。生产环境需要保存同步进度并补查日志:
- 保存最后处理的区块高度,例如
lastProcessedBlock = 1050。 - 连接恢复后先读取当前最新区块,例如
latestBlock = 1080。 - 从
max(0, lastProcessedBlock - 12)开始分批执行queryFilter,一直查询到最新区块,与实时订阅结果合并去重。 - 如果检测到区块哈希变化或链重组,撤销受影响的旧事件记录,重新扫描受影响区间,并读取当前合约状态。
- 只有在日志和业务状态成功处理后,才推进持久化的同步进度。
其中回退 12 个区块是演示用策略参数,并非以太坊通用的最终确认保证。对于不能容忍回滚的业务,应根据网络最终性和产品要求选择确认策略,必要时等区块达到 finalized 状态后再视为最终记录。
部分 RPC 服务对历史日志的查询跨度或返回数量有限制。正式环境可按 500~2000 个区块一批作为初始配置,根据服务商限制缩小范围,并避免一次查询从创世区块到最新区块。WebSocket 或 HTTP 事件订阅也不应被视为可靠的永久消息队列。
验证事件更新和异常恢复
使用测试网账户和测试代币,按以下顺序完成验收:
- 输入有效的 Sepolia RPC 和 ERC-20 地址,确认余额显示与合约
balanceOf的链上读取结果一致。 - 向观察账户转入一笔代币,确认产生一条入账日志,显示的数量已经按
decimals换算。 - 从观察账户转出一笔代币,确认转出日志出现,余额随链上状态刷新。
- 从观察账户向自身转账,确认即使两条过滤器都匹配,也不会在页面重复显示同一日志。
- 点击“停止监听”,再进行一笔转账,确认页面不再接收来自旧监听器的更新。
- 故意使用错误链的 RPC,确认显示“RPC 必须连接 Sepolia”而不是错误地展示其他网络的数据。
还需要测试一次页面刷新或网络临时中断。刷新后,本示例会重新查询最近 100 个区块,因此能够恢复这个窗口内的事件;但超过该窗口的遗漏不会自动补齐。若项目要求完整事件历史,应实现前述持久化游标与分批补查机制。
当页面能够从历史日志恢复记录、实时展示新事件、使用链上读取值刷新余额,并在离开页面后停止旧监听时,基础事件同步功能就具备了可验证的闭环。对于资金结算、订单完成等需要强一致性的业务,还必须补充持久化进度、重组恢复和最终确认处理。