Skip to content

Phân trang và lọc ​

Trang này giải thích frontend gửi tham số phân trang, lọc và sắp xếp thế nào, và vì sao danh sách tìm việc công khai và danh sách quản trị dùng hai cách khác nhau. Dành cho developer thêm bộ lọc hoặc đổi cách hiển thị danh sách.

Vì sao có hai cách ​

Backend có hai kiểu route danh sách:

  • Route CRUD như /jobs, /companies, /users nhận bộ lọc dưới dạng query string tự do, do thư viện api-query-params của backend đọc (name=/abc/i, sort=-createdAt).
  • Route tìm kiếm hợp nhất /job-search nhận một tập tham số cố định và có kiểm tra giá trị.

Frontend giữ nguyên hai kiểu đó thay vì ép về một: danh sách quản trị cần lọc linh hoạt, còn trang tìm việc công khai cần tham số rõ ràng và an toàn.

Dạng dữ liệu phân trang ​

Mọi danh sách phân trang có dạng PaginatedResult<T> ở src/shared/types/pagination.ts:

FieldKiểuÝ nghĩa
resultT[]Các phần tử của trang hiện tại
meta.pagination.current_pagenumberTrang hiện tại
meta.pagination.per_pagenumberSố phần tử mỗi trang
meta.pagination.total_pagesnumberTổng số trang
meta.pagination.totalnumberTổng số phần tử

Backend nêu một ngoại lệ ở GET /cv-profiles, trả { data, total, page, limit }; xem tài liệu backend.

Kiểu 1: danh sách CRUD ​

Tham số nhận vào là PaginatedQueryParams:

FieldKiểuMặc định ở hookÝ nghĩa
pagenumber1Trang
limitnumber10Số phần tử mỗi trang
filterstringrỗngĐoạn query nối thẳng vào URL, ví dụ isActive=true
sortstringrỗngĐoạn query nối thẳng, ví dụ sort=-createdAt
keywordstringkhông cóChỉ getJobs gửi, được encodeURIComponent

getJobs và getCompanies dựng page=..&limit=.., rồi nối filter và sort nguyên văn. Ví dụ từ trang chủ:

ts
// home-query.ts: getHomeJobsQuery(page) trả về
// { page, limit: 6, filter: "isActive=true", sort: "sort=-createdAt" }
useGetJobsQuery(getHomeJobsQuery(jobsPage));
// GET /jobs?page=1&limit=6&isActive=true&sort=-createdAt

Danh sách công ty công khai lọc theo tên bằng name=/<từ khóa>/i, do buildCompanyListQueryArgs dựng và có encodeURIComponent.

WARNING

filter và sort được nối thẳng vào URL, nên người gọi phải tự bảo đảm giá trị đã được mã hóa. Danh sách công ty công khai, danh sách việc của công ty và keyword có dùng encodeURIComponent; trang quản trị tin dựng name=/<từ khóa>/i mà không mã hóa từ khóa.

Kiểu 2: tìm việc hợp nhất ​

Trạng thái của trang /jobs được giữ trong URL, đọc bằng parseJobListSearchParams, rồi đổi thành tham số API bằng buildJobSearchParams. Giá trị lạ trong URL bị thay bằng mặc định.

Tham số URLGiá trị chấp nhậnTham số APIGhi chú
qchuỗi bất kỳkeywordBỏ khoảng trắng hai đầu
locationCodemã địa điểmlocationCodeCũng nhận location và đổi thành mã
typeall, Full-time, Part-time, Internship, Freelance, Remote, Hybrid, OtherformOfWorkall thì không gửi
experienceall, Internship, Junior, Mid, Senior, Lead, Managerlevelall thì không gửi
salaryall, 0-10000000, 10000000-20000000, 20000000-50000000, 50000000-999999999salaryMin, salaryMaxTách chuỗi tại dấu -
sourceall, internal, externalsourceall thì không gửi
sort-createdAt, createdAt, -salary, salarysortĐổi thành newest, oldest, salary_desc, salary_asc
pagesố nguyên dươngpageMặc định 1
limitsố nguyên dươnglimitMặc định 10

JobSearchParams luôn có page, limit, sort; các trường còn lại chỉ có khi người dùng chọn.

Backend giới hạn limit tối đa 50 và keyword tối đa 100 ký tự (job-search.constants.ts). Frontend chỉ kiểm tra limit là số nguyên dương và không tự cắt về 50, nên kết quả khi vượt trần do backend quyết định.

Đồng bộ với URL ​

Khi người dùng đổi bộ lọc, trang gọi router.replace với URL mới và scroll: false. Tham số có giá trị mặc định không được ghi vào URL, vì vậy trang mặc định luôn có URL gọn. Đây cũng là cơ sở để trang quyết định biến thể nào được lập chỉ mục, xem Rendering và SEO.

Danh sách công ty cũng đồng bộ với URL theo cách tương tự nhưng chỉ có q, page, limit, và kích thước trang mặc định là 9.

Hiển thị phân trang ​

Hai component cùng tồn tại:

ComponentProps chínhDùng ở
SimplePaginationpage, totalPages, onPageChangeTrang /jobs, lấy totalPages từ meta.pagination.total_pages
PaginationcurrentPage, pageSize, totalItems, onPageChange, onPageSizeChangeTự tính số trang bằng Math.ceil(totalItems / pageSize)

Source code liên quan ​

Backend mô tả route tìm kiếm ở Job Search API.

Đọc tiếp: Quy ước API, Cache và invalidation, Chiến lược cache.

Tài liệu kỹ thuật xây dựng theo chuẩn Documentation as Code