Search params arxitekturasi — Query parametrlarni JSON-first boshqarish
TanStack Router'da Search Params: JSON-first yondashuv, Zod orqali validatsiya, validateSearch, Route.useSearch() va React Router bilan taqqoslash.
27-dars
Search params arxitekturasi — Query parametrlarni JSON-first boshqarish
Tasavvur qiling, siz aeroport bojxona nazoratidan o‘tyapsiz. Agar deklaratsiya qog‘oziga barcha ma'lumotlarni tartibsiz bitta qatorda oddiy matn qilib yozsangiz, bojxona xodimi har bir so‘zni qo‘lda o‘qib, bu raqammi, ismmi yoki buyummi deb tekshirishga majbur bo‘ladi. Ammo zamonaviy elektron nazorat punktida siz raqamli anketani to‘ldirasiz: pul miqdori (raqam — number), xizmat safari ekanligi (ha/yo‘q — boolean), hamrohlar ro‘yxati (massiv — array). Tizim skaneri bu ma'lumotlarni qat'iy tekshiruvdan o‘tkazib, darhol to‘g‘ri formatda bazaga kiritadi.
Veb-ilovalarda URL query parametrlari (?page=2&filter=active&sort=desc) an'anaviy ravishda doimo oddiy quruq matn (string) bo‘lib kelgan.
TanStack Router bu muammoga chek qo‘ydi va JSON-First Search Params arxitekturasini taqdim etdi. Endi query parametrlar shunchaki matn emas, balki to‘laqonli JavaScript turlari (raqamlar, boolean, massivlar va hatto ichma-ich obyektlar) sifatida boshqariladi.
1. JSON-first yondashuvi nima degani?
An'anaviy veb-ishlanmalarda brauzer URL manzili faqat satrlarni (string) tushunadi. Masalan, ?page=1&showDeleted=false manzilidagi har ikkala qiymat brauzer uchun oddiy "1" va "false" matnidir.
TanStack Router bu jarayonni o‘z zimmasiga oladi:
- Serializatsiya: Komponentdagi
{ page: 1, showDeleted: false }obyektini avtomatik toza URL query matniga aylantiradi. - Deserializatsiya (Pars qilish): URL'dagi matnni avtomatik ravishda haqiqiy
numbervabooleanturidagi JavaScript obyektiga o‘girib beradi.
2. Zod yordamida Search Params Validatsiyasi (validateSearch)
TanStack Router Zod (yoki Valibot, ArkType) kutubxonalari bilan birinchi darajali integratsiyaga ega. Marshrut e'lon qilinayotganda validateSearch xossasi orqali query parametrlar qat'iy sxemaga solinadi:
// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
// 1. Qidiruv parametrlari uchun Zod sxemasini e'lon qilamiz
const postsSearchSchema = z.object({
// Agar URL'da page bo'lmasa yoki xato yozilsa, avtomatik 1 bo'ladi
page: z.number().catch(1),
// Ixtiyoriy matnli filtr
filter: z.string().optional(),
// Boolean qiymat, xato bo'lsa false fallback beriladi
showDeleted: z.boolean().catch(false),
})
export const Route = createFileRoute('/posts')({
// 2. validateSearch orqali URL'dagi query'lar tekshiriladi va 100% tiplanadi
validateSearch: (search) => postsSearchSchema.parse(search),
// 3. Loader parametrlardan to'liq type-safe foydalanadi
loaderDeps: ({ search }) => ({
page: search.page,
filter: search.filter,
}),
loader: async ({ deps }) => {
// deps.page turi: number!
const response = await fetchPostsApi(deps.page, deps.filter)
return response
},
component: PostsPageComponent,
})
function PostsPageComponent() {
// 4. Route.useSearch() orqali to'g'ridan-to'g'ri tiplangan obyektni olamiz
const search = Route.useSearch()
return (
<div style={{ padding: '2rem' }}>
<h1>Maqolalar ro'yxati</h1>
<p>Joriy sahifa raqami: <strong>{search.page}</strong> (Turi: {typeof search.page})</p>
<p>O'chirilganlar ko'rinsinmi: <strong>{search.showDeleted ? "Ha" : "Yo'q"}</strong></p>
</div>
)
}
async function fetchPostsApi(_page: number, _filter?: string) {
return []
}
[!TIP]
.catch(default)nima uchun kerak? Agar foydalanuvchi brauzer manzilida ataylab?page=not-a-numberdeb xato kiritsa,.catch(1)zaxira qiymati ishga tushadi va sahifa buzilmasdan avtomatik 1-sahifaga o‘giriladi.
3. Search parametrlarni o'zgartirish (navigate va <Link>)
Query parametrlarini yangilashda ham to‘liq type-safety saqlanib qoladi.
A. navigate orqali dinamik o'zgartirish:
import { useNavigate } from '@tanstack/react-router'
export function PaginationButtons() {
const navigate = useNavigate()
const handleNextPage = () => {
navigate({
to: '/posts',
// search funksiyasi avvalgi parametrlarni (prev) oladi
search: (prev) => ({
...prev,
page: prev.page + 1, // prev.page raqam bo'lgani uchun xavfsiz qo'shamiz
}),
})
}
return <button onClick={handleNextPage}>Keyingi sahifa →</button>
}
B. <Link> komponenti orqali:
import { Link } from '@tanstack/react-router'
export function FilterLinks() {
return (
<div style={{ display: 'flex', gap: '1rem' }}>
{/* Type-safe Link: mavjud parametrlarga yangi filtr qo'shamiz */}
<Link
to="/posts"
search={(prev) => ({ ...prev, filter: 'tech', page: 1 })}
>
Texnologiyalar
</Link>
<Link
to="/posts"
search={(prev) => ({ ...prev, showDeleted: true })}
>
O'chirilganlarni ko'rsatish
</Link>
</div>
)
}
4. Query parametrlarning ishlash oqimi (Mermaid Diagram)
flowchart LR
URL["Brauzer URL: ?page=3&showDeleted=true"] --> Router["TanStack Router tahlili"]
Router --> Zod["validateSearch (Zod Schema)"]
subgraph Transformation["Avtomatik Pars Qilish"]
Zod --> PageNum["page: 3 (number)"]
Zod --> BoolVal["showDeleted: true (boolean)"]
end
PageNum --> Hook["Route.useSearch()"]
BoolVal --> Hook
Hook --> Component["Komponent ichida toza va qulay foydalanish"]
5. React Router va TanStack Router taqqosi
| Xususiyat | React Router (useSearchParams) |
TanStack Router (JSON-First) |
|---|---|---|
| Qaytaradigan qiymat turi | URLSearchParams (Faqat matn/string) |
To‘liq JavaScript obyekti (number, boolean, array) |
| Raqamlar bilan ishlash | Number(params.get('page')) qo‘lda |
search.page (O‘z-o‘zidan number) |
| Boolean bilan ishlash | params.get('del') === 'true' qo‘lda |
search.showDeleted (O‘z-o‘zidan boolean) |
| Sxema validatsiyasi | Standart holda mavjud emas | Zod, Valibot bilan chuqur integratsiya (validateSearch) |
| Xatoliklardan himoya | Qo‘lda try/catch yoki tekshiruv |
.catch() orqali avtomatik xavfsiz fallback |
| Parametrlarni o‘zgartirish | setSearchParams({ page: '2' }) |
search: (prev) => ({ ...prev, page: 2 }) |
Xulosa
- JSON-First Search Params — query parametrlarni quruq matn sifatida emas, balki real JavaScript obyektlari sifatida boshqarish imkonini beradi.
validateSearchva Zod yordamida URL query ma'lumotlari qat'iy tiplanadi va noto‘g‘ri kiritilgan qiymatlar xavfsiz standart qiymatga o‘giriladi.Route.useSearch()orqali komponent ichida raqamlar, mantiqiy qiymatlar va massivlarni hech qanday qo‘shimchaNumber()yokiBoolean()kastinglarisiz xavfsiz ishlatish mumkin.