Series: TanStack Router Lesson 54

Route masking — URL'ni o‘zgartirmasdan boshqa route ko‘rinishini ko‘rsatish

TanStack Router'da Route Masking: Instagram/Pinterest uslubidagi modal navigatsiya, mask prop, unmaskOnReload va React Router bilan taqqos.

54-dars

Route masking — URL'ni o‘zgartirmasdan boshqa route ko‘rinishini ko‘rsatish

Instagram, Twitter (X) yoki Pinterest kabi mashhur ilovalardan foydalanganingizda ajoyib bir effektga duch kelasiz: Siz lentada (feed) turib biror rasmni bossangiz, orqa fondagi sahifa o‘z joyida qoladi va uning ustida Modal oyna ochiladi. Shu bilan bir vaqtda, brauzerning manzil satridagi URL /photo/123 ga o‘zgaradi.

Agar siz modalni yopsangiz — lentadagi o‘rningizga hech qanday qayta yuklanishsiz qaytasiz. Agar ushbu /photo/123 havolasini do‘stingizga yuborsangiz yoki sahifani yangilasangiz (F5), fotosurat alohida to‘laqonli sahifa sifatida ochiladi!

TanStack Router bu murakkab mexanizmni Route Masking texnologiyasi orqali bir necha qatorda oson va deklarativ hal qilib beradi.


1. Hayotiy o‘xshatish: Teatr tomoshasi va Durbin

Tasavvur qiling, siz katta teatr zalida spektakl tomosha qilyapsiz (Galereya / Lenta sahifasi).

Sahnadagi bosh qahramonning yuz ifodasini yaqindan ko‘rish uchun ko‘zingizga durbinni tutasiz (Modal rasm ochildi). Siz teatr zalidan chiqib ketmadingiz, o‘rindiq va atrofingiz o‘z joyida turibdi, faqat ko‘rish maydoningiz qahramonga qaratildi. Durbinni olib qo‘ysangiz — zaldagi tomoshani to‘xtovsiz davom ettirasiz.

Agar kimgadir: "Men spektaklning 15-qahramonini tomosha qilyapman" deb manzil yuborsangiz (Kanonik havola), do‘stingiz teatr eshigidan to‘g‘ri o‘sha spektakl zaliga kirib keladi.


2. Route Masking qanday ishlaydi?

Route Masking — bu brauzer xotirasidagi ichki marshrut holati bilan manzil satrida ko‘rinib turgan tashqi URLni bir-biridan ajratish (maskalash) usulidir:

// src/routes/gallery.tsx
import { createFileRoute, Link, Outlet } from '@tanstack/react-router'

interface Photo {
  id: string
  title: string
  url: string
}

export const Route = createFileRoute('/gallery')({
  loader: async () => fetchPhotosApi(),
  component: GalleryPage,
})

function GalleryPage() {
  const photos = Route.useLoaderData()

  return (
    <div className="gallery-page">
      <h1>Foto Galereya</h1>

      <div className="photos-grid">
        {photos.map((photo: Photo) => (
          <div key={photo.id} className="photo-card">
            {/* 
              to: modal ichida ochiladigan ichki route (/gallery/photo/1)
              mask: brauzer manzil satrida ko'rinadigan chiroyli manzil (/photos/1)
            */}
            <Link
              to="/gallery/photo/$photoId"
              params={{ photoId: photo.id }}
              mask={{
                to: '/photos/$photoId',
                params: { photoId: photo.id },
                unmaskOnReload: true,
              }}
            >
              <img src={photo.url} alt={photo.title} />
              <p>{photo.title}</p>
            </Link>
          </div>
        ))}
      </div>

      {/* Modal oyna shu Outlet ichida chiziladi */}
      <Outlet />
    </div>
  )
}

async function fetchPhotosApi(): Promise<Photo[]> {
  return [
    { id: '1', title: 'Tog‘ manzarasi', url: '/mountain.jpg' },
    { id: '2', title: 'Dengiz sohili', url: '/beach.jpg' },
  ]
}

3. Modal Route va Mustaqil Route farqi

Loyihangizda ikkita alohida route fayli yaratiladi:

  1. src/routes/gallery/photo/$photoId.tsx (Modal ko‘rinishi): Galereya ichida ochiladi, qora shaffof fon (backdrop) va yopish tugmasiga ega bo‘ladi.
  2. src/routes/photos/$photoId.tsx (Mustaqil sahifa): Foydalanuvchi havolani to‘g‘ridan-to‘g‘ri ochganda yoki F5 bosganda chiziladigan to‘liq sahifa.
// src/routes/gallery/photo/$photoId.tsx (Modal komponenti)
import { createFileRoute, useNavigate } from '@tanstack/react-router'

export const Route = createFileRoute('/gallery/photo/$photoId')({
  component: PhotoModal,
})

function PhotoModal() {
  const { photoId } = Route.useParams()
  const navigate = useNavigate()

  return (
    <div className="modal-backdrop" onClick={() => navigate({ to: '/gallery' })}>
      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
        <h3>Rasm tafsilotlari (ID: {photoId})</h3>
        <p>Orqa fonda galereya o'z joyida turibdi!</p>
        <button onClick={() => navigate({ to: '/gallery' })}>Yopish (Esc)</button>
      </div>
    </div>
  )
}

4. unmaskOnReload parametri nima qiladi?

mask konfiguratsiyasidagi eng qimmatli xossalardan biri — bu unmaskOnReload:

mask={{
  to: '/photos/$photoId',
  params: { photoId: '1' },
  unmaskOnReload: true, // Standart holatda true
}}
  • unmaskOnReload: true: Agar foydalanuvchi sahifani yangilasa (F5), router maskani yechadi va mustaqil /photos/1 sahifasini to‘liq render qiladi.
  • unmaskOnReload: false: Sahifa yangilanganda ham maskalangan holat saqlanib qoladi.

5. Route Masking oqimi (Mermaid Diagram)

flowchart TD
    subgraph ScenarioA["1-holat: Sayt ichida link bosildi (In-App Click)"]
        Click["Foydalanuvchi galereyada rasmni bosdi"] --> ModalRoute["Ichki navigatsiya: /gallery/photo/15"]
        ModalRoute --> RenderModal["Galereya ustida Modal oyna ochildi"]
        RenderModal --> AddressBar["Brauzer manzil satriga /photos/15 yozildi (Mask)"]
    end

    subgraph ScenarioB["2-holat: Do'stiga ulashildi yoki F5 bosildi (Direct URL)"]
        DirectURL["Foydalanuvchi to'g'ridan-to'g'ri /photos/15 ga kirdi"] --> Standalone["Mustaqil /photos/$photoId sahifasi ochildi"]
        Standalone --> FullPage["To'liq sahifa ko'rinishi (Modal emas!)"]
    end

6. React Router va TanStack Router taqqosi

Xususiyat React Router TanStack Router (mask)
Modal navigatsiyasi ⚠️ location.state={{ backgroundLocation }} orqali qo‘lda murakkab kod ✅ mask={{ to: '...' }} deklarativ xossasi
Type Safety ❌ state tiplanmagan bo‘lib qoladi ✅ Maskalangan URL ham, ichki URL ham 100% tiplangan
Sahifa yangilanishini boshqarish F5 bosilganda xatoliklar yuz berishi oson unmaskOnReload orqali to‘liq nazorat qilinadi
Kesh bilan integratsiya Qo‘lda kesh boshqarish kerak Router kesh tizimiga to‘liq bog‘langan

Xulosa

  • Route Masking — joriy sahifa holatini (masalan, galereya lentasini) yo‘qotmasdan modal ochish va brauzer satrida kanonik URL ko‘rsatish usulidir.
  • <Link mask={{ ... }}> yoki navigate({ mask: { ... } }) orqali manzil satri osongina niqoblanadi.
  • unmaskOnReload: true sahifa qayta yangilanganda (F5) yoki tashqaridan to‘g‘ridan-to‘g‘ri kirilganda to‘liq mustaqil sahifaga aylanishini kafolatlaydi.
  • Bu yondashuv Instagram, Twitter va Pinterest darajasidagi mukammal UX yaratish imkonini beradi.