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 auf die angezeigte URL zurückgreifen möchten, wenn sie geteilt wird und (optional) wenn die Seite neu geladen wird. Hier sind einige Beispiele

• Navigation zu einer modalen Route wie /photo/5/modal, aber Maskierung der tatsächlichen URL als /photos/5
• Navigation zu einer modalen 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 und sogar erweitert werden, um fortgeschrittenere Muster wie Parallelrouten 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. Es 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 des vom URL analysierten Standorts. Dies ermöglicht es Ihnen, zu einer Route wie /photos/5 zu navigieren und den Router stattdessen 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. Alles wird automatisch für Sie im Hintergrund erledigt!

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

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

Bei Verwendung einer der Routenmaskierungs-APIs akzeptiert die mask-Option dasselbe Navigationsobjekt, das die <Link>- und navigate()-APIs akzeptieren. Das bedeutet, dass Sie dieselben to-, replace-, state- und search-Optionen verwenden können, 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 außerdem **typsicher**! Das bedeutet, dass Sie bei der Verwendung von TypeScript Typfehler erhalten, wenn Sie versuchen, ein ungültiges Navigationsobjekt an die mask-Option zu übergeben. Booyah!

Die <Link>- und navigate()-APIs akzeptieren beide eine mask-Option, die verwendet werden kann, um die URL der zu navigierenden Route zu maskieren. 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 am Router erstellen, um Routen zu maskieren, die einem bestimmten Muster entsprechen. Hier ist ein Beispiel für dieselbe Routenmaske wie oben, aber stattdessen mit der routeMasks-Option.

// Verwenden Sie das Folgende für das Beispiel unten

import { createRouteMask } from '@tanstack/solid-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/solid-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 usw., die die <Link>- und navigate()-APIs akzeptieren.

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

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

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

Wie oben erwähnt, werden URLs beim Neuladen der Seite standardmäßig 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.