使用 wagmi/core 的 getEnsText Action 读取 ENS 文本记录【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmigetEnsText 是wagmi/core提供的核心 Action用于按 ENS 名称与文本键Text Key读取链上的文本记录Text Record例如通过com.twitter键获取wevm.eth对应的 Twitter 用户名。本文以 site/core/api/actions/getEnsText.md 为主线结合仓库中的源码实现、Query 封装与测试用例完整讲解该 Action 的导入方式、全部参数、返回值类型、错误处理以及底层执行原理读完即可在真实项目中落地使用。功能概述ENS 文本记录是 ENS 协议中一类可自由定义的键值数据常被用来存放社交账号com.twitter、com.github、邮箱email、头像链接avatar等元信息。getEnsText接受一个 ENS 名称如wevm.eth与一个文本键如com.twitter通过 ENS Universal Resolver 合约解析出对应的文本值。在仓库中的实现层面该 Action 由三部分构成核心 Actionpackages/core/src/actions/getEnsText.ts直接封装 Viem 的getEnsText响应式 Query 封装packages/core/src/query/getEnsText.ts提供getEnsTextQueryOptions与getEnsTextQueryKey用于 TanStack Query 集成测试用例packages/core/src/actions/getEnsText.test.ts 与 packages/core/src/query/getEnsText.test.ts。导入 Action在项目中使用核心包时直接从wagmi/core顶层导入即可import { getEnsText } from wagmi/coregetEnsText及相关类型会经由 packages/core/src/exports/actions.ts 统一导出Query 版本getEnsTextQueryOptions等则由 packages/core/src/exports/query.ts 导出。基础用法import { getEnsText } from wagmi/core import { normalize } from viem/ens import { config } from ./config const ensText getEnsText(config, { name: normalize(wevm.eth), key: com.twitter, })第一个参数configgetEnsText的第一个参数是wagmi/core创建的 Config 实例通过createConfig构建。仓库中使用的示例配置见 site/snippets/core/config.tsimport { createConfig, http } from wagmi/core import { mainnet, sepolia } from wagmi/core/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })关于 normalize 的必要性::: warning ENS 名称禁止某些特殊字符如下划线并有一套完整的校验规则。在把名称传给getEnsText之前建议先用 UTS-46 规范化规则对 ENS 名称做标准化处理。可以直接使用 Viem 内置的normalize函数从viem/ens导入完成该操作避免因名称格式问题导致解析失败。 :::从测试用例 packages/core/src/actions/getEnsText.test.ts 可以看到真实调用形态传入name: wevm.eth与key: com.twitter后期望返回值为wevm_dev。这说明该 Action 在链上真正执行了文本记录解析。参数详解getEnsText的参数类型为GetEnsTextParameters由 Viem 的参数类型与 Wagmi 的链 ID 参数组合而成import { type GetEnsTextParameters } from wagmi/core在源码 packages/core/src/actions/getEnsText.ts 中定义如下export type GetEnsTextParametersconfig extends Config Config Compute viem_GetEnsTextParameters ChainIdParameterconfig 下面逐一说明各参数。name必填string要读取文本记录的 ENS 名称。const ensText await getEnsText(config, { name: normalize(wevm.eth), // [!code focus] key: com.twitter, })key必填string要读取的 ENS 文本键常见取值包括com.twitter、com.github、email、avatar、url等。const ensText await getEnsText(config, { name: normalize(wevm.eth), key: com.twitter, // [!code focus] })blockNumberbigint | undefined指定在某个区块高度上读取文本记录适用于需要回溯历史状态的场景。const ensText getEnsText(config, { blockNumber: 17829139n, // [!code focus] name: normalize(wevm.eth), key: com.twitter, })blockTaglatest | earliest | pending | safe | finalized | undefined指定读取文本记录时的区块标签默认由客户端决定通常为latest。safe与finalized用于读取已确认的区块数据。const ensText getEnsText(config, { blockTag: latest, // [!code focus] name: normalize(wevm.eth), key: com.twitter, })chainIdconfig[chains][number][id] | undefined指定执行查询的链 ID。当 Config 中配置了多条链时通过该参数选择目标链未指定时使用当前客户端对应的链。例如指定以太坊主网import { mainnet } from wagmi/core/chains const ensText await getEnsText(config, { chainId: mainnet.id, // [!code focus] name: normalize(wevm.eth), key: com.twitter, })chainId在实现上会被单独解构出来用于定位客户端而不是透传给 Viemconst { chainId, ...rest } parameters const client config.getClient({ chainId })universalResolverAddressAddress | undefinedENS Universal Resolver 合约的地址。默认使用当前链上配置的 Universal Resolver 合约地址一般无需显式指定仅在链配置缺失或需要自定义解析器时才传入const ensText await getEnsText(config, { name: normalize(wevm.eth), key: com.twitter, universalResolverAddress: 0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376, // [!code focus] })返回值类型import { type GetEnsTextReturnType } from wagmi/corestring | null返回该 ENS 名称对应的文本记录字符串如果该名称没有设置对应的文本记录则返回null。仓库源码 packages/core/src/actions/getEnsText.ts 将其直接映射为 Viem 的返回类型export type GetEnsTextReturnType viem_GetEnsTextReturnType错误处理import { type GetEnsTextErrorType } from wagmi/coreGetEnsTextErrorType同样是 Viem 错误类型的透传见 packages/core/src/actions/getEnsText.ts。可能出现的错误包括名称未注册、Universal Resolver 解析失败、网络或 RPC 调用失败等。由于该 Action 返回 Promise建议在实际业务中使用try/catch或.catch()统一处理失败分支。源码级的执行链路阅读 packages/core/src/actions/getEnsText.ts 可以看到完整实现export function getEnsTextconfig extends Config( config: config, parameters: GetEnsTextParametersconfig, ): PromiseGetEnsTextReturnType { const { chainId, ...rest } parameters const client config.getClient({ chainId }) const action getAction(client, viem_getEnsText, getEnsText) return action(rest) }执行流程可概括为三步从参数中解构出chainId其余参数name、key、blockNumber、blockTag、universalResolverAddress等透传给 Viem通过config.getClient({ chainId })按链获取对应的 Viem Client使用getAction工具见 packages/core/src/utils/getAction.ts从 Client 上取到 Viem 的getEnsTextaction 并执行最终将 Viem 的 Promise 结果直接返回。这意味着 Wagmi 的getEnsText本质上是「Config 客户端管理 Viem 底层实现」的组合所有链上解析逻辑由 Viem 完成Wagmi 负责按chainId精确路由到正确的链客户端。与 TanStack Query 的集成除了直接调用 Action仓库还提供了配套的 Query 层封装见 packages/core/src/query/getEnsText.ts便于在框架中实现缓存、去重与自动刷新。相关类型与函数通过wagmi/core/query导出import { type GetEnsTextData, type GetEnsTextOptions, type GetEnsTextQueryFnData, type GetEnsTextQueryKey, getEnsTextQueryKey, getEnsTextQueryOptions, } from wagmi/core/querygetEnsTextQueryOptionsgetEnsTextQueryOptions(config, options)用于构造 TanStack Query 的选项对象核心逻辑包括enabled 控制只有当key与name都存在时才启用查询enabled: Boolean(options.key options.name (options.query?.enabled ?? true))避免参数缺失时发起无效请求queryFn从 queryKey 中取出参数并调用核心 Action若缺少key或name会抛出key and name are required错误queryKey由getEnsTextQueryKey生成。getEnsTextQueryKeyexport function getEnsTextQueryKeyconfig extends Config( options: ComputeExactPartialGetEnsTextParametersconfig ScopeKeyParameter {}, ) { return [ensText, filterQueryOptions(options)] as const }查询键统一以ensText开头后续跟随过滤后的参数对象。从 packages/core/src/query/getEnsText.test.ts 的测试快照可以看到两种典型形态默认调用无 chainId{ enabled: true, queryFn: [Function], queryKey: [ ensText, { key: com.twitter, name: wevm.eth } ] }指定chainId: chain.mainnet.id即 1时chainId会进入查询键从而让不同链上的同名查询彼此隔离{ queryKey: [ ensText, { chainId: 1, key: com.twitter, name: wevm.eth } ] }scopeKey等非查询参数则会被filterQueryOptions过滤掉不会污染查询键。框架层封装useEnsText在 React 框架包中该能力进一步封装为useEnsTextHook文档见 site/react/api/hooks/useEnsText.mdimport { useEnsText } from wagmi import { normalize } from viem/ens function App() { const result useEnsText({ name: normalize(wevm.eth), key: com.twitter, }) }useEnsText的底层正是基于getEnsTextQueryOptions实现因此天然继承 TanStack Query 的isPending、isError、data、refetch等状态字段适合直接嵌入组件渲染逻辑。Hook 支持与 Action 完全一致的参数name、key、blockNumber、blockTag、chainId、universalResolverAddress并额外提供query选项用于精细控制缓存与重试策略。总结getEnsText是 Wagmi 生态中读取 ENS 文本记录的标准入口直接使用核心 Action 时传入 Config 与{ name, key }即可配合blockNumber、blockTag、chainId、universalResolverAddress可精确控制查询位置与目标链参数中name与key必填其余均为可选返回值string | null需要处理空值分支内部通过config.getClient({ chainId })定位链客户端再委托给 Viem 执行实现简洁且职责清晰需要缓存与响应式更新时使用getEnsTextQueryOptions/getEnsTextQueryKey在 React 中可直接使用useEnsTextHook。参考实现与测试packages/core/src/actions/getEnsText.ts、packages/core/src/query/getEnsText.ts、packages/core/src/actions/getEnsText.test.ts。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考