Routenmaskierung

Routenmaskierung ist eine Methode, um die tatsächliche URL einer Route zu maskieren, die im Browserverlauf und in der Adressleiste gespeichert wird. Dies ist nützlich für Szenarien, in denen Sie eine andere URL anzeigen möchten als die, zu der tatsächlich navigiert wird, und dann zur angezeigten URL zurückfallen, wenn sie geteilt wird und (optional) wenn die Seite neu geladen wird. Hier sind einige Beispiele

• Navigation zu einer Modal-Route wie /photo/5/modal, aber Maskierung der tatsächlichen URL als /photos/5
• Navigation zu einer Modal-Route wie /post/5/comments, aber Maskierung der tatsächlichen URL als /posts/5
• Navigation zu einer Route mit dem Suchparameter ?showLogin=true, aber Maskierung der URL, sodass sie den Suchparameter *nicht* enthält
• Navigation zu einer Route mit dem Suchparameter ?modal=settings, aber Maskierung der URL als `/settings`

Jedes dieser Szenarien kann mit Routenmaskierung erreicht werden und sogar erweitert werden, um fortgeschrittenere Muster wie parallele Routen zu unterstützen.

Routenmaskierung nutzt die location.state API, um den gewünschten Laufzeit-Standort innerhalb des Standorts zu speichern, der in die URL geschrieben wird. Sie speichert diesen Laufzeit-Standort unter der __tempLocation-Eigenschaft des Status

const location = {
  pathname: '/photos/5',
  search: '',
  hash: '',
  state: {
    key: 'wesdfs',
    __tempKey: 'sadfasd',
    __tempLocation: {
      pathname: '/photo/5/modal',
      search: '',
      hash: '',
      state: {},
    },
  },
}

const location = {
  pathname: '/photos/5',
  search: '',
  hash: '',
  state: {
    key: 'wesdfs',
    __tempKey: 'sadfasd',
    __tempLocation: {
      pathname: '/photo/5/modal',
      search: '',
      hash: '',
      state: {},
    },
  },
}

Wenn der Router einen Standort aus dem Verlauf mit der Eigenschaft location.state.__tempLocation analysiert, verwendet er diesen Standort anstelle desjenigen, der aus der URL analysiert wurde. Dies ermöglicht es Ihnen, zu einer Route wie /photos/5 zu navigieren und den Router tatsächlich zu /photo/5/modal navigieren zu lassen. Wenn dies geschieht, wird der Verlauf-Standort zurück in die Eigenschaft location.maskedLocation gespeichert, nur für den Fall, dass wir wissen müssen, was die **tatsächliche URL** ist. Ein Beispiel dafür ist in den Devtools, wo wir erkennen, ob eine Route maskiert ist und die tatsächliche URL anstelle der maskierten anzeigen!

Denken Sie daran, dass Sie sich um nichts davon kümmern müssen. Es wird alles automatisch im Hintergrund für Sie gehandhabt!

Routenmaskierung ist eine einfache API, die auf 2 Arten verwendet werden kann

• Imperativ über die mask-Option, die für die <Link>- und navigate()-APIs verfügbar ist
• Deklarativ über die routeMasks-Option des Routers

Bei der Verwendung einer der Routenmaskierungs-APIs akzeptiert die mask-Option dasselbe Navigationsobjekt, das die <Link>- und navigate()-APIs akzeptieren. Das bedeutet, Sie können dieselben to-, replace-, state- und search-Optionen verwenden, mit denen Sie bereits vertraut sind. Der einzige Unterschied besteht darin, dass die mask-Option verwendet wird, um die URL der zu navigierenden Route zu maskieren.

🧠 Die mask-Option ist auch **typsicher**! Das bedeutet, wenn Sie TypeScript verwenden, erhalten Sie Typfehler, wenn Sie versuchen, ein ungültiges Navigationsobjekt an die mask-Option zu übergeben. Booyah!

Die <Link>- und navigate()-APIs akzeptieren beide eine mask-Option, mit der die URL der zu navigierenden Route maskiert werden kann. Hier ist ein Beispiel für die Verwendung mit der <Link>-Komponente

<Link
  to="/photos/$photoId/modal"
  params={{ photoId: 5 }}
  mask={{
    to: '/photos/$photoId',
    params: {
      photoId: 5,
    },
  }}
>
  Open Photo
</Link>

<Link
  to="/photos/$photoId/modal"
  params={{ photoId: 5 }}
  mask={{
    to: '/photos/$photoId',
    params: {
      photoId: 5,
    },
  }}
>
  Open Photo
</Link>

Und hier ist ein Beispiel für die Verwendung mit der navigate()-API

const navigate = useNavigate()

function onOpenPhoto() {
  navigate({
    to: '/photos/$photoId/modal',
    params: { photoId: 5 },
    mask: {
      to: '/photos/$photoId',
      params: {
        photoId: 5,
      },
    },
  })
}

const navigate = useNavigate()

function onOpenPhoto() {
  navigate({
    to: '/photos/$photoId/modal',
    params: { photoId: 5 },
    mask: {
      to: '/photos/$photoId',
      params: {
        photoId: 5,
      },
    },
  })
}

Zusätzlich zur imperativen API können Sie auch die routeMasks-Option des Routers verwenden, um Routen deklarativ zu maskieren. Anstatt die mask-Option an jeden <Link>- oder navigate()-Aufruf übergeben zu müssen, können Sie stattdessen eine Routenmaske auf dem Router erstellen, um Routen zu maskieren, die einem bestimmten Muster entsprechen. Hier ist ein Beispiel für dieselbe Routenmaske von oben, aber stattdessen mit der routeMasks-Option

// Verwenden Sie Folgendes für das folgende Beispiel

import { createRouteMask } from '@tanstack/react-router'

const photoModalToPhotoMask = createRouteMask({
  routeTree,
  from: '/photos/$photoId/modal',
  to: '/photos/$photoId',
  params: (prev) => ({
    photoId: prev.photoId,
  }),
})

const router = createRouter({
  routeTree,
  routeMasks: [photoModalToPhotoMask],
})

import { createRouteMask } from '@tanstack/react-router'

const photoModalToPhotoMask = createRouteMask({
  routeTree,
  from: '/photos/$photoId/modal',
  to: '/photos/$photoId',
  params: (prev) => ({
    photoId: prev.photoId,
  }),
})

const router = createRouter({
  routeTree,
  routeMasks: [photoModalToPhotoMask],
})

Beim Erstellen einer Routenmaske müssen Sie 1 Argument mit mindestens Folgendem übergeben

• routeTree - Der Routenbaum, auf den die Routenmaske angewendet wird
• from - Die Routen-ID, auf die die Routenmaske angewendet wird
• ...navigateOptions - Die Standardoptionen to, search, params, replace, etc., die die <Link>- und navigate()-APIs akzeptieren

🧠 Die Option createRouteMask ist ebenfalls **typsicher**! Das bedeutet, wenn Sie TypeScript verwenden, erhalten Sie Typfehler, wenn Sie versuchen, eine ungültige Routenmaske an die routeMasks-Option zu übergeben.

URLs werden automatisch aufgehoben, wenn sie geteilt werden, da die Maskierungsdaten der URL nicht mehr verfügbar sind, sobald eine URL aus dem lokalen Verlaufsstapel Ihres Browsers entfernt wird. Im Grunde gehen die Maskierungsdaten verloren, sobald Sie eine URL aus Ihrem Verlauf kopieren und einfügen ... das ist schließlich der Sinn der Maskierung einer URL!

**Standardmäßig werden URLs beim lokalen Neuladen der Seite nicht aufgehoben**. Maskierungsdaten werden in der location.state-Eigenschaft des Verlauf-Standorts gespeichert. Solange der Verlauf-Standort noch im Speicher Ihres Verlaufsstapels vorhanden ist, sind die Maskierungsdaten verfügbar und die URL wird weiterhin maskiert.

Wie oben erwähnt, werden URLs standardmäßig beim Neuladen der Seite nicht aufgehoben.

Wenn Sie eine URL lokal beim Neuladen der Seite aufheben möchten, haben Sie 3 Optionen, die sich jeweils gegenseitig überschreiben, wenn sie übergeben werden

• Setzen Sie die Standardoption unmaskOnReload des Routers auf true
• Geben Sie die Option unmaskOnReload: true aus der Maskierungsfunktion zurück, wenn Sie eine Routenmaske mit createRouteMask() erstellen
• Übergeben Sie die Option unmaskOnReload: true an die <Link>-Komponente oder die navigate()-API