NNext.js 中文网 GitHub

useOffline

experimental

useOffline hook 的 API 参考。

useOffline hook 返回一个布尔值,指示应用当前是否离线。使用它可以渲染感知连接状态的 UI,例如当用户断开网络连接时显示横幅,或感知离线的 Suspense 回退。

该 hook 是一项更大功能的一部分。启用 experimental.useOffline 配置选项会开启离线连接检测,以及对被阻塞的导航、预取和 Server Action 请求的自动重试,并公开此 hook 以便 Client Components 读取状态。

不使用该标志时,此 hook 始终返回 false。

next.config.js
module.exports = {
  experimental: {
    useOffline: true,
  },
}
app/offline-status.tsx
'use client'

import { useOffline } from 'next/offline'

export function OfflineStatus() {
  const isOffline = useOffline()
  return <div>{isOffline ? 'Offline' : 'Online'}</div>
}
app/offline-status.js
'use client'

import { useOffline } from 'next/offline'

export function OfflineStatus() {
  const isOffline = useOffline()
  return <div>{isOffline ? 'Offline' : 'Online'}</div>
}

有关如何检测连接状态和重试请求的详细信息,请参阅重试的工作方式。

参数#

tsx
const isOffline = useOffline()

useOffline 不接受任何参数。

返回值#

useOffline 返回一个 boolean:

值含义
true应用处于离线状态。网络请求失败,或浏览器触发了 offline 事件。
false应用处于在线状态,或正在服务端渲染。这也是 hydration 完成前的初始值。

示例#

显示离线横幅#

每当用户断开连接时,渲染一个持续显示的横幅。

app/components/offline-banner.tsx
'use client'

import { useOffline } from 'next/offline'

export function OfflineBanner() {
  const isOffline = useOffline()

  if (!isOffline) {
    return null
  }

  return (
    <div role="status" className="offline-banner">
      You are offline. Some content may be unavailable.
    </div>
  )
}
app/components/offline-banner.js
'use client'

import { useOffline } from 'next/offline'

export function OfflineBanner() {
  const isOffline = useOffline()

  if (!isOffline) {
    return null
  }

  return (
    <div role="status" className="offline-banner">
      You are offline. Some content may be unavailable.
    </div>
  )
}

在根布局中渲染它,使横幅在每个路由上显示:

app/layout.tsx
import { OfflineBanner } from './components/offline-banner'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <OfflineBanner />
        {children}
      </body>
    </html>
  )
}
app/layout.js
import { OfflineBanner } from './components/offline-banner'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <OfflineBanner />
        {children}
      </body>
    </html>
  )
}

感知离线的 Suspense 回退#

当用户在离线状态下导航到某个路由时,预取的静态 shell 会立即渲染,但 <Suspense> 边界后的动态内容会在网络上阻塞。例如,在 loading.tsx 文件中使用 useOffline 来解释内容为何比预期耗时更长。

app/destination/loading.tsx
'use client'

import { useOffline } from 'next/offline'

export default function Loading() {
  const isOffline = useOffline()

  return (
    <div>
      {isOffline ? 'Waiting for connection to load this page...' : 'Loading...'}
    </div>
  )
}
app/destination/loading.js
'use client'

import { useOffline } from 'next/offline'

export default function Loading() {
  const isOffline = useOffline()

  return (
    <div>
      {isOffline ? 'Waiting for connection to load this page...' : 'Loading...'}
    </div>
  )
}

连接恢复后,Next.js 会重试被阻塞的请求,动态内容会自动流式传入。

版本历史#

版本变更
v16.x.0引入了 useOffline hook。
Next.js 中文网