尧图网站建设 
Preact Query 错误重置函数 QueryErrorResetFunction 深入解析与 QueryErrorResetBoundary 协作的完整机制【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryQueryErrorResetFunction是tanstack/preact-query定义的一个核心类型别名描述清除错误边界内所有查询错误、让查询知晓可以重试的回调函数签名。本文将围绕这一类型定义展开其所属的 QueryErrorResetBoundary 错误重置机制包括配套类型、底层闭包实现、与 Error Boundary / Suspense 的协作流程以及useBaseQuery中的真实调用链。导读本文聚焦 Preact Querytanstack/preact-query中与错误边界Error Boundary恢复相关的一类回调签名QueryErrorResetFunction () void。当你在查询中开启suspense或throwOnError并配合 Preact 的错误边界捕获渲染错误时需要一个明确的信号通知查询对象错误已被用户处理可以重新尝试。读完本文你将掌握该类型别名的精确定义与导出位置、它如何被reset/clearReset等函数使用、底层isReset标志位的生命周期以及一个可复制的点击 Try again 重试实战示例。1. 类型别名定义一个无参无返回的重置回调关联文档给出的定义如下位于 packages/preact-query/src/QueryErrorResetBoundary.tsx:10type QueryErrorResetFunction () void;其官方注释原文为Resets any query errors within the boundary, so queries know they can try again.重置边界内的任何查询错误让查询知道自己可以再次尝试返回值为void。它是 TypeScript 层面的纯类型声明type alias不带任何泛型参数、不接收任何入参语义上是一个已发生的动作信号而非携带数据的处理器。从导出链看该类型并非仅在文档中出现而是作为公共 API 从包入口统一输出在 packages/preact-query/src/index.ts:41-46 中与QueryErrorClearResetFunction、QueryErrorIsResetFunction、QueryErrorResetBoundaryFunction等类型一同被 re-export因此使用者可直接通过import type { QueryErrorResetFunction } from tanstack/preact-query引用它。在 docs/framework/preact/reference/index.md 的类型别名清单中亦能看到它的收录。2. 三个伴生回调类型与值对象接口QueryErrorResetFunction并不是孤立存在的。在 packages/preact-query/src/QueryErrorResetBoundary.tsx:15-20 中它与另外两个函数类型组成一套重置状态机export type QueryErrorResetFunction () void // 重置告知查询可重试 export type QueryErrorIsResetFunction () boolean // 查询当前是否处于已重置且未清除状态 export type QueryErrorClearResetFunction () void // 清除重置状态告知查询不可再重试三者共同组成QueryErrorResetBoundaryValue接口同文件第 22-35 行该接口作为 Context 值与 render-prop 参数四处传递export interface QueryErrorResetBoundaryValue { clearReset: QueryErrorClearResetFunction isReset: QueryErrorIsResetFunction reset: QueryErrorResetFunction }可以这样理解三者的职责闭环函数类型行为resetQueryErrorResetFunction把边界标记为已重置isReset true查询据此得知可以再次发起请求clearResetQueryErrorClearResetFunction清除重置标记isReset false通常在新一次渲染挂载完成后自动调用isResetQueryErrorIsResetFunction返回当前是否处于已重置且尚未被清除的窗口期3. 底层实现基于闭包的布尔状态机reset的行为由 QueryErrorResetBoundary.tsx 的createValue工厂函数 用闭包实现不需要任何外部状态库function createValue(): QueryErrorResetBoundaryValue { let isReset false return { clearReset: () { isReset false }, reset: () { isReset true }, isReset: () { return isReset }, } }关键点在于reset本身不触发任何网络请求也不直接操作 QueryCache它只翻转一个闭包内布尔标志位。真正是否重试的判断发生在渲染阶段由查询读取该标志后决定见下文第 5 节。默认的 Context 初始值也由createValue()生成第 52 行保证没有任何 Provider 包裹时也有一个可用的空实现。4. 组件与 Hook如何获得 reset在 Preact Query 中错误重置能力通过一对 API 暴露QueryErrorResetBoundary组件与useQueryErrorResetBoundaryHook。4.1 useQueryErrorResetBoundary该 Hook 定义于 QueryErrorResetBoundary.tsx:85-86只是对 Context 的读取export const useQueryErrorResetBoundary () useContext(QueryErrorResetBoundaryContext)其文档注释说明了作用范围如果没有定义任何 Boundary它将全局重置查询错误否则重置最近的QueryErrorResetBoundary边界内的错误。函数签名与返回值见 functions/useQueryErrorResetBoundary.md返回QueryErrorResetBoundaryValue。4.2 QueryErrorResetBoundary 组件该组件定义于 QueryErrorResetBoundary.tsx:159-168通过useState(() createValue())在组件生命周期内固化一份状态机值并以 Context Provider 形式向下分发若children是函数则作为 render-prop 直接调用并传入该值export const QueryErrorResetBoundary ({ children, }: QueryErrorResetBoundaryProps) { const [value] useState(() createValue()) return ( QueryErrorResetBoundaryContext.Provider value{value} {typeof children function ? children(value) : children} /QueryErrorResetBoundaryContext.Provider ) }接受QueryErrorResetBoundaryProps组件文档完整参数说明见 reference 索引中列出的接口条目。4.3 组合实战Try again组件文档中给出了标准组合用法——把reset传给自定义 Error Boundary点击按钮时先重置查询错误状态、再让 Preact 重新渲染子树import { useErrorBoundary } from preact/hooks import type { ComponentChildren } from preact import { QueryErrorResetBoundary } from tanstack/preact-query function App() { return ( QueryErrorResetBoundary {({ reset }) ( ErrorBoundary reset{reset} Page / /ErrorBoundary )} /QueryErrorResetBoundary ) } function ErrorBoundary({ children, reset, }: { children: ComponentChildren reset: () void }) { const [error, resetError] useErrorBoundary(() reset()) if (error) { return ( div There was an error! button onClick{() resetError()}Try again/button /div ) } return children }其中useErrorBoundary(() reset())的语义是当用户点击Try again触发resetError()时先执行reset()把闭包内isReset置为true随后 Preact 重渲染组件树、清空错误边界——这正是QueryErrorResetFunction在真实场景下的唯一职责。5. 底层协作链reset 标志如何在查询中被消费仅了解reset翻转标志位还不够需要看它如何决定查询重试。以useBaseQuery为核心packages/preact-query/src/useBaseQuery.ts每轮渲染都会消费 errorResetBoundary渲染期读取第 52 行useQueryErrorResetBoundary()取得当前边界值抑制重试调用ensurePreventErrorBoundaryRetry(...)第 79 行逻辑位于 errorBoundaryUtils.ts:13-41if (options.suspense || throwOnError) { // Prevent retrying failed query if the error boundary has not been reset yet if (!errorResetBoundary.isReset()) { options.retryOnMount false } }即只要错误边界未重置用户还没点击重试即使查询因重新挂载也不会立刻自动重试避免错误循环轰炸。卸载后自动清除useClearResetErrorBoundary(errorResetBoundary)第 81 行通过useEffect在每次渲染后调用clearReset()errorBoundaryUtils.ts:43-49把isReset复位为false保证重置窗口只在一次错误恢复流程内有效判定是否抛错getHasError(...)第 123-133 行综合判断后向 Error Boundary 抛出错误其条件errorBoundaryUtils.ts:51-78为return ( result.isError !errorResetBoundary.isReset() !result.isFetching query ((suspense result.data undefined) || shouldThrowError(throwOnError, [result.error, query])) )注意!errorResetBoundary.isReset()这一条件当用户已经执行reset()后错误将不再被抛出查询才有机会重新拉取数据。Suspense 失败兜底若挂载期使用fetchOptimistic抛出的 Promise 最终失败其.catch中也会执行errorResetBoundary.clearReset()packages/preact-query/src/suspense.ts:74-76把状态机复位到未重置状态等待下一次用户触发reset。同样的协作逻辑也存在于useQueriespackages/preact-query/src/useQueries.ts中。6. 多框架一致性React Query 中的同构实现值得说明的是该错误重置机制并非 Preact 独有。在 React 生态中packages/react-query/src/QueryErrorResetBoundary.tsx 实现了完全同构的一套类型与组件QueryErrorResetFunction () void第 5 行、createValue闭包第 18-40 行、useQueryErrorResetBoundary与QueryErrorResetBoundary第 76-145 行两者共享同样的状态机设计只是分别基于preact/hooks与react的 Context 原语。若你需要在 React 与 Preact 之间移植错误恢复代码这套 API 的调用语义可以保持一致。7. 关键要点速览QueryErrorResetFunction仅是一个() void类型别名定义并导出自 packages/preact-query/src/QueryErrorResetBoundary.tsx是QueryErrorResetBoundaryValue.reset字段的类型。调用reset()只会把闭包内isReset置为true真正的重试决策在后续渲染中由errorBoundaryUtils的判断完成。reset之后必须配合 Preact 错误边界复位重渲染一起使用才能看到Try again → 请求重新发出 → 页面恢复的完整效果。每次渲染周期结束后useEffect会调用clearReset()因此重置状态是一次性的窗口不会无限期阻止错误抛出。所有相关 API 均可从tanstack/preact-query包入口统一导入完整类型与函数清单见 Preact Query API 参考索引。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Preact Query 错误重置函数 QueryErrorResetFunction 深入解析：与 QueryErrorResetBoundary 协作的完整机制
Preact Query 错误重置函数 QueryErrorResetFunction 深入解析与 QueryErrorResetBoundary 协作的完整机制【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryQueryErrorResetFunction是tanstack/preact-query定义的一个核心类型别名描述清除错误边界内所有查询错误、让查询知晓可以重试的回调函数签名。本文将围绕这一类型定义展开其所属的 QueryErrorResetBoundary 错误重置机制包括配套类型、底层闭包实现、与 Error Boundary / Suspense 的协作流程以及useBaseQuery中的真实调用链。导读本文聚焦 Preact Querytanstack/preact-query中与错误边界Error Boundary恢复相关的一类回调签名QueryErrorResetFunction () void。当你在查询中开启suspense或throwOnError并配合 Preact 的错误边界捕获渲染错误时需要一个明确的信号通知查询对象错误已被用户处理可以重新尝试。读完本文你将掌握该类型别名的精确定义与导出位置、它如何被reset/clearReset等函数使用、底层isReset标志位的生命周期以及一个可复制的点击 Try again 重试实战示例。1. 类型别名定义一个无参无返回的重置回调关联文档给出的定义如下位于 packages/preact-query/src/QueryErrorResetBoundary.tsx:10type QueryErrorResetFunction () void;其官方注释原文为Resets any query errors within the boundary, so queries know they can try again.重置边界内的任何查询错误让查询知道自己可以再次尝试返回值为void。它是 TypeScript 层面的纯类型声明type alias不带任何泛型参数、不接收任何入参语义上是一个已发生的动作信号而非携带数据的处理器。从导出链看该类型并非仅在文档中出现而是作为公共 API 从包入口统一输出在 packages/preact-query/src/index.ts:41-46 中与QueryErrorClearResetFunction、QueryErrorIsResetFunction、QueryErrorResetBoundaryFunction等类型一同被 re-export因此使用者可直接通过import type { QueryErrorResetFunction } from tanstack/preact-query引用它。在 docs/framework/preact/reference/index.md 的类型别名清单中亦能看到它的收录。2. 三个伴生回调类型与值对象接口QueryErrorResetFunction并不是孤立存在的。在 packages/preact-query/src/QueryErrorResetBoundary.tsx:15-20 中它与另外两个函数类型组成一套重置状态机export type QueryErrorResetFunction () void // 重置告知查询可重试 export type QueryErrorIsResetFunction () boolean // 查询当前是否处于已重置且未清除状态 export type QueryErrorClearResetFunction () void // 清除重置状态告知查询不可再重试三者共同组成QueryErrorResetBoundaryValue接口同文件第 22-35 行该接口作为 Context 值与 render-prop 参数四处传递export interface QueryErrorResetBoundaryValue { clearReset: QueryErrorClearResetFunction isReset: QueryErrorIsResetFunction reset: QueryErrorResetFunction }可以这样理解三者的职责闭环函数类型行为resetQueryErrorResetFunction把边界标记为已重置isReset true查询据此得知可以再次发起请求clearResetQueryErrorClearResetFunction清除重置标记isReset false通常在新一次渲染挂载完成后自动调用isResetQueryErrorIsResetFunction返回当前是否处于已重置且尚未被清除的窗口期3. 底层实现基于闭包的布尔状态机reset的行为由 QueryErrorResetBoundary.tsx 的createValue工厂函数 用闭包实现不需要任何外部状态库function createValue(): QueryErrorResetBoundaryValue { let isReset false return { clearReset: () { isReset false }, reset: () { isReset true }, isReset: () { return isReset }, } }关键点在于reset本身不触发任何网络请求也不直接操作 QueryCache它只翻转一个闭包内布尔标志位。真正是否重试的判断发生在渲染阶段由查询读取该标志后决定见下文第 5 节。默认的 Context 初始值也由createValue()生成第 52 行保证没有任何 Provider 包裹时也有一个可用的空实现。4. 组件与 Hook如何获得 reset在 Preact Query 中错误重置能力通过一对 API 暴露QueryErrorResetBoundary组件与useQueryErrorResetBoundaryHook。4.1 useQueryErrorResetBoundary该 Hook 定义于 QueryErrorResetBoundary.tsx:85-86只是对 Context 的读取export const useQueryErrorResetBoundary () useContext(QueryErrorResetBoundaryContext)其文档注释说明了作用范围如果没有定义任何 Boundary它将全局重置查询错误否则重置最近的QueryErrorResetBoundary边界内的错误。函数签名与返回值见 functions/useQueryErrorResetBoundary.md返回QueryErrorResetBoundaryValue。4.2 QueryErrorResetBoundary 组件该组件定义于 QueryErrorResetBoundary.tsx:159-168通过useState(() createValue())在组件生命周期内固化一份状态机值并以 Context Provider 形式向下分发若children是函数则作为 render-prop 直接调用并传入该值export const QueryErrorResetBoundary ({ children, }: QueryErrorResetBoundaryProps) { const [value] useState(() createValue()) return ( QueryErrorResetBoundaryContext.Provider value{value} {typeof children function ? children(value) : children} /QueryErrorResetBoundaryContext.Provider ) }接受QueryErrorResetBoundaryProps组件文档完整参数说明见 reference 索引中列出的接口条目。4.3 组合实战Try again组件文档中给出了标准组合用法——把reset传给自定义 Error Boundary点击按钮时先重置查询错误状态、再让 Preact 重新渲染子树import { useErrorBoundary } from preact/hooks import type { ComponentChildren } from preact import { QueryErrorResetBoundary } from tanstack/preact-query function App() { return ( QueryErrorResetBoundary {({ reset }) ( ErrorBoundary reset{reset} Page / /ErrorBoundary )} /QueryErrorResetBoundary ) } function ErrorBoundary({ children, reset, }: { children: ComponentChildren reset: () void }) { const [error, resetError] useErrorBoundary(() reset()) if (error) { return ( div There was an error! button onClick{() resetError()}Try again/button /div ) } return children }其中useErrorBoundary(() reset())的语义是当用户点击Try again触发resetError()时先执行reset()把闭包内isReset置为true随后 Preact 重渲染组件树、清空错误边界——这正是QueryErrorResetFunction在真实场景下的唯一职责。5. 底层协作链reset 标志如何在查询中被消费仅了解reset翻转标志位还不够需要看它如何决定查询重试。以useBaseQuery为核心packages/preact-query/src/useBaseQuery.ts每轮渲染都会消费 errorResetBoundary渲染期读取第 52 行useQueryErrorResetBoundary()取得当前边界值抑制重试调用ensurePreventErrorBoundaryRetry(...)第 79 行逻辑位于 errorBoundaryUtils.ts:13-41if (options.suspense || throwOnError) { // Prevent retrying failed query if the error boundary has not been reset yet if (!errorResetBoundary.isReset()) { options.retryOnMount false } }即只要错误边界未重置用户还没点击重试即使查询因重新挂载也不会立刻自动重试避免错误循环轰炸。卸载后自动清除useClearResetErrorBoundary(errorResetBoundary)第 81 行通过useEffect在每次渲染后调用clearReset()errorBoundaryUtils.ts:43-49把isReset复位为false保证重置窗口只在一次错误恢复流程内有效判定是否抛错getHasError(...)第 123-133 行综合判断后向 Error Boundary 抛出错误其条件errorBoundaryUtils.ts:51-78为return ( result.isError !errorResetBoundary.isReset() !result.isFetching query ((suspense result.data undefined) || shouldThrowError(throwOnError, [result.error, query])) )注意!errorResetBoundary.isReset()这一条件当用户已经执行reset()后错误将不再被抛出查询才有机会重新拉取数据。Suspense 失败兜底若挂载期使用fetchOptimistic抛出的 Promise 最终失败其.catch中也会执行errorResetBoundary.clearReset()packages/preact-query/src/suspense.ts:74-76把状态机复位到未重置状态等待下一次用户触发reset。同样的协作逻辑也存在于useQueriespackages/preact-query/src/useQueries.ts中。6. 多框架一致性React Query 中的同构实现值得说明的是该错误重置机制并非 Preact 独有。在 React 生态中packages/react-query/src/QueryErrorResetBoundary.tsx 实现了完全同构的一套类型与组件QueryErrorResetFunction () void第 5 行、createValue闭包第 18-40 行、useQueryErrorResetBoundary与QueryErrorResetBoundary第 76-145 行两者共享同样的状态机设计只是分别基于preact/hooks与react的 Context 原语。若你需要在 React 与 Preact 之间移植错误恢复代码这套 API 的调用语义可以保持一致。7. 关键要点速览QueryErrorResetFunction仅是一个() void类型别名定义并导出自 packages/preact-query/src/QueryErrorResetBoundary.tsx是QueryErrorResetBoundaryValue.reset字段的类型。调用reset()只会把闭包内isReset置为true真正的重试决策在后续渲染中由errorBoundaryUtils的判断完成。reset之后必须配合 Preact 错误边界复位重渲染一起使用才能看到Try again → 请求重新发出 → 页面恢复的完整效果。每次渲染周期结束后useEffect会调用clearReset()因此重置状态是一次性的窗口不会无限期阻止错误抛出。所有相关 API 均可从tanstack/preact-query包入口统一导入完整类型与函数清单见 Preact Query API 参考索引。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考