useRouter
Wenn Sie auf das router
-Objekt in einer beliebigen Funktionskomponente Ihrer App zugreifen möchten, können Sie den useRouter
-Hook verwenden. Sehen Sie sich das folgende Beispiel an:
import { useRouter } from 'next/router'
function ActiveLink({ children, href }) {
const router = useRouter()
const style = {
marginRight: 10,
color: router.asPath === href ? 'red' : 'black',
}
const handleClick = (e) => {
e.preventDefault()
router.push(href)
}
return (
<a href={href} onClick={handleClick} style={style}>
{children}
</a>
)
}
export default ActiveLink
useRouter
ist ein React Hook, was bedeutet, dass er nicht mit Klassen verwendet werden kann. Sie können entweder withRouter verwenden oder Ihre Klasse in eine Funktionskomponente einwickeln.
router
-Objekt
Im Folgenden finden Sie die Definition des router
-Objekts, das sowohl von useRouter
als auch von withRouter
zurückgegeben wird:
pathname
:String
- Der Pfad der aktuellen Routendatei, der nach/pages
kommt. Daher sindbasePath
,locale
und der nachgestellte Schrägstrich (trailingSlash: true
) nicht enthalten.query
:Object
- Die Abfragezeichenfolge, die in ein Objekt geparst wurde, einschließlich der Parameter für dynamische Routen. Während des Prerenderings wird es ein leeres Objekt sein, wenn die Seite kein Server-seitiges Rendering (SSR) verwendet. Standardwert ist{}
.asPath
:String
- Der Pfad, wie er im Browser angezeigt wird, einschließlich der Suchparameter und unter Berücksichtigung dertrailingSlash
-Konfiguration.basePath
undlocale
sind nicht enthalten.isFallback
:boolean
- Gibt an, ob sich die aktuelle Seite im Fallback-Modus befindet.basePath
:String
- Der aktive basePath (falls aktiviert).locale
:String
- Die aktive Locale (falls aktiviert).locales
:String[]
- Alle unterstützten Locales (falls aktiviert).defaultLocale
:String
- Die aktuelle Standard-Locale (falls aktiviert).domainLocales
:Array<{domain, defaultLocale, locales}>
- Alle konfigurierten Domain-Locales.isReady
:boolean
- Gibt an, ob die Router-Felder clientseitig aktualisiert und einsatzbereit sind. Sollte nur innerhalb vonuseEffect
-Methoden verwendet werden und nicht für bedingtes Rendering auf dem Server. Siehe verwandte Dokumentation für den Anwendungsfall mit automatisch statisch optimierten Seiten.isPreview
:boolean
- Gibt an, ob sich die Anwendung aktuell im Vorschaumodus (Preview Mode) befindet.
Die Verwendung des
asPath
-Felds kann zu einer Diskrepanz zwischen Client und Server führen, wenn die Seite mit Server-seitigem Rendering oder automatischer statischer Optimierung gerendert wird. Vermeiden Sie die Verwendung vonasPath
, bis dasisReady
-Feldtrue
ist.
Die folgenden Methoden sind im router
-Objekt enthalten:
router.push
Behandelt clientseitige Übergänge. Diese Methode ist nützlich für Fälle, in denen next/link
nicht ausreicht.
router.push(url, as, options)
url
:UrlObject | String
- Die URL, zu der navigiert werden soll (siehe Node.JS URL-Modul-Dokumentation fürUrlObject
-Eigenschaften).as
:UrlObject | String
- Optionaler Dekorator für den Pfad, der in der Browser-URL-Leiste angezeigt wird. Vor Next.js 9.5.3 wurde dies für dynamische Routen verwendet.options
- Optionales Objekt mit den folgenden Konfigurationsoptionen:scroll
- Optionaler Boolean, steuert das Scrollen zum Seitenanfang nach der Navigation. Standardwert isttrue
.shallow
: Aktualisiert den Pfad der aktuellen Seite, ohnegetStaticProps
,getServerSideProps
odergetInitialProps
erneut auszuführen. Standardwert istfalse
.locale
- Optionaler String, gibt die Locale der neuen Seite an.
Sie müssen
router.push
nicht für externe URLs verwenden. window.location ist dafür besser geeignet.
Navigation zu pages/about.js
, einer vordefinierten Route:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.push('/about')}>
Klick mich
</button>
)
}
Navigation zu pages/post/[pid].js
, einer dynamischen Route:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.push('/post/abc')}>
Klick mich
</button>
)
}
Weiterleitung des Benutzers zu pages/login.js
, nützlich für Seiten hinter einer Authentifizierung:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
// Hier würden Sie den Benutzer abrufen und zurückgeben
const useUser = () => ({ user: null, loading: false })
export default function Page() {
const { user, loading } = useUser()
const router = useRouter()
useEffect(() => {
if (!(user || loading)) {
router.push('/login')
}
}, [user, loading])
return <p>Weiterleiten...</p>
}
Zurücksetzen des Zustands nach der Navigation
Beim Navigieren zur gleichen Seite in Next.js wird der Seitenzustand standardmäßig nicht zurückgesetzt, da React die Komponente nicht aushängt, es sei denn, die übergeordnete Komponente hat sich geändert.
import Link from 'next/link'
import { useState } from 'react'
import { useRouter } from 'next/router'
export default function Page(props) {
const router = useRouter()
const [count, setCount] = useState(0)
return (
<div>
<h1>Seite: {router.query.slug}</h1>
<p>Zähler: {count}</p>
<button onClick={() => setCount(count + 1)}>Zähler erhöhen</button>
<Link href="/one">eins</Link> <Link href="/two">zwei</Link>
</div>
)
}
Im obigen Beispiel wird beim Navigieren zwischen /one
und /two
der Zähler nicht zurückgesetzt. Der useState
-Wert bleibt zwischen den Renderings erhalten, da die übergeordnete React-Komponente Page
gleich bleibt.
Wenn Sie dieses Verhalten nicht wünschen, haben Sie mehrere Möglichkeiten:
-
Manuelles Aktualisieren jedes Zustands mit
useEffect
. Im obigen Beispiel könnte das so aussehen:useEffect(() => { setCount(0) }, [router.query.slug])
-
Verwenden Sie einen React
key
, um React mitzuteilen, dass die Komponente neu eingehängt werden soll. Um dies für alle Seiten zu tun, können Sie eine benutzerdefinierte App verwenden:pages/_app.js import { useRouter } from 'next/router' export default function MyApp({ Component, pageProps }) { const router = useRouter() return <Component key={router.asPath} {...pageProps} /> }
Mit URL-Objekt
Sie können ein URL-Objekt auf die gleiche Weise verwenden wie bei next/link
. Funktioniert für beide Parameter url
und as
:
import { useRouter } from 'next/router'
export default function ReadMore({ post }) {
const router = useRouter()
return (
<button
type="button"
onClick={() => {
router.push({
pathname: '/post/[pid]',
query: { pid: post.id },
})
}}
>
Klicken Sie hier, um mehr zu lesen
</button>
)
}
router.replace
Ähnlich wie die replace
-Eigenschaft in next/link
, verhindert router.replace
, dass ein neuer URL-Eintrag in den history
-Stack hinzugefügt wird.
router.replace(url, as, options)
- Die API für
router.replace
ist identisch mit der API fürrouter.push
.
Sehen Sie sich das folgende Beispiel an:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.replace('/home')}>
Klick mich
</button>
)
}
router.prefetch
Seiten vorab laden für schnellere clientseitige Übergänge. Diese Methode ist nur für Navigationen ohne next/link
nützlich, da next/link
Seiten automatisch vorab lädt.
Dies ist eine Funktion nur für die Produktion. Next.js lädt Seiten im Entwicklungsmodus nicht vorab.
router.prefetch(url, as, options)
url
- Die URL, die vorab geladen werden soll, einschließlich expliziter Routen (z.B./dashboard
) und dynamischer Routen (z.B./product/[id]
).as
- Optionaler Dekorator fürurl
. Vor Next.js 9.5.3 wurde dies verwendet, um dynamische Routen vorab zu laden.options
- Optionales Objekt mit den folgenden erlaubten Feldern:locale
- Ermöglicht die Angabe einer anderen Locale als der aktiven. Wennfalse
, mussurl
die Locale enthalten, da die aktive Locale nicht verwendet wird.
Angenommen, Sie haben eine Login-Seite, und nach dem Login leiten Sie den Benutzer zum Dashboard weiter. Für diesen Fall können wir das Dashboard vorab laden, um einen schnelleren Übergang zu ermöglichen, wie im folgenden Beispiel:
import { useCallback, useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Login() {
const router = useRouter()
const handleSubmit = useCallback((e) => {
e.preventDefault()
fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
/* Formulardaten */
}),
}).then((res) => {
// Führen Sie einen schnellen clientseitigen Übergang zur bereits vorab geladenen Dashboard-Seite durch
if (res.ok) router.push('/dashboard')
})
}, [])
useEffect(() => {
// Dashboard-Seite vorab laden
router.prefetch('/dashboard')
}, [router])
return (
<form onSubmit={handleSubmit}>
{/* Formularfelder */}
<button type="submit">Login</button>
</form>
)
}
router.beforePopState
In einigen Fällen (z.B. bei Verwendung eines Custom Servers) möchten Sie möglicherweise auf popstate hören und etwas tun, bevor der Router darauf reagiert.
router.beforePopState(cb)
cb
- Die Funktion, die bei eingehendenpopstate
-Ereignissen ausgeführt werden soll. Die Funktion erhält den Zustand des Ereignisses als Objekt mit den folgenden Eigenschaften:url
:String
- Die Route für den neuen Zustand. Dies ist normalerweise der Name einerpage
.as
:String
- Die URL, die im Browser angezeigt wird.options
:Object
- Zusätzliche Optionen, die von router.push gesendet werden.
Wenn cb
false
zurückgibt, wird der Next.js-Router popstate
nicht behandeln, und Sie sind dafür verantwortlich, es in diesem Fall zu behandeln. Siehe Deaktivieren des Dateisystem-Routings.
Sie können beforePopState
verwenden, um die Anfrage zu manipulieren oder ein SSR-Refresh zu erzwingen, wie im folgenden Beispiel:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
useEffect(() => {
router.beforePopState(({ url, as, options }) => {
// Ich möchte nur diese beiden Routen zulassen!
if (as !== '/' && as !== '/other') {
// Lassen Sie SSR ungültige Routen als 404 rendern.
window.location.href = as
return false
}
return true
})
}, [router])
return <p>Willkommen auf der Seite</p>
}
router.back
Navigieren Sie in der Historie zurück. Entspricht dem Klicken auf die Zurück-Schaltfläche des Browsers. Führt window.history.back()
aus.
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.back()}>
Klicken Sie hier, um zurückzugehen
</button>
)
}
router.reload
Laden Sie die aktuelle URL neu. Entspricht dem Klicken auf die Aktualisieren-Schaltfläche des Browsers. Führt window.location.reload()
aus.
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.reload()}>
Klicken Sie hier, um neu zu laden
</button>
)
}
router.events
Sie können verschiedene Ereignisse im Next.js-Router abhören. Hier ist eine Liste der unterstützten Ereignisse:
routeChangeStart(url, { shallow })
- Wird ausgelöst, wenn eine Route beginnt, sich zu ändern.routeChangeComplete(url, { shallow })
- Wird ausgelöst, wenn eine Route vollständig geändert wurde.routeChangeError(err, url, { shallow })
- Wird ausgelöst, wenn ein Fehler beim Ändern der Routen auftritt oder ein Routenladen abgebrochen wird.err.cancelled
- Gibt an, ob die Navigation abgebrochen wurde.
beforeHistoryChange(url, { shallow })
- Wird ausgelöst, bevor die Browser-Historie geändert wird.hashChangeStart(url, { shallow })
- Wird ausgelöst, wenn sich der Hash ändert, aber nicht die Seite.hashChangeComplete(url, { shallow })
- Wird ausgelöst, wenn sich der Hash geändert hat, aber nicht die Seite.
Wichtig: Hier ist
url
die im Browser angezeigte URL, einschließlich desbasePath
.
Um beispielsweise auf das Router-Ereignis routeChangeStart
zu hören, öffnen oder erstellen Sie pages/_app.js
und abonnieren Sie das Ereignis wie folgt:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
useEffect(() => {
const handleRouteChange = (url, { shallow }) => {
console.log(
`App wechselt zu ${url} ${
shallow ? 'mit' : 'ohne'
} shallow routing`
)
}
router.events.on('routeChangeStart', handleRouteChange)
// Wenn die Komponente ausgehängt wird, abonnieren Sie
// das Ereignis mit der `off`-Methode:
return () => {
router.events.off('routeChangeStart', handleRouteChange)
}
}, [router])
return <Component {...pageProps} />
}
Wir verwenden eine Custom App (
pages/_app.js
) für dieses Beispiel, um das Ereignis zu abonnieren, weil sie bei Seitenwechseln nicht ausgehängt wird. Sie können jedoch Router-Ereignisse in jeder Komponente Ihrer Anwendung abonnieren.
Router-Ereignisse sollten registriert werden, wenn eine Komponente eingehängt wird (useEffect oder componentDidMount / componentWillUnmount) oder imperativ, wenn ein Ereignis eintritt.
Wenn ein Routenladen abgebrochen wird (z.B. durch schnelles Klicken auf zwei Links hintereinander), wird routeChangeError
ausgelöst. Das übergebene err
enthält eine Eigenschaft cancelled
, die auf true
gesetzt ist, wie im folgenden Beispiel:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
useEffect(() => {
const handleRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route zu ${url} wurde abgebrochen!`)
}
}
router.events.on('routeChangeError', handleRouteChangeError)
// Wenn die Komponente ausgehängt wird, abonnieren Sie
// das Ereignis mit der `off`-Methode:
return () => {
router.events.off('routeChangeError', handleRouteChangeError)
}
}, [router])
return <Component {...pageProps} />
}
Der next/compat/router
-Export
Dies ist derselbe useRouter
-Hook, kann jedoch sowohl in app
- als auch pages
-Verzeichnissen verwendet werden.
Er unterscheidet sich von next/router
dadurch, dass er keinen Fehler auslöst, wenn der Pages-Router nicht eingebunden ist, und stattdessen einen Rückgabetyp von NextRouter | null
hat.
Dies ermöglicht Entwicklern, Komponenten so anzupassen, dass sie sowohl in app
als auch pages
funktionieren, während sie zum app
-Router migrieren.
Eine Komponente, die zuvor so aussah:
import { useRouter } from 'next/router'
const MyComponent = () => {
const { isReady, query } = useRouter()
// ...
}
Wird beim Wechsel zu next/compat/router
einen Fehler verursachen, da null
nicht destrukturiert werden kann. Stattdessen können Entwickler neue Hooks nutzen:
import { useEffect } from 'react'
import { useRouter } from 'next/compat/router'
import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
const router = useRouter() // kann null oder eine NextRouter-Instanz sein
const searchParams = useSearchParams()
useEffect(() => {
if (router && !router.isReady) {
return
}
// In `app/` sind searchParams sofort mit Werten verfügbar, in
// `pages/` erst nachdem der Router bereit ist.
const search = searchParams.get('search')
// ...
}, [router, searchParams])
// ...
}
Diese Komponente funktioniert nun in beiden Verzeichnissen (pages
und app
). Wenn die Komponente nicht mehr in pages
verwendet wird, können die Verweise auf den Compat-Router entfernt werden:
import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
const searchParams = useSearchParams()
// Da diese Komponente nur in `app/` verwendet wird, kann der Compat-Router entfernt werden.
const search = searchParams.get('search')
// ...
}
Verwendung von useRouter
außerhalb des Next.js-Kontexts in Pages
Ein spezieller Anwendungsfall ist das Rendern von Komponenten außerhalb eines Next.js-Anwendungskontexts, z.B. innerhalb von getServerSideProps
im pages
-Verzeichnis. Hier kann der Compat-Router verwendet werden, um Fehler zu vermeiden:
import { renderToString } from 'react-dom/server'
import { useRouter } from 'next/compat/router'
const MyComponent = () => {
const router = useRouter() // kann null oder eine NextRouter-Instanz sein
// ...
}
export async function getServerSideProps() {
const renderedComponent = renderToString(<MyComponent />)
return {
props: {
renderedComponent,
},
}
}
Potenzielle ESLint-Fehler
Bestimmte Methoden des router
-Objekts geben ein Promise zurück. Wenn die ESLint-Regel no-floating-promises aktiviert ist, sollte sie entweder global oder für die betroffene Zeile deaktiviert werden.
Falls diese Regel benötigt wird, sollte das Promise entweder mit void
ignoriert werden – oder eine async
-Funktion verwendet werden, die das Promise mit await
behandelt und dann der Funktionsaufruf mit void
ignoriert wird. Dies gilt nicht, wenn die Methode innerhalb eines onClick
-Handlers aufgerufen wird.
Betroffene Methoden sind:
router.push
router.replace
router.prefetch
Mögliche Lösungen
import { useEffect } from 'react'
import { useRouter } from 'next/router'
// Hier würde der Benutzer abgefragt und zurückgegeben werden
const useUser = () => ({ user: null, loading: false })
export default function Page() {
const { user, loading } = useUser()
const router = useRouter()
useEffect(() => {
// Linting für die nächste Zeile deaktivieren - Dies ist die sauberste Lösung
// eslint-disable-next-line no-floating-promises
router.push('/login')
// Promise von router.push mit void ignorieren
if (!(user || loading)) {
void router.push('/login')
}
// oder async-Funktion verwenden, Promise mit await behandeln, dann Funktionsaufruf mit void ignorieren
async function handleRouteChange() {
if (!(user || loading)) {
await router.push('/login')
}
}
void handleRouteChange()
}, [user, loading])
return <p>Weiterleiten...</p>
}
withRouter
Falls useRouter
nicht die beste Option ist, kann withRouter
dasselbe router
-Objekt zu jeder Komponente hinzufügen.
Verwendung
import { withRouter } from 'next/router'
function Page({ router }) {
return <p>{router.pathname}</p>
}
export default withRouter(Page)
TypeScript
Für Klassenkomponenten mit withRouter
muss die Komponente eine router-Prop akzeptieren:
import React from 'react'
import { withRouter, NextRouter } from 'next/router'
interface WithRouterProps {
router: NextRouter
}
interface MyComponentProps extends WithRouterProps {}
class MyComponent extends React.Component<MyComponentProps> {
render() {
return <p>{this.props.router.pathname}</p>
}
}
export default withRouter(MyComponent)