URLs ו-Query Strings ב-JavaScript: URL ו-URLSearchParams

הפסיקו לפענח URLs עם טריקים של מחרוזות

לפני שה-API של URL היה קיים, אנשים חתכו כתובות עם split('?'), ביטויים רגולריים ותקווה. זה עבד ברוב המקרים, עד שערך הכיל &, =, רווח או תו שאינו ASCII, ואז זה הפסיק לעבוד. גם הדפדפן וגם Node מגיעים עם parser אמיתי. השתמשו בו.

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"

קריאה אחת, וכל חלק של הכתובת כבר מפורק ומפוענח נכון. ה-constructor זורק TypeError על קלט לא תקין, ובדרך כלל זה מה שרוצים: כתובת זבל צריכה להיכשל ברעש, ולא לייצר בשקט זבל בהמשך הדרך.

קריאת פרמטרים של Query

לכל URL יש מאפיין .searchParams: אובייקט URLSearchParams שיודע לקרוא ולכתוב את ה-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

כמה דברים ששווה לשים לב אליהם:

• הערכים חוזרים כבר מפוענחים. ?name=Ada%20Lovelace נותן לכם "Ada Lovelace".
• הכול מחרוזת. "2" הוא לא 2. המירו עם Number() אם אתם צריכים מספר.
• מפתחות שחוזרים על עצמם הם חוקיים. get מחזיר את ההתאמה הראשונה; getAll מחזיר את כל ההתאמות.
• מפתחות חסרים מחזירים null, לא undefined, ולכן ?? "default" עובד איתם מצוין.

בניית Query String

אפשר לבנות query string מאפס עם URLSearchParams, בלי escape ידני ובלי חיבור עם &:

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"

או ליצור אותו מאובייקט: כל iterable של זוגות [key, value] עובד, וגם אובייקט רגיל:

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

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

set מול append: set מחליף כל ערך קיים של אותו מפתח. append מוסיף עוד ערך. השתמשו ב-append כשמפתח יכול לחזור באופן לגיטימי (תגיות, מסננים); השתמשו ב-set לפרמטרים עם ערך יחיד.

שינוי URL

מכיוון ש-URL הוא אובייקט חי, שינוי של searchParams מעדכן אוטומטית את .search ואת .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"

זו הדרך המקובלת להוסיף פרמטר query לכתובת קיימת. בלי בדיקה של "האם כבר יש בכתובת ?", בלי לדאוג אם להוסיף לפני כן & או ?.

אפשר לשנות חלקים אחרים של הכתובת באותה דרך:

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

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

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

מעבר על הפרמטרים

URLSearchParams הוא iterable. for...of נותן לכם זוגות [key, value], ויש גם את העוזרים הרגילים keys(), values() ו-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);
}

שימו לב שמפתחות שחוזרים מופיעים כמה פעמים: תראו tag = web ואחריו tag = beginner כרשומות נפרדות. זה נאמן ל-query string האמיתי.

אם אתם רוצים אובייקט רגיל להדפסת דיבוג מהירה, Object.fromEntries עובד, אבל הוא מאחד מפתחות חוזרים ושומר רק את הערך האחרון:

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" }

בסדר לדיבוג. שגוי אם מפתח כלשהו יכול לחזור.

כתובות יחסיות צריכות בסיס

new URL("/search?q=js") לבדו זורק שגיאה: נתיב יחסי הוא לא URL תקין בפני עצמו. העבירו בסיס כארגומנט השני:

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"

חוקי הפתרון זהים לאלה שדפדפנים משתמשים בהם עבור <a href>: / בהתחלה הוא נתיב מוחלט מה-host, בלי לוכסן זה יחסי לנתיב הנוכחי, ו-.. עולה רמה. שימושי מאוד כשמרכיבים כתובות API מבסיס מוגדר.

בדפדפן, window.location.href הוא בסיס מוכן לפענוח הכתובת של העמוד הנוכחי:

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

טיפול בכתובות לא תקינות

ה-constructor של URL זורק שגיאה על קלט פגום. זה שימושי, אבל זה אומר שצריך try/catch כשמפענחים כל דבר שהמשתמש הקליד או שמערכת חיצונית שלחה:

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

סביבות מודרניות חושפות גם את URL.canParse(input): בדיקה בוליאנית שחוסכת את ריקוד ה-try/catch כשרק רוצים לאמת:

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

דוגמה קטנה שעובדת

מחברים הכול יחד: קוראים את המסננים הנוכחיים מכתובת, משנים אותם ומפיקים כתובת חדשה לניווט:

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"

העברת null מוחקת את הפרמטר. כל ערך אחר מגדיר אותו או דורס אותו. זה דפוס שתכתבו בצורה כזו או אחרת בכל פעם שתבנו ממשקי סינון, עימוד או deep links.

מה לקחת מכאן

• new URL(string) מפענח כתובת לחלקים עם שמות. הוא זורק שגיאה על זבל.
• url.searchParams הוא URLSearchParams: השתמשו ב-get, getAll, set, append, delete, has.
• הקידוד קורה בשבילכם. אל תשתמשו ב-encodeURIComponent אלא אם אתם בונים מחרוזות ביד.
• העבירו כתובת בסיס כארגומנט השני כדי לפתור נתיבים יחסיים.
• URL.canParse (או try/catch) הוא כלי האימות שלכם לקלט לא מהימן.

בכל פעם שאתם מתפתים לפצל כתובת עם .split('?') או לשלוף פרמטר query עם regex, השתמשו ב-APIs האלה במקום. הם קצרים יותר, נכונים, וכבר נמצאים בסביבת הריצה.