URL.canParse() — Methode · JavaScript-Referenz

Signatur

URL.canParse(url, base)

Beschreibung

URL.canParse() ist eine statische Methode des URL-Interfaces. Sie wendet denselben Parser an wie der Konstruktor new URL(), gibt aber nur einen booleschen Wert zurück. Ein URL-Objekt wird nicht erzeugt. Damit ersetzt sie das bisher übliche Muster, new URL() in ein try...catch zu packen, nur um die Gültigkeit einer Adresse zu prüfen.

Typische Einsatzfälle sind die Validierung von Benutzereingaben (z. B. Link-Felder in Formularen), das Filtern von URLs aus Konfigurationsdateien oder API-Antworten und Schutzprüfungen, bevor eine Adresse an fetch() oder location.assign() weitergegeben wird.

Relative Angaben wie /pfad oder ../bild.png sind nur mit einem zweiten Argument base gültig. Die Methode prüft ausschließlich die Syntax nach dem WHATWG-URL-Standard. Ob die Adresse erreichbar ist oder ein sinnvolles Protokoll verwendet, prüft sie nicht.

Wird das geparste Objekt anschließend ohnehin gebraucht, ist URL.parse() (ES-Umfeld 2024) oft die bessere Wahl. Es gibt direkt das Objekt oder null zurück, sodass nicht zweimal geparst wird.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| object mit toString()		Absolute oder relative URL. Nicht-String-Werte werden in einen String umgewandelt, z. B. ein `URL`-Objekt oder ein `Location`-Objekt.
$base	string \| URL	undefined	Basis-URL, gegen die `url` aufgelöst wird, wenn `url` relativ ist. Die Basis selbst muss eine gültige absolute URL sein, sonst ist das Ergebnis `false`. Ist `url` absolut, wird `base` ignoriert.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn new URL(url, base) erfolgreich wäre, sonst false.

Beispiele

Absolute und relative URLs prüfen

console.log(URL.canParse('https://programmierung.net/js'));
console.log(URL.canParse('/js/url'));
console.log(URL.canParse('/js/url', 'https://programmierung.net'));
console.log(URL.canParse('kein url'));
console.log(URL.canParse('mailto:info@example.com'));

true false true false true

Formulareingabe validieren (nur http/https zulassen)

const input = document.querySelector('#website');

const isWebUrl = (value) => {
  if (!URL.canParse(value)) return false;
  const { protocol } = new URL(value);
  return protocol === 'http:' || protocol === 'https:';
};

input.addEventListener('input', () => {
  input.setCustomValidity(isWebUrl(input.value) ? '' : 'Bitte eine gültige http(s)-Adresse eingeben.');
});

Ungültige Einträge aus einer Liste filtern

const links = [
  'https://example.com',
  'docs/intro.html',
  'http://[::1]:8080/',
  'https://exa mple.com',
  '//cdn.example.com/lib.js'
];

const base = 'https://example.com/app/';
const valid = links.filter((link) => URL.canParse(link, base));

console.log(valid);

[ 'https://example.com', 'docs/intro.html', 'http://[::1]:8080/', '//cdn.example.com/lib.js' ]

Fallback für ältere Umgebungen

const canParse = (url, base) => {
  if (typeof URL.canParse === 'function') return URL.canParse(url, base);
  try {
    new URL(url, base);
    return true;
  } catch {
    return false;
  }
};

console.log(canParse('ftp://files.example.org'));

true

// Wichtig · Fallstricke

Nur die Syntax wird geprüft: Auch javascript:alert(1) oder data:text/html,... gelten als gültig. Vor der Nutzung in href, Weiterleitungen oder fetch() immer zusätzlich das protocol gegen eine Positivliste prüfen, sonst drohen XSS-Lücken und offene Weiterleitungen (Open Redirect).
Der Parser ist großzügig: Leerzeichen am Anfang und Ende werden entfernt, und https:example.com oder http://1.2.3 sind gültig. Für strenge Regeln sind zusätzliche Prüfungen nötig.
Relative URLs ohne base ergeben immer false. Ist base selbst ungültig, ist das Ergebnis ebenfalls false.
Wer das Objekt danach braucht, parst mit canParse() plus new URL() doppelt. Besser ist URL.parse() (Chrome 126, Firefox 126, Safari 18, Node.js 22.1).
Kompatibilität: Seit 2023 in allen aktuellen Browsern verfügbar (Baseline 2023). In älteren Browsern und in Node.js vor 18.17 fehlt die Methode. Dort den oben gezeigten Fallback mit try...catch verwenden.

Siehe auch

URL URL.parse() URL.searchParams URLSearchParams try...catch new PannerNode()