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。 |