TanStackRouter v1
自动
框架
版本
菜单
入门
路由
指南
API
ESLint
路由示例

导航阻止

导航阻止是一种防止导航发生的方式。这在用户尝试导航时通常会发生，当他们：

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

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

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

导航阻止是如何工作的？

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

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

如何使用导航阻止？

有 2 种使用导航阻止的方式：

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

基于 Hook/逻辑的阻止

假设我们想要在表单有未保存更改时阻止导航。我们可以使用 useBlocker hook 来实现：

tsx
import { useBlocker } from '@tanstack/solid-router'

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

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

      const shouldLeave = confirm('您确定要离开吗？')
      return !shouldLeave
    },
  })

  // ...
}

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

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

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

      const shouldLeave = confirm('您确定要离开吗？')
      return !shouldLeave
    },
  })

  // ...
}

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

tsx
import { useBlocker } from '@tanstack/solid-router'

function MyComponent() {
  // 始终阻止从 /foo 到 /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/solid-router'

function MyComponent() {
  // 始终阻止从 /foo 到 /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/solid-router'

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

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

        const shouldLeave = confirm('您确定要离开吗？')
        return !shouldLeave
      }}
    />
  )

  // OR

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

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

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

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

        const shouldLeave = confirm('您确定要离开吗？')
        return !shouldLeave
      }}
    />
  )

  // OR

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

如何显示自定义 UI？

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

但是，在某些情况下，您可能希望显示一个故意较少干扰且与您的应用程序设计更集成的自定义 UI。

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

基于 Hook/逻辑的自定义 UI（带解析器）
tsx
import { useBlocker } from '@tanstack/solid-router'

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

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

  // ...

  return (
    <>
      {/* ... */}
      {status === 'blocked' && (
        <div>
          <p>您确定要离开吗？</p>
          <button onClick={proceed}>是</button>
          <button onClick={reset}>否</button>
        </div>
      )}
    </>
}

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

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

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

  // ...

  return (
    <>
      {/* ... */}
      {status === 'blocked' && (
        <div>
          <p>您确定要离开吗？</p>
          <button onClick={proceed}>是</button>
          <button onClick={reset}>否</button>
        </div>
      )}
    </>
}

基于 Hook/逻辑的自定义 UI（不带解析器）
tsx
import { useBlocker } from '@tanstack/solid-router'

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

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

      const shouldBlock = new Promise<boolean>((resolve) => {
        // 使用您选择的模态框管理器
        modals.open({
          title: '您确定要离开吗？',
          children: (
            <SaveBlocker
              confirm={() => {
                modals.closeAll()
                resolve(false)
              }}
              reject={() => {
                modals.closeAll()
                resolve(true)
              }}
            />
          ),
          onClose: () => resolve(true),
        })
      })
      return shouldBlock
    },
  })

  // ...
}

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

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

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

      const shouldBlock = new Promise<boolean>((resolve) => {
        // 使用您选择的模态框管理器
        modals.open({
          title: '您确定要离开吗？',
          children: (
            <SaveBlocker
              confirm={() => {
                modals.closeAll()
                resolve(false)
              }}
              reject={() => {
                modals.closeAll()
                resolve(true)
              }}
            />
          ),
          onClose: () => resolve(true),
        })
      })
      return shouldBlock
    },
  })

  // ...
}

基于组件的自定义 UI

与 hook 类似，Block 组件返回相同的状态和函数作为渲染属性：

tsx
import { Block } from '@tanstack/solid-router'

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

  return (
    <Block shouldBlockFn={() => formIsDirty()} withResolver>
      {({ status, proceed, reset }) => (
        <>
          {/* ... */}
          {status === 'blocked' && (
            <div>
              <p>您确定要离开吗？</p>
              <button onClick={proceed}>是</button>
              <button onClick={reset}>否</button>
            </div>
          )}
        </>
      )}
    </Block>
  )
}

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

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

  return (
    <Block shouldBlockFn={() => formIsDirty()} withResolver>
      {({ status, proceed, reset }) => (
        <>
          {/* ... */}
          {status === 'blocked' && (
            <div>
              <p>您确定要离开吗？</p>
              <button onClick={proceed}>是</button>
              <button onClick={reset}>否</button>
            </div>
          )}
        </>
      )}
    </Block>
  )
}
在 GitHub 上编辑
路由伪装
自定义搜索参数序列化