useEnsAvatar在 wagmi 中获取 ENS 头像的完整指南【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseEnsAvatar是 wagmi 提供的 React Hook用于根据 ENS 名称ENS name获取对应的头像avatarURL。本文以 wagmi 仓库中的官方文档 site/react/api/hooks/useEnsAvatar.md 为主体结合 hooks 源码、core action 实现 与 测试用例 展开讲解覆盖导入方式、基本用法、全部参数含义、查询选项、返回类型以及底层查询键与缓存机制帮助你快速在 React 应用中实现 ENS 头像展示。导入 Hook在 React 组件中通过以下方式从wagmi导入useEnsAvatarimport { useEnsAvatar } from wagmiuseEnsAvatar基于 TanStack Query 实现返回的是一个查询结果对象而非直接的字符串因此可以自然融入WagmiProvidercreateConfig的响应式数据流中。基本用法下面是一个最小示例通过viem/ens提供的normalize函数将 ENS 名称规范化后传入 Hookimport { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), }) }配套的配置如下示例配置片段来自 site/snippets/react/config.tsimport { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })为什么必须先normalizeENS 名称禁止某些特殊字符如下划线_且存在其他校验规则因此在传给useEnsAvatar之前建议先使用 UTS-46 规范化 处理名称。Viem 内置的normalize函数正是为此设计可避免因名称未规范化导致的解析失败。参数ParametersuseEnsAvatar接受一个UseEnsAvatarParameters类型的参数对象类型定义如下import { type UseEnsAvatarParameters } from wagmi从源码看该类型是GetEnsAvatarOptionsconfig, selectData ConfigParameterconfig的合并结果见 packages/react/src/hooks/useEnsAvatar.ts#L17-L20即同时包含查询参数与 wagmi 配置参数。assetGatewayUrls类型{ ipfs?: string | undefined; arweave?: string | undefined } | undefined说明用于解析 IPFS 和/或 Arweave 资产的自定义网关 URL。当头像指向 IPFS 或 Arweave 上的资源时可通过该参数指定可访问的网关。版本要求viem2.3.1import { getEnsAvatar } from wagmi/core import { normalize } from viem/ens import { config } from ./config function App() { const result useEnsAvatar({ assetGatewayUrls: { ipfs: https://cloudflare-ipfs.com, }, name: normalize(wevm.eth), }) }blockNumber类型bigint | undefined说明指定在某个区块高度block number上获取 ENS 头像用于查询历史状态的头像。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ blockNumber: 17829139n, name: normalize(wevm.eth), }) }blockTag类型latest | earliest | pending | safe | finalized | undefined说明指定获取头像时使用的区块标签block tag默认通常为latest。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), blockTag: latest, }) }chainId类型config[chains][number][id] | undefined说明指定执行查询的链 ID。未指定时Hook 会通过useChainId自动使用当前激活的链。import { useEnsAvatar } from wagmi import { mainnet } from wagmi/chains import { normalize } from viem/ens function App() { const result useEnsAvatar({ chainId: mainnet.id, name: normalize(wevm.eth), }) }config类型Config | undefined说明显式传入Config以替代从最近的WagmiProvider中读取的配置。适用于脱离 Provider 上下文或需要覆盖配置的场景。import { useEnsAvatar } from wagmi import { normalize } from viem/ens import { config } from ./config function App() { const result useEnsAvatar({ config, name: normalize(wevm.eth), }) }gatewayUrls类型string[] | undefined说明一组 Universal Resolver 网关地址用于解析通过 ENS Universal Resolver 合约发起的 CCIP-Read 请求。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ gatewayUrls: [https://cloudflare-ipfs.com], name: normalize(wevm.eth), }) }name类型string | undefined说明要获取头像的 ENS 名称。当name为undefined时enabled会被自动置为false查询不会执行该逻辑见下文源码剖析部分。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), }) }scopeKey类型string | undefined说明将缓存限定在给定上下文范围内。具有相同scopeKey的 Hook 会共享同一份缓存适用于需要在不同场景下隔离或复用缓存数据的情形。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), scopeKey: foo, }) }universalResolverAddress类型Address | undefined说明ENS Universal Resolver 合约地址未指定时默认使用当前链的 Universal Resolver 合约地址。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), universalResolverAddress: 0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376, }) }查询选项queryuseEnsAvatar透传 TanStack Query 的查询选项详见 site/shared/query-options.md。需要特别说明wagmi 不允许覆盖所有 TanStack Query 参数其中queryFn与queryKey由 wagmi 内部使用不可自定义下表所列参数均受支持。参数类型默认值说明enabledboolean \| undefined—设为false可禁用查询自动执行常用于依赖查询Dependent QueriesgcTimenumber \| Infinity \| undefined5 * 60 * 10005 分钟SSR 期间为Infinity未使用/非活跃缓存数据的保留时长Infinity表示禁用垃圾回收initialDataTData \| (() TData) \| undefined—作为查询初始缓存数据函数形式仅会在共享/根查询初始化时调用一次默认视为已过期除非设置了staleTime会被持久化到缓存initialDataUpdatedAtnumber \| (() number \| undefined) \| undefined—initialData本身的最后更新时间毫秒metaRecordstring, unknown \| undefined—附加到查询缓存条目上的额外信息可在queryFn的QueryFunctionContext中访问networkModeonline \| always \| offlineFirst \| undefinedonline网络模式notifyOnChangePropsstring[] \| all \| (() string[] \| all) \| undefined默认按属性访问跟踪仅当列出的属性变化时触发组件重渲染placeholderDataTData \| ((previousValue, previousQuery) TData) \| undefined—查询处于pending状态时使用的占位数据不会持久化到缓存queryClientQueryClient \| undefined最近上下文中的实例指定自定义QueryClientrefetchIntervalnumber \| false \| ((data, query) number \| false \| undefined) \| undefined—定时自动重新拉取的毫秒间隔refetchIntervalInBackgroundboolean \| undefined—true时后台标签页也会继续定时重拉取refetchOnMountboolean \| always \| ((query) boolean \| always) \| undefinedtrue挂载时若数据已过期则重新拉取refetchOnReconnectboolean \| always \| ((query) boolean \| always) \| undefinedtrue网络重连时若数据已过期则重新拉取refetchOnWindowFocusboolean \| always \| ((query) boolean \| always) \| undefinedtrue窗口重新聚焦时若数据已过期则重新拉取retryboolean \| number \| ((failureCount, error) boolean) \| undefined客户端3服务端0失败重试策略retryDelaynumber \| ((retryAttempt, error) number) \| undefined—每次重试前的延迟毫秒数可配合指数退避函数retryOnMountboolean \| undefinedtrue挂载时若查询含错误是否重试select((data: TData) unknown) \| undefined—转换/选取查询数据只影响返回值data不影响缓存内容staleTimenumber \| Infinity \| undefined0数据过期时间毫秒Infinity表示永不过期structuralSharingboolean \| ((oldData, newData) TData) \| undefinedtrue是否启用查询结果间的结构共享注意对useEnsAvatar而言TData string | nullTError GetEnsAvatarErrorType。返回类型Return Typeimport { type UseEnsAvatarReturnType } from wagmi返回类型UseEnsAvatarReturnType实为UseQueryReturnTypestring | null, GetEnsAvatarErrorType见 packages/react/src/hooks/useEnsAvatar.ts#L22-L23即标准 TanStack Query 结果详见 site/shared/query-result.md。核心字段如下字段类型说明datastring \| null最近一次成功解析的头像 URL默认undefineddataUpdatedAtnumber查询最近一次返回success状态的时间戳errornull \| GetEnsAvatarErrorType查询抛出的错误对象默认nullerrorUpdatedAtnumber最近一次进入error状态的时间戳errorUpdateCountnumber累计错误次数failureCountnumber失败计数成功时重置为0failureReasonnull \| GetEnsAvatarErrorType重试失败的原因成功时重置为nullfetchStatusfetching \| idle \| paused查询拉取状态isError/isPending/isSuccessboolean由status派生的布尔标记isFetchedboolean查询是否已完成过拉取isFetchedAfterMountboolean组件挂载后是否拉取过可用于隐藏旧缓存isFetching/isPausedboolean由fetchStatus派生的布尔标记isLoadingboolean首次拉取进行中等价于isFetching isPendingisLoadingErrorboolean首次拉取是否失败isPlaceholderDataboolean当前展示的是否为占位数据isRefetchErrorboolean后台重拉取是否失败isRefetchingboolean后台重拉取进行中等价于isFetching !isPendingisStaleboolean缓存数据是否已过期refetch(options) Promise...手动重新拉取throwOnError控制失败时抛错还是仅记录日志cancelRefetch控制是否取消正在运行的请求默认truestatuserror \| pending \| success查询整体状态在组件中通常会这样使用const { data: avatar, isPending, isError, error } useEnsAvatar({ name: normalize(wevm.eth), }) if (isPending) return divLoading avatar…/div if (isError) return divError: {error.message}/div return avatar ? img src{avatar} altENS avatar / : nullTanStack Query 编程式 API如果希望脱离 React Hook使用底层命令式 API例如在事件处理函数中手动触发查询可以从wagmi/query导入对应类型与工具详见 site/shared/query-imports.mdimport { type GetEnsAvatarData, type GetEnsAvatarOptions, type GetEnsAvatarQueryFnData, type GetEnsAvatarQueryKey, getEnsAvatarQueryKey, getEnsAvatarQueryOptions, } from wagmi/queryActiongetEnsAvataruseEnsAvatar底层委托给getEnsAvataraction。核心实现位于 packages/core/src/actions/getEnsAvatar.tsexport function getEnsAvatarconfig extends Config( config: config, parameters: GetEnsAvatarParametersconfig, ): PromiseGetEnsAvatarReturnType { const { chainId, ...rest } parameters const client config.getClient({ chainId }) const action getAction(client, viem_getEnsAvatar, getEnsAvatar) return action(rest) }调用链可概括为useEnsAvatarReact Hook→getEnsAvatarQueryOptions查询选项→getEnsAvatarcore action→viem的getEnsAvatarviem/actions导入→ 链上 Universal Resolver 合约解析。chainId参数被单独取出并用于从config获取对应链的 viem client其余参数name、blockNumber、blockTag、gatewayUrls、assetGatewayUrls、universalResolverAddress等原样透传给 viem。源码剖析Hook 的底层工作原理结合 packages/react/src/hooks/useEnsAvatar.ts 可看到完整实现export function useEnsAvatar config extends Config ResolvedRegister[config], selectData GetEnsAvatarData, ( parameters: UseEnsAvatarParametersconfig, selectData {}, ): UseEnsAvatarReturnTypeselectData { const config useConfig(parameters) const chainId useChainId({ config }) const options getEnsAvatarQueryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, }) return useQuery(options) }其工作流程为读取配置通过useConfig(parameters)获取 wagmi 配置若传入了config参数则优先使用否则从最近的WagmiProvider上下文获取确定链 ID通过useChainId({ config })获取当前链 ID若未显式传入chainId则以当前链为准构造查询选项调用getEnsAvatarQueryOptions生成enabled、queryFn、queryKey执行查询交给 TanStack Query 的useQuery驱动拉取、缓存与重渲染。查询键与 enabled 逻辑查询选项的核心逻辑位于 packages/core/src/query/getEnsAvatar.tsreturn { ...options.query, enabled: Boolean(options.name (options.query?.enabled ?? true)), queryFn: async (context) { const [, { scopeKey: _, ...parameters }] context.queryKey if (!parameters.name) throw new Error(name is required) return getEnsAvatar(config, { ...parameters, name: parameters.name }) }, queryKey: getEnsAvatarQueryKey(options), }关键点enabled与name强绑定只要name未提供查询就不会执行即使手动设置了query.enabled true查询键格式[ensAvatar, { chainId, name, ... }]由getEnsAvatarQueryKey生成见 packages/core/src/query/getEnsAvatar.ts#L47-L53。查询键中包含chainId与name意味着不同链或不同名称的头像查询互不共享缓存scopeKey参与缓存隔离scopeKey会保留在查询键中filterQueryOptions不会过滤它因此传入不同scopeKey的相同查询会各自独立缓存。测试用例印证仓库中的测试 packages/react/src/hooks/useEnsAvatar.test.ts 验证了默认行为test(default, async () { const { result } await renderHook(() useEnsAvatar({ name: wevm.eth }), ) await vi.waitUntil(() result.current.isSuccess, { timeout: 10_000 }) expect(result.current).toMatchInlineSnapshot( { data: https://euc.li/wevm.eth, ... queryKey: [ ensAvatar, { chainId: 1, name: wevm.eth, }, ], ... } ) })该用例确认了两个事实对wevm.eth查询成功后会返回头像 URL测试快照中的值为https://euc.li/wevm.eth生成的查询键为[ensAvatar, { chainId: 1, name: wevm.eth }]与源码中getEnsAvatarQueryKey的实现一致。小结useEnsAvatar是 wagmi 中获取 ENS 头像的推荐方式它封装了 viem 的底层解析能力并通过 TanStack Query 提供开箱即用的缓存、重试、依赖查询与 SSR 支持。使用时牢记两点传入前用normalize规范化 ENS 名称、name缺失时查询会被自动禁用。若需在非 React 环境使用同一能力可直接调用getEnsAvataraction 或从wagmi/query导入查询工具函数。更多相关能力可参考useEnsAddress等 ENS 系列 Hook 的文档。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 useEnsAvatar：在 wagmi 中获取 ENS 头像的完整指南
useEnsAvatar在 wagmi 中获取 ENS 头像的完整指南【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseEnsAvatar是 wagmi 提供的 React Hook用于根据 ENS 名称ENS name获取对应的头像avatarURL。本文以 wagmi 仓库中的官方文档 site/react/api/hooks/useEnsAvatar.md 为主体结合 hooks 源码、core action 实现 与 测试用例 展开讲解覆盖导入方式、基本用法、全部参数含义、查询选项、返回类型以及底层查询键与缓存机制帮助你快速在 React 应用中实现 ENS 头像展示。导入 Hook在 React 组件中通过以下方式从wagmi导入useEnsAvatarimport { useEnsAvatar } from wagmiuseEnsAvatar基于 TanStack Query 实现返回的是一个查询结果对象而非直接的字符串因此可以自然融入WagmiProvidercreateConfig的响应式数据流中。基本用法下面是一个最小示例通过viem/ens提供的normalize函数将 ENS 名称规范化后传入 Hookimport { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), }) }配套的配置如下示例配置片段来自 site/snippets/react/config.tsimport { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })为什么必须先normalizeENS 名称禁止某些特殊字符如下划线_且存在其他校验规则因此在传给useEnsAvatar之前建议先使用 UTS-46 规范化 处理名称。Viem 内置的normalize函数正是为此设计可避免因名称未规范化导致的解析失败。参数ParametersuseEnsAvatar接受一个UseEnsAvatarParameters类型的参数对象类型定义如下import { type UseEnsAvatarParameters } from wagmi从源码看该类型是GetEnsAvatarOptionsconfig, selectData ConfigParameterconfig的合并结果见 packages/react/src/hooks/useEnsAvatar.ts#L17-L20即同时包含查询参数与 wagmi 配置参数。assetGatewayUrls类型{ ipfs?: string | undefined; arweave?: string | undefined } | undefined说明用于解析 IPFS 和/或 Arweave 资产的自定义网关 URL。当头像指向 IPFS 或 Arweave 上的资源时可通过该参数指定可访问的网关。版本要求viem2.3.1import { getEnsAvatar } from wagmi/core import { normalize } from viem/ens import { config } from ./config function App() { const result useEnsAvatar({ assetGatewayUrls: { ipfs: https://cloudflare-ipfs.com, }, name: normalize(wevm.eth), }) }blockNumber类型bigint | undefined说明指定在某个区块高度block number上获取 ENS 头像用于查询历史状态的头像。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ blockNumber: 17829139n, name: normalize(wevm.eth), }) }blockTag类型latest | earliest | pending | safe | finalized | undefined说明指定获取头像时使用的区块标签block tag默认通常为latest。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), blockTag: latest, }) }chainId类型config[chains][number][id] | undefined说明指定执行查询的链 ID。未指定时Hook 会通过useChainId自动使用当前激活的链。import { useEnsAvatar } from wagmi import { mainnet } from wagmi/chains import { normalize } from viem/ens function App() { const result useEnsAvatar({ chainId: mainnet.id, name: normalize(wevm.eth), }) }config类型Config | undefined说明显式传入Config以替代从最近的WagmiProvider中读取的配置。适用于脱离 Provider 上下文或需要覆盖配置的场景。import { useEnsAvatar } from wagmi import { normalize } from viem/ens import { config } from ./config function App() { const result useEnsAvatar({ config, name: normalize(wevm.eth), }) }gatewayUrls类型string[] | undefined说明一组 Universal Resolver 网关地址用于解析通过 ENS Universal Resolver 合约发起的 CCIP-Read 请求。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ gatewayUrls: [https://cloudflare-ipfs.com], name: normalize(wevm.eth), }) }name类型string | undefined说明要获取头像的 ENS 名称。当name为undefined时enabled会被自动置为false查询不会执行该逻辑见下文源码剖析部分。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), }) }scopeKey类型string | undefined说明将缓存限定在给定上下文范围内。具有相同scopeKey的 Hook 会共享同一份缓存适用于需要在不同场景下隔离或复用缓存数据的情形。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), scopeKey: foo, }) }universalResolverAddress类型Address | undefined说明ENS Universal Resolver 合约地址未指定时默认使用当前链的 Universal Resolver 合约地址。import { useEnsAvatar } from wagmi import { normalize } from viem/ens function App() { const result useEnsAvatar({ name: normalize(wevm.eth), universalResolverAddress: 0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376, }) }查询选项queryuseEnsAvatar透传 TanStack Query 的查询选项详见 site/shared/query-options.md。需要特别说明wagmi 不允许覆盖所有 TanStack Query 参数其中queryFn与queryKey由 wagmi 内部使用不可自定义下表所列参数均受支持。参数类型默认值说明enabledboolean \| undefined—设为false可禁用查询自动执行常用于依赖查询Dependent QueriesgcTimenumber \| Infinity \| undefined5 * 60 * 10005 分钟SSR 期间为Infinity未使用/非活跃缓存数据的保留时长Infinity表示禁用垃圾回收initialDataTData \| (() TData) \| undefined—作为查询初始缓存数据函数形式仅会在共享/根查询初始化时调用一次默认视为已过期除非设置了staleTime会被持久化到缓存initialDataUpdatedAtnumber \| (() number \| undefined) \| undefined—initialData本身的最后更新时间毫秒metaRecordstring, unknown \| undefined—附加到查询缓存条目上的额外信息可在queryFn的QueryFunctionContext中访问networkModeonline \| always \| offlineFirst \| undefinedonline网络模式notifyOnChangePropsstring[] \| all \| (() string[] \| all) \| undefined默认按属性访问跟踪仅当列出的属性变化时触发组件重渲染placeholderDataTData \| ((previousValue, previousQuery) TData) \| undefined—查询处于pending状态时使用的占位数据不会持久化到缓存queryClientQueryClient \| undefined最近上下文中的实例指定自定义QueryClientrefetchIntervalnumber \| false \| ((data, query) number \| false \| undefined) \| undefined—定时自动重新拉取的毫秒间隔refetchIntervalInBackgroundboolean \| undefined—true时后台标签页也会继续定时重拉取refetchOnMountboolean \| always \| ((query) boolean \| always) \| undefinedtrue挂载时若数据已过期则重新拉取refetchOnReconnectboolean \| always \| ((query) boolean \| always) \| undefinedtrue网络重连时若数据已过期则重新拉取refetchOnWindowFocusboolean \| always \| ((query) boolean \| always) \| undefinedtrue窗口重新聚焦时若数据已过期则重新拉取retryboolean \| number \| ((failureCount, error) boolean) \| undefined客户端3服务端0失败重试策略retryDelaynumber \| ((retryAttempt, error) number) \| undefined—每次重试前的延迟毫秒数可配合指数退避函数retryOnMountboolean \| undefinedtrue挂载时若查询含错误是否重试select((data: TData) unknown) \| undefined—转换/选取查询数据只影响返回值data不影响缓存内容staleTimenumber \| Infinity \| undefined0数据过期时间毫秒Infinity表示永不过期structuralSharingboolean \| ((oldData, newData) TData) \| undefinedtrue是否启用查询结果间的结构共享注意对useEnsAvatar而言TData string | nullTError GetEnsAvatarErrorType。返回类型Return Typeimport { type UseEnsAvatarReturnType } from wagmi返回类型UseEnsAvatarReturnType实为UseQueryReturnTypestring | null, GetEnsAvatarErrorType见 packages/react/src/hooks/useEnsAvatar.ts#L22-L23即标准 TanStack Query 结果详见 site/shared/query-result.md。核心字段如下字段类型说明datastring \| null最近一次成功解析的头像 URL默认undefineddataUpdatedAtnumber查询最近一次返回success状态的时间戳errornull \| GetEnsAvatarErrorType查询抛出的错误对象默认nullerrorUpdatedAtnumber最近一次进入error状态的时间戳errorUpdateCountnumber累计错误次数failureCountnumber失败计数成功时重置为0failureReasonnull \| GetEnsAvatarErrorType重试失败的原因成功时重置为nullfetchStatusfetching \| idle \| paused查询拉取状态isError/isPending/isSuccessboolean由status派生的布尔标记isFetchedboolean查询是否已完成过拉取isFetchedAfterMountboolean组件挂载后是否拉取过可用于隐藏旧缓存isFetching/isPausedboolean由fetchStatus派生的布尔标记isLoadingboolean首次拉取进行中等价于isFetching isPendingisLoadingErrorboolean首次拉取是否失败isPlaceholderDataboolean当前展示的是否为占位数据isRefetchErrorboolean后台重拉取是否失败isRefetchingboolean后台重拉取进行中等价于isFetching !isPendingisStaleboolean缓存数据是否已过期refetch(options) Promise...手动重新拉取throwOnError控制失败时抛错还是仅记录日志cancelRefetch控制是否取消正在运行的请求默认truestatuserror \| pending \| success查询整体状态在组件中通常会这样使用const { data: avatar, isPending, isError, error } useEnsAvatar({ name: normalize(wevm.eth), }) if (isPending) return divLoading avatar…/div if (isError) return divError: {error.message}/div return avatar ? img src{avatar} altENS avatar / : nullTanStack Query 编程式 API如果希望脱离 React Hook使用底层命令式 API例如在事件处理函数中手动触发查询可以从wagmi/query导入对应类型与工具详见 site/shared/query-imports.mdimport { type GetEnsAvatarData, type GetEnsAvatarOptions, type GetEnsAvatarQueryFnData, type GetEnsAvatarQueryKey, getEnsAvatarQueryKey, getEnsAvatarQueryOptions, } from wagmi/queryActiongetEnsAvataruseEnsAvatar底层委托给getEnsAvataraction。核心实现位于 packages/core/src/actions/getEnsAvatar.tsexport function getEnsAvatarconfig extends Config( config: config, parameters: GetEnsAvatarParametersconfig, ): PromiseGetEnsAvatarReturnType { const { chainId, ...rest } parameters const client config.getClient({ chainId }) const action getAction(client, viem_getEnsAvatar, getEnsAvatar) return action(rest) }调用链可概括为useEnsAvatarReact Hook→getEnsAvatarQueryOptions查询选项→getEnsAvatarcore action→viem的getEnsAvatarviem/actions导入→ 链上 Universal Resolver 合约解析。chainId参数被单独取出并用于从config获取对应链的 viem client其余参数name、blockNumber、blockTag、gatewayUrls、assetGatewayUrls、universalResolverAddress等原样透传给 viem。源码剖析Hook 的底层工作原理结合 packages/react/src/hooks/useEnsAvatar.ts 可看到完整实现export function useEnsAvatar config extends Config ResolvedRegister[config], selectData GetEnsAvatarData, ( parameters: UseEnsAvatarParametersconfig, selectData {}, ): UseEnsAvatarReturnTypeselectData { const config useConfig(parameters) const chainId useChainId({ config }) const options getEnsAvatarQueryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, }) return useQuery(options) }其工作流程为读取配置通过useConfig(parameters)获取 wagmi 配置若传入了config参数则优先使用否则从最近的WagmiProvider上下文获取确定链 ID通过useChainId({ config })获取当前链 ID若未显式传入chainId则以当前链为准构造查询选项调用getEnsAvatarQueryOptions生成enabled、queryFn、queryKey执行查询交给 TanStack Query 的useQuery驱动拉取、缓存与重渲染。查询键与 enabled 逻辑查询选项的核心逻辑位于 packages/core/src/query/getEnsAvatar.tsreturn { ...options.query, enabled: Boolean(options.name (options.query?.enabled ?? true)), queryFn: async (context) { const [, { scopeKey: _, ...parameters }] context.queryKey if (!parameters.name) throw new Error(name is required) return getEnsAvatar(config, { ...parameters, name: parameters.name }) }, queryKey: getEnsAvatarQueryKey(options), }关键点enabled与name强绑定只要name未提供查询就不会执行即使手动设置了query.enabled true查询键格式[ensAvatar, { chainId, name, ... }]由getEnsAvatarQueryKey生成见 packages/core/src/query/getEnsAvatar.ts#L47-L53。查询键中包含chainId与name意味着不同链或不同名称的头像查询互不共享缓存scopeKey参与缓存隔离scopeKey会保留在查询键中filterQueryOptions不会过滤它因此传入不同scopeKey的相同查询会各自独立缓存。测试用例印证仓库中的测试 packages/react/src/hooks/useEnsAvatar.test.ts 验证了默认行为test(default, async () { const { result } await renderHook(() useEnsAvatar({ name: wevm.eth }), ) await vi.waitUntil(() result.current.isSuccess, { timeout: 10_000 }) expect(result.current).toMatchInlineSnapshot( { data: https://euc.li/wevm.eth, ... queryKey: [ ensAvatar, { chainId: 1, name: wevm.eth, }, ], ... } ) })该用例确认了两个事实对wevm.eth查询成功后会返回头像 URL测试快照中的值为https://euc.li/wevm.eth生成的查询键为[ensAvatar, { chainId: 1, name: wevm.eth }]与源码中getEnsAvatarQueryKey的实现一致。小结useEnsAvatar是 wagmi 中获取 ENS 头像的推荐方式它封装了 viem 的底层解析能力并通过 TanStack Query 提供开箱即用的缓存、重试、依赖查询与 SSR 支持。使用时牢记两点传入前用normalize规范化 ENS 名称、name缺失时查询会被自动禁用。若需在非 React 环境使用同一能力可直接调用getEnsAvataraction 或从wagmi/query导入查询工具函数。更多相关能力可参考useEnsAddress等 ENS 系列 Hook 的文档。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考