企业官网建设流程全解析

wagmi Tempodex.useWatchOrderCancelled：React 中监听稳定币 DEX 订单取消事件的完整指南

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

本文围绕 wagmi 为 Tempo 网络提供的Hooks.dex.useWatchOrderCancelled进行深入讲解：它用于在 React 应用中订阅 Tempo 稳定币 DEX（Stablecoin DEX）的订单取消（order cancelled）事件，是构建订单簿交易 UI 时"实时感知订单被撤销"的核心工具。读完本文，你将掌握该 Hook 的完整参数语义、与底层dex.watchOrderCancelledAction 的调用链路、事件过滤技巧（如按orderId精确订阅），以及如何与dex.cancel搭配实现"取消即刷新"的实战模式。

背景：Tempo 与稳定币 DEX

Tempo 是一条专注于支付场景的 Layer 1 区块链，其协议内置了代币管理（TIP-20）、Fee AMM 以及稳定币 DEX（订单簿式交易所）等能力（详见 Tempo 入门指南）。在 wagmi 中，Tempo 网络获得了一等公民支持：wagmi/tempo模块同时导出了声明式 Hooks（Hooks.*）与命令式 Actions（Actions.*），分别面向 React 组件与纯逻辑调用场景。

Hooks.dex.useWatchOrderCancelled正是这一体系下负责"监听订单取消事件"的 Hook，与其配套的还有useWatchOrderPlaced（下单事件）、useWatchOrderFilled（成交事件）、useWatchFlipOrderPlaced（Flip 单下单事件）等监听型 Hook（完整清单见 Tempo Hooks 总览）。

快速上手：最小可用示例

在 React 组件中使用useWatchOrderCancelled，只需传入onOrderCancelled回调：

import { Hooks } from 'wagmi/tempo' function OrderFeed() { Hooks.dex.useWatchOrderCancelled({ onOrderCancelled: (args, log) => { console.log('args:', args) }, }) return <div>正在监听订单取消事件...</div> }

其中onOrderCancelled回调签名如下（定义于 action 文档）：

declare function onOrderCancelled(args: Args, log: Log): void type Args = { /** 被取消订单的 ID */ orderId: bigint }

• args：事件解码后的参数对象，目前包含被取消订单的 ID（orderId: bigint）；
• log：对应事件的原始日志（Log）对象，可用于进一步校验或上报。

该 Hook 的使用前提是项目中已配置好 Tempo 链与tempoWallet连接器，参考 配置示例：

import { createConfig, http } from 'wagmi' import { tempo } from 'wagmi/chains' import { tempoWallet } from 'wagmi/tempo' export const config = createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })

参数详解

useWatchOrderCancelled的参数类型由两部分叠加而成：底层 Actiondex.watchOrderCancelled的参数（完整定义）加 Hook 层特有的config与enabled参数。从源码声明可以看出其精确形态（packages/react/src/tempo/hooks/dex.ts#L1598-L1603）：

type Parameters<config extends Config = Config> = UnionCompute< ExactPartial<Actions.dex.watchOrderCancelled.Parameters<config>> & ConfigParameter<config> & { enabled?: boolean | undefined } >

下面按类别逐一说明。

onOrderCancelled（必需）

• 类型：function
• 签名：(args: Args, log: Log) => void

每当链上发生一笔订单取消时被调用。若未提供该回调，Hook 内部会直接跳过订阅逻辑（见下文实现剖析）。

orderId（可选，事件过滤）

• 类型：bigint | bigint[] | null

按订单 ID 过滤事件，可传单个 ID、ID 数组或null。这是最常用的过滤手段——例如在"我的订单"页面只想感知自己订单的取消，避免被全市场事件淹没。

fromBlock（可选）

• 类型：bigint

从指定区块开始监听。不传时从当前最新区块开始，适合只关心"之后发生"的取消事件。

onError（可选）

• 类型：(error: Error) => void

在拉取新区块（轮询场景）或订阅过程中发生错误时回调，用于捕获异常而不是让错误静默丢失。

poll 与 pollingInterval（可选）

• poll：true—— 强制启用轮询模式（而非链上事件订阅）；
• pollingInterval：number—— 轮询频率（毫秒），默认继承 Client 的pollingInterval配置。

对于不支持原生事件订阅的环境，或在测试环境中，轮询模式是稳定的兜底方案。

config（可选）

• 类型：Config | undefined

指定要使用的 Config，默认从最近的WagmiProvider上下文获取。适用于需要同时操作多个 Config 实例的场景。

enabled（Hook 层扩展）

• 类型：boolean，默认true

源码中通过解构const { enabled = true, onOrderCancelled, ...rest } = parameters提取该开关（packages/react/src/tempo/hooks/dex.ts#L1570）。当enabled为false时 Hook 不建立订阅，可用于"登录后才开始监听""页面不可见时暂停监听"等动态控制。

chainId（Hook 层扩展）

• 类型：ChainIdParameter<config>

Hook 内部默认使用当前激活链的 ID（useChainId），也允许手动指定目标链。

底层实现剖析：从 Hook 到 Action 再到链上事件

useWatchOrderCancelled并非独立实现的监听逻辑，而是对 Core 层 Actiondex.watchOrderCancelled的 React 封装。其完整实现如下（packages/react/src/tempo/hooks/dex.ts#L1567-L1596）：

export function useWatchOrderCancelled< config extends Config = ResolvedRegister['config'], >(parameters: useWatchOrderCancelled.Parameters<config> = {}) { const { enabled = true, onOrderCancelled, ...rest } = parameters const config = useConfig({ config: parameters.config }) const configChainId = useChainId({ config }) const chainId = parameters.chainId ?? configChainId useEffect(() => { if (!enabled) return if (!onOrderCancelled) return return Actions.dex.watchOrderCancelled(config, { ...rest, chainId, onOrderCancelled, }) }, [ config, enabled, chainId, onOrderCancelled, rest.fromBlock, rest.onError, rest.orderId, rest.poll, rest.pollingInterval, ]) }

几个值得注意的实现细节：

1. useEffect 生命周期即订阅生命周期：Hook 在副作用中调用 Action 建立订阅，并把 Action 返回的unwatch函数作为 effect 的清理函数。这意味着组件卸载、或依赖项（chainId、orderId等）变化时，旧的订阅会被自动释放，再按新参数重建——不需要手动管理取消订阅。
2. 依赖项白名单：effect 依赖数组显式列出了fromBlock、onError、orderId、poll、pollingInterval等参数，只有这些参数变化才会重建订阅，其余参数通过...rest透传。
3. 回调不触发重建：onOrderCancelled虽在依赖数组中，但 React 中通过useCallback稳定引用可避免不必要的重订阅。

而 Core 层的 Action 则负责把 Config 解析为 Client 并透传给 viem 的 Tempo 实现（packages/core/src/tempo/actions/dex.ts#L1501-L1517）：

export function watchOrderCancelled<config extends Config>( config: config, parameters: watchOrderCancelled.Parameters<config>, ) { const { chainId, ...rest } = parameters const client = config.getClient({ chainId }) return Actions.dex.watchOrderCancelled(client, rest) }

由此形成清晰的调用链：useWatchOrderCancelled→Actions.dex.watchOrderCancelled(config, …)→config.getClient({ chainId })→ viem 的dex.watchOrderCancelled。Action 的返回类型为() => void，即"调用即可取消订阅"的函数（action 文档）。

实战模式：订单取消后自动刷新订单列表

监听事件的意义在于驱动 UI 更新。与写操作dex.cancel（文档）配合，可以构建"取消订单 → 实时刷新列表"的闭环：

import { Hooks } from 'wagmi/tempo' import { useQueryClient } from '@tanstack/react-query' function OrderBook() { const queryClient = useQueryClient() Hooks.dex.useWatchOrderCancelled({ // 只关心自己订单的取消 orderId: myOrders.map((o) => o.orderId), onOrderCancelled({ orderId }) { console.log('订单已取消:', orderId) // 失效订单列表查询，触发重新拉取 queryClient.invalidateQueries({ queryKey: ['my-orders'] }) }, }) return <OrdersTable /> }

若是在非 React 环境（服务端、脚本、事件网关）中消费同样的事件，则应直接使用命令式 Action：

import { Actions } from 'wagmi/tempo' import { config } from './config' const unwatch = Actions.dex.watchOrderCancelled(config, { onOrderCancelled(args, log) { console.log('Order cancelled:', args.orderId) }, }) // 业务完成后再取消订阅 unwatch()

行为验证：测试用例如何证明过滤语义

仓库中针对该 Hook 与 Action 分别编写了行为测试，可以直接作为"事件过滤是否正确"的权威依据：

• Action 层测试（packages/core/src/tempo/actions/dex.test.ts#L1242-L1321）覆盖了两个场景：default场景先placeSync下一笔买单再cancelSync取消，断言回调恰好收到 1 次取消且args.orderId与下单返回的 ID 一致；filter by orderId场景则同时下两笔单，仅监听其中一笔的取消，随后依次取消两笔订单，最终断言只收到 1 个事件且对应被监听的那笔。
• Hook 层测试（packages/react/src/tempo/hooks/dex.test.ts#L791-L867）通过renderHook挂载useWatchOrderCancelled，用cancelSync触发事件后用vi.waitUntil等待异步回调，验证了同样的默认监听与按orderId过滤两种行为。

这两个测试文件相互印证：无论通过 Hook 还是 Action 使用，orderId过滤都会严格生效，且回调接收到的orderId与dex.cancel/dex.cancelSync返回的订单 ID 一一对应。

小结

Hooks.dex.useWatchOrderCancelled将 viem Tempo 的订单取消事件订阅能力以声明式、生命周期自管理的形态带入 React：

• 订阅即副作用：通过useEffect建立/销毁订阅，组件卸载自动清理；
• 参数灵活：orderId支持单值/数组过滤，fromBlock控制起始区块，poll/pollingInterval提供轮询兜底，enabled实现动态启停；
• 可组合性强：与dex.cancel（文档）、useWatchOrderPlaced、useWatchOrderFilled等组合，即可搭建出完整的实时订单簿体验。

若要进一步深入底层 viem 实现或查看相邻事件 Hook（如下单、成交），可继续阅读 dex.watchOrderCancelled Action 文档、dex.cancel 文档 与 Tempo Hooks 总览。

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi