TanStack路由 v1
自动
框架
版本
菜单
开始使用
路由
指南
API
ESLint
Router 示例

导航阻塞

导航阻塞是一种阻止导航发生的方式。当用户尝试在以下情况下导航时，这很常见

  • 有未保存的更改
  • 正在填写表单
  • 正在付款

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

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

导航阻塞是如何工作的？

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

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

如何使用导航阻塞？

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

  • 基于 Hook/逻辑的阻塞
  • 基于组件的阻塞

基于 Hook/逻辑的阻塞

假设我们想在表单已更改但未保存时阻止导航。我们可以通过使用 useBlocker hook 来做到这一点

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,
  })

  // ...
}

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

基于组件的阻塞

除了基于逻辑/hook 的阻塞之外，还可以使用 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
      }}
    />
  )

  // OR

  return (
    <Block shouldBlockFn={() => !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
      }}
    />
  )

  // OR

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

如何显示自定义 UI？

在大多数情况下，在 hook 中使用 window.confirm 的 shouldBlockFn 函数和 withResolver: false 就足够了，因为它会清楚地向用户表明导航被阻止，并根据用户的响应解决阻塞。

但是，在某些情况下，您可能希望显示一个自定义 UI，该 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

与 hook 类似，Block 组件返回与渲染 props 相同的状态和函数

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>
  )
}
在 GitHub 上编辑
路由掩码
自定义搜索参数序列化
订阅 Bytes

您的每周 JavaScript 新闻。每周一免费发送给超过 10 万名开发者。

Bytes

无垃圾邮件。随时取消订阅。