URL và query string trong JavaScript: URL và URLSearchParams

Đừng phân tích URL bằng các mẹo xử lý chuỗi nữa

Trước khi có API URL, người ta cắt URL bằng split('?'), regex và cầu may. Cách đó phần lớn vẫn chạy, cho đến khi một giá trị chứa &, =, khoảng trắng hoặc ký tự ngoài ASCII, và lúc đó thì hỏng. Cả trình duyệt lẫn Node đều có sẵn một bộ phân tích đúng chuẩn. Hãy dùng nó.

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

Chỉ một lời gọi, mọi phần của URL đã được tách riêng và giải mã đúng. Hàm khởi tạo ném ra TypeError với đầu vào không hợp lệ, và đó thường là điều bạn muốn: một URL rác nên thất bại rõ ràng, thay vì lặng lẽ tạo ra dữ liệu rác ở phía sau.

Đọc tham số query

Mỗi URL có thuộc tính .searchParams: một đối tượng URLSearchParams biết cách đọc và ghi query string:

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

Vài điều đáng chú ý:

• Giá trị trả về đã được giải mã. ?name=Ada%20Lovelace cho bạn "Ada Lovelace".
• Mọi thứ đều là chuỗi. "2" không phải 2. Hãy chuyển đổi bằng Number() nếu bạn cần số.
• Khóa lặp lại là hợp lệ. get trả về giá trị khớp đầu tiên; getAll trả về mọi giá trị khớp.
• Khóa không tồn tại trả về null, không phải undefined, nên ?? "default" dùng rất hợp với chúng.

Tạo query string

Bạn có thể tạo query string từ đầu bằng URLSearchParams, không cần tự thoát ký tự, không cần nối bằng &:

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

Hoặc tạo từ một đối tượng: bất kỳ iterable nào chứa các cặp [key, value] đều được, và một đối tượng thông thường cũng vậy:

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set và append: set thay thế mọi giá trị đang có của khóa đó. append thêm một giá trị nữa. Dùng append khi một khóa có thể lặp lại một cách hợp lệ (tag, bộ lọc); dùng set cho các tham số chỉ có một giá trị.

Chỉnh sửa URL

Vì URL là một đối tượng "sống", việc thay đổi searchParams tự động cập nhật .search và .href:

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // overwrites
u.searchParams.delete("utm_source");       // no-op if absent

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

Đây là cách viết chuẩn để thêm một tham số query vào URL có sẵn. Không cần kiểm tra "URL đã có ? chưa", không phải lo nên thêm & hay ? ở trước.

Bạn có thể thay đổi các phần khác của URL theo cách tương tự:

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

Duyệt qua các tham số

URLSearchParams là một iterable. for...of cho bạn các cặp [key, value], và có sẵn các hàm hỗ trợ quen thuộc keys(), values() và entries():

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

Lưu ý rằng các khóa lặp lại sẽ xuất hiện nhiều lần: bạn sẽ thấy tag = web rồi tag = beginner như hai mục riêng biệt. Điều đó phản ánh đúng query string thực tế.

Nếu bạn muốn một đối tượng thông thường để in ra gỡ lỗi nhanh, Object.fromEntries dùng được, nhưng nó gộp các khóa lặp lại và chỉ giữ giá trị cuối cùng:

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

Dùng để gỡ lỗi thì được. Sai nếu có khóa nào có thể lặp lại.

URL tương đối cần một URL gốc

Riêng new URL("/search?q=js") sẽ ném lỗi: một đường dẫn tương đối tự nó không phải URL hợp lệ. Hãy truyền một URL gốc làm đối số thứ hai:

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

Quy tắc phân giải giống hệt quy tắc trình duyệt dùng cho <a href>: dấu / ở đầu là tuyệt đối tính từ host, không có dấu gạch chéo là tương đối so với đường dẫn hiện tại, .. đi lên một cấp. Rất tiện khi bạn ghép URL API từ một URL gốc đã cấu hình.

Trên trình duyệt, window.location.href là một URL gốc có sẵn để phân tích URL của trang hiện tại:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Xử lý URL không hợp lệ

Hàm khởi tạo URL ném lỗi khi đầu vào sai định dạng. Điều đó hữu ích, nhưng cũng có nghĩa là bạn cần try/catch khi phân tích bất cứ thứ gì người dùng nhập hoặc hệ thống bên ngoài gửi tới:

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL object
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

Các môi trường hiện đại còn cung cấp URL.canParse(input): một phép kiểm tra trả về boolean, giúp tránh rườm rà với try/catch khi bạn chỉ muốn xác thực:

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

Một ví dụ nhỏ hoàn chỉnh

Ghép tất cả lại: đọc các bộ lọc hiện tại từ một URL, điều chỉnh chúng và tạo ra một URL mới để chuyển tới:

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

Truyền null sẽ xóa tham số. Mọi giá trị khác sẽ đặt mới hoặc ghi đè nó. Đó là mẫu bạn sẽ viết dưới dạng này hay dạng khác mỗi khi xây dựng giao diện bộ lọc, phân trang hoặc deep link.

Những điều cần nhớ

• new URL(string) phân tích một URL thành các phần có tên. Nó ném lỗi khi gặp dữ liệu rác.
• url.searchParams là một URLSearchParams: dùng get, getAll, set, append, delete, has.
• Việc mã hóa được làm sẵn cho bạn. Đừng dùng encodeURIComponent trừ khi bạn tự tay ghép chuỗi.
• Truyền một URL gốc làm đối số thứ hai để phân giải đường dẫn tương đối.
• URL.canParse (hoặc try/catch) là công cụ xác thực cho đầu vào không đáng tin.

Mỗi khi bạn định tách URL bằng .split('?') hay lấy một tham số query bằng regex, hãy dùng những API này thay vào đó. Chúng ngắn hơn, đúng hơn và đã có sẵn trong môi trường chạy.