导航阻止 | TanStack Router React 文档

导航阻止是一种阻止导航发生的方法。当用户尝试导航时，通常会出现以下情况：

有未保存的更改
正在填写表单
正在进行支付

在这些情况下，应向用户显示提示或自定义 UI，以确认他们是否要离开。

如果用户确认，导航将正常继续
如果用户取消，所有待处理的导航都将被阻止

导航阻止会为整个底层历史 API 添加一层或多层“阻止器”。如果存在任何阻止器，导航将通过以下方式之一暂停：

自定义 UI
- 如果导航是由我们通过路由级别控制的某些事件触发的，我们可以允许您执行任何任务或向用户显示您想要的任何 UI 来确认操作。每个阻止器的 blocker 函数将异步且按顺序执行。如果任何阻止函数解析或返回 true，则导航将被允许，所有其他阻止器将继续执行相同的操作，直到所有阻止器都被允许继续。如果任何单个阻止器解析或返回 false，则导航将被取消，其余的 blocker 函数将被忽略。
onbeforeunload 事件
- 对于我们无法直接控制的页面事件，我们依赖于浏览器的 onbeforeunload 事件。如果用户尝试关闭选项卡或窗口、刷新或以任何方式“卸载”页面资源，将显示浏览器的通用“您确定要离开吗？”对话框。如果用户确认，所有阻止器将被绕过，页面将卸载。如果用户取消，卸载将被取消，页面将保持原样。

有两种方法可以使用导航阻止

基于 Hook/逻辑的阻止
基于组件的阻止

基于 Hook/逻辑的阻止

假设我们希望在表单脏时阻止导航。我们可以通过使用 useBlocker 钩子来实现

tsx

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    shouldBlockFn: () => {
      if (!formIsDirty) return false

      const shouldLeave = confirm('Are you sure you want to leave?')
      return !shouldLeave
    },
  })

  // ...
}

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    shouldBlockFn: () => {
      if (!formIsDirty) return false

      const shouldLeave = confirm('Are you sure you want to leave?')
      return !shouldLeave
    },
  })

  // ...
}

shouldBlockFn 为您提供对 current 和 next 位置的类型安全访问

tsx

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  // always block going from /foo to /bar/123?hello=world
  const { proceed, reset, status } = useBlocker({
    shouldBlockFn: ({ current, next }) => {
      return (
        current.routeId === '/foo' &&
        next.fullPath === '/bar/$id' &&
        next.params.id === 123 &&
        next.search.hello === 'world'
      )
    },
    withResolver: true,
  })

  // ...
}

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  // always block going from /foo to /bar/123?hello=world
  const { proceed, reset, status } = useBlocker({
    shouldBlockFn: ({ current, next }) => {
      return (
        current.routeId === '/foo' &&
        next.fullPath === '/bar/$id' &&
        next.params.id === 123 &&
        next.search.hello === 'world'
      )
    },
    withResolver: true,
  })

  // ...
}

请注意，即使 shouldBlockFn 返回 false，浏览器在页面重新加载或选项卡关闭时仍可能触发 beforeunload 事件。要控制这一点，您可以使用 enableBeforeUnload 选项有条件地注册 beforeunload 处理程序

tsx

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    {/* ... */}
    enableBeforeUnload: formIsDirty, // or () => formIsDirty
  })

  // ...
}

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    {/* ... */}
    enableBeforeUnload: formIsDirty, // or () => formIsDirty
  })

  // ...
}

您可以在 API 参考中找到有关 useBlocker 钩子的更多信息。

基于组件的阻止

除了基于逻辑/钩子的阻止，您还可以使用 Block 组件来实现类似的结果

tsx

import { Block } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  return (
    <Block
      shouldBlockFn={() => {
        if (!formIsDirty) return false

        const shouldLeave = confirm('Are you sure you want to leave?')
        return !shouldLeave
      }}
      enableBeforeUnload={formIsDirty}
    />
  )

  // OR

  return (
    <Block
      shouldBlockFn={() => formIsDirty}
      enableBeforeUnload={formIsDirty}
      withResolver
    >
      {({ status, proceed, reset }) => <>{/* ... */}</>}
    </Block>
  )
}

import { Block } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  return (
    <Block
      shouldBlockFn={() => {
        if (!formIsDirty) return false

        const shouldLeave = confirm('Are you sure you want to leave?')
        return !shouldLeave
      }}
      enableBeforeUnload={formIsDirty}
    />
  )

  // OR

  return (
    <Block
      shouldBlockFn={() => formIsDirty}
      enableBeforeUnload={formIsDirty}
      withResolver
    >
      {({ status, proceed, reset }) => <>{/* ... */}</>}
    </Block>
  )
}

我如何显示自定义 UI？

在大多数情况下，在钩子中使用 shouldBlockFn 函数并设置 withResolver: false 来调用 window.confirm 就足够了，因为它会清楚地向用户显示导航正在被阻止，并根据他们的响应解决阻止问题。

然而，在某些情况下，您可能希望显示一个自定义 UI，它有意地不那么具有干扰性，并且与您的应用程序设计更加集成。

注意：如果 withResolver 为 true，则 shouldBlockFn 的返回值不会解决阻止问题。

使用解析器的基于 Hook/逻辑的自定义 UI

tsx

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  const { proceed, reset, status } = useBlocker({
    shouldBlockFn: () => formIsDirty,
    withResolver: true,
  })

  // ...

  return (
    <>
      {/* ... */}
      {status === 'blocked' && (
        <div>
          <p>Are you sure you want to leave?</p>
          <button onClick={proceed}>Yes</button>
          <button onClick={reset}>No</button>
        </div>
      )}
    </>
}

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  const { proceed, reset, status } = useBlocker({
    shouldBlockFn: () => formIsDirty,
    withResolver: true,
  })

  // ...

  return (
    <>
      {/* ... */}
      {status === 'blocked' && (
        <div>
          <p>Are you sure you want to leave?</p>
          <button onClick={proceed}>Yes</button>
          <button onClick={reset}>No</button>
        </div>
      )}
    </>
}

不使用解析器的基于 Hook/逻辑的自定义 UI

tsx

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    shouldBlockFn: () => {
      if (!formIsDirty) {
        return false
      }

      const shouldBlock = new Promise<boolean>((resolve) => {
        // Using a modal manager of your choice
        modals.open({
          title: 'Are you sure you want to leave?',
          children: (
            <SaveBlocker
              confirm={() => {
                modals.closeAll()
                resolve(false)
              }}
              reject={() => {
                modals.closeAll()
                resolve(true)
              }}
            />
          ),
          onClose: () => resolve(true),
        })
      })
      return shouldBlock
    },
  })

  // ...
}

import { useBlocker } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  useBlocker({
    shouldBlockFn: () => {
      if (!formIsDirty) {
        return false
      }

      const shouldBlock = new Promise<boolean>((resolve) => {
        // Using a modal manager of your choice
        modals.open({
          title: 'Are you sure you want to leave?',
          children: (
            <SaveBlocker
              confirm={() => {
                modals.closeAll()
                resolve(false)
              }}
              reject={() => {
                modals.closeAll()
                resolve(true)
              }}
            />
          ),
          onClose: () => resolve(true),
        })
      })
      return shouldBlock
    },
  })

  // ...
}

基于组件的自定义 UI

与钩子类似，Block 组件返回与渲染属性相同的状态和函数

tsx

import { Block } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  return (
    <Block shouldBlockFn={() => formIsDirty} withResolver>
      {({ status, proceed, reset }) => (
        <>
          {/* ... */}
          {status === 'blocked' && (
            <div>
              <p>Are you sure you want to leave?</p>
              <button onClick={proceed}>Yes</button>
              <button onClick={reset}>No</button>
            </div>
          )}
        </>
      )}
    </Block>
  )
}

import { Block } from '@tanstack/react-router'

function MyComponent() {
  const [formIsDirty, setFormIsDirty] = useState(false)

  return (
    <Block shouldBlockFn={() => formIsDirty} withResolver>
      {({ status, proceed, reset }) => (
        <>
          {/* ... */}
          {status === 'blocked' && (
            <div>
              <p>Are you sure you want to leave?</p>
              <button onClick={proceed}>Yes</button>
              <button onClick={reset}>No</button>
            </div>
          )}
        </>
      )}
    </Block>
  )
}

导航阻塞

导航阻止是如何工作的？

我该如何使用导航阻止？