Query-Parameter in Angular verwenden

Mit Query-Parametern lassen sich in Angular optionale Anwendungszustände über die URL übertragen, ohne dass sich dadurch die Zuordnung einer Route verändert. Im Unterschied zu Routenparametern, die ein Bestandteil des definierten URL-Pfads sind und für die Aktivierung einer Route vorhanden sein müssen, stehen Query-Parameter hinter dem Zeichen ?. Sie können vollständig fehlen, ohne die Navigation zu beeinflussen. In Angular-Anwendungen werden sie häufig eingesetzt, um Filtereinstellungen, Seiteninformationen und Sortierreihenfolgen in der URL abzubilden.

In diesem Tutorial dient eine Produktübersicht als Beispiel. Anhand dieses Szenarios erfahren Sie, wie Sie Query-Parameter über Router.navigate und RouterLink setzen, bestehende Parameter mit queryParamsHandling über mehrere Navigationsvorgänge hinweg beibehalten oder zusammenführen und die Werte mithilfe von ActivatedRoute in einer Komponente auslesen. Außerdem werden die Vor- und Nachteile von Snapshots und Observables erläutert. Abschließend lernen Sie, wie Angular ab Version 16 Query-Parameter direkt an Eingabeeigenschaften einer Komponente bindet, sodass keine direkte Injection von ActivatedRoute erforderlich ist.

Die wichtigsten Erkenntnisse

• Query-Parameter sind optional, befinden sich nach dem Zeichen ? in der URL und haben keinen Einfluss auf den Abgleich einer Route.
• Verwenden Sie queryParams zusammen mit Router.navigate oder [queryParams] zusammen mit RouterLink, um einer Navigation Parameter hinzuzufügen.
• queryParamsHandling: 'preserve' übernimmt die vorhandene Query-Zeichenfolge unverändert in die nächste Route. Mit 'merge' werden vorhandene und neue Parameter zusammengeführt. Bei identischen Schlüsseln ersetzt der neue Wert den bisherigen Wert.
• Wird queryParamsHandling nicht angegeben, entfernt Angular bei der nächsten Navigation alle zuvor vorhandenen Query-Parameter.
• ActivatedRoute.snapshot.queryParams sollte nur verwendet werden, wenn die betreffende Komponente bei jeder Navigation sicher zerstört und anschließend neu erstellt wird.
• Nutzen Sie eine Subscription auf ActivatedRoute.queryParams oder queryParamMap, wenn Angular dieselbe Komponenteninstanz bei Navigationen innerhalb derselben Route weiterverwendet.
• queryParamMap.get('key') liefert null, wenn ein Parameter nicht vorhanden ist. Prüfen Sie den Rückgabewert deshalb immer oder verwenden Sie einen Fallback mit ??.
• Ab Angular 16 steht withComponentInputBinding() zur Verfügung. Damit können Query-Parameter direkt auf @Input()-Eigenschaften abgebildet werden, ohne ActivatedRoute zu injizieren.
• Query-Parameter eignen sich besonders für Suchfilter, Seitennavigation und andere Zustände, die über eine URL gespeichert, geteilt oder als Lesezeichen abgelegt werden sollen.

Voraussetzungen

Für dieses Tutorial benötigen Sie:

• Grundkenntnisse im Umgang mit Angular Router, RouterLink und ActivatedRoute.
• Angular 16 oder eine neuere Version.

Was sind Query-Parameter in Angular?

Query-Parameter bestehen aus Schlüssel-Wert-Paaren, die nach einem ? an eine URL angehängt werden. Sind mehrere Paare vorhanden, werden sie mit & voneinander getrennt. In der folgenden URL sind order und price-range Query-Parameter:

http://localhost:4200/products?order=popular&price-range=not-cheap

Der Angular Router verarbeitet diese Paare automatisch und stellt sie über ActivatedRoute bereit. Da Query-Parameter nicht zum eigentlichen Routenpfad gehören, wird weiterhin die Route /products verwendet, unabhängig davon, welche Werte die Query-Zeichenfolge enthält.

Query-Parameter und Routenparameter im Vergleich

Die folgende Tabelle stellt Query-Parameter und Routenparameter gegenüber. Dadurch lässt sich leichter entscheiden, welcher Parametertyp für einen bestimmten Anwendungsfall geeignet ist.

Der entscheidende Unterschied besteht darin, dass ein Routenparameter festlegt, welche Ressource geladen wird. Ein Query-Parameter bestimmt dagegen, wie diese Ressource dargestellt, sortiert oder gefiltert werden soll.

Wann sollten Query-Parameter verwendet werden?

Query-Parameter sind geeignet, wenn ein Wert optional ist und die Route sowohl mit als auch ohne diesen Wert funktionieren soll. Sie sind außerdem sinnvoll, wenn eine Ansicht teilbar oder als Lesezeichen speicherbar sein soll. Eine andere Person kann dadurch eine gefilterte Ansicht über dieselbe URL öffnen. Query-Parameter lassen sich zudem zwischen verschiedenen Routen weitergeben, wenn ein Wert während mehrerer Navigationsschritte erhalten bleiben soll.

Typische Beispiele sind Suchseiten wie /search?q=angular, paginierte Listen wie /products?page=2&pageSize=20 und Filteroberflächen wie /items?category=books&sort=price.

Query-Parameter mit Router.navigate verwenden

Um bei einer programmgesteuerten Navigation Query-Parameter zu übermitteln, fügen Sie dem an Router.navigate übergebenen NavigationExtras-Objekt eine Eigenschaft namens queryParams hinzu. Der aus @angular/router importierte Typ NavigationExtras unterstützt unter anderem queryParams, queryParamsHandling, fragment und weitere Navigationseinstellungen.

Das folgende Beispiel navigiert zu /products und ergänzt die URL um order=popular:

import { Component } from '@angular/core';
import { Router } from '@angular/router';

@Component({ ... })
export class ProductListComponent {
  constructor(private router: Router) {}

  goProducts() {
    this.router.navigate(
      ['/products'],
      { queryParams: { order: 'popular' } }
    );
  }
}

Durch diese Navigation entsteht eine URL in der folgenden Form:

Ausgabe

http://localhost:4200/products?order=popular

Für mehrere Query-Parameter ergänzen Sie das queryParams-Objekt um weitere Schlüssel. Im nächsten Beispiel werden sowohl order als auch price-range übergeben:

goProducts() {
  this.router.navigate(
    ['/products'],
    { queryParams: { order: 'popular', 'price-range': 'not-cheap' } }
  );
}

Die daraus resultierende URL lautet:

Ausgabe

http://localhost:4200/products?order=popular&price-range=not-cheap

Query-Parameter mit queryParamsHandling beibehalten oder zusammenführen

Standardmäßig entfernt Angular alle Query-Parameter, sobald zu einer anderen Route navigiert wird. Mit der Eigenschaft queryParamsHandling innerhalb von NavigationExtras kann dieses Verhalten geändert werden. Der Wert 'preserve' übernimmt die gesamte aktuelle Query-Zeichenfolge. Der Wert 'merge' verbindet dagegen vorhandene Parameter mit den neu angegebenen Parametern.

Vorhandene Query-Parameter beibehalten

Verwenden Sie 'preserve', wenn eine verwandte Zielseite den bestehenden Kontext vollständig übernehmen soll, ohne einen Parameter hinzuzufügen oder zu verändern. Im folgenden Beispiel wechselt ein Benutzer von /products?order=popular zu /users. Der Parameter order bleibt dabei erhalten:

goUsers() {
  this.router.navigate(
    ['/users'],
    { queryParamsHandling: 'preserve' }
  );
}

Die Ziel-URL enthält weiterhin den ursprünglichen Parameter:

Ausgabe

http://localhost:4200/users?order=popular

Vorhandene und neue Query-Parameter zusammenführen

Nutzen Sie 'merge', wenn einzelne Parameter ergänzt oder aktualisiert werden sollen, während alle übrigen Werte bestehen bleiben. Das folgende Beispiel ergänzt einen Parameter namens filter und behält gleichzeitig den vorhandenen Parameter order bei:

goUsers() {
  this.router.navigate(
    ['/users'],
    {
      queryParams: { filter: 'new' },
      queryParamsHandling: 'merge'
    }
  );
}

Die zusammengeführte URL enthält beide Parameter:

Ausgabe

http://localhost:4200/users?order=popular&filter=new

Hinweis: Die Option preserveQueryParams wurde in Angular 4 als veraltet markiert und in Angular 8 entfernt. Verwenden Sie stattdessen queryParamsHandling: 'preserve'.

Ein typisches Einsatzgebiet für 'merge' ist ein mehrstufiger Filterprozess. Eine Person kann beispielsweise in einer Komponente eine Kategorie und in einer weiteren Komponente einen Preisbereich auswählen. Jede Navigation kann die neue Auswahl in die URL integrieren, ohne zuvor gewählte Filter zu überschreiben.

Query-Parameter mit RouterLink verwenden

Die Direktive RouterLink unterstützt dieselben Optionen queryParams und queryParamsHandling wie Router.navigate. Binden Sie ein Objekt an [queryParams], um Parameter festzulegen. Über das Attribut queryParamsHandling bestimmen Sie, wie Angular mit bereits vorhandenen Parametern umgehen soll.

Um in einem Template einen Query-Parameter zu definieren, binden Sie ein Objektliteral an [queryParams]:

<a
  [routerLink]="['/products']"
  [queryParams]="{ order: 'popular' }"
>
  Products
</a>

Um Parameter bei einer Navigation im Template zu übernehmen oder zusammenzuführen, ergänzen Sie queryParamsHandling. Der folgende Link verbindet die aktuelle Query-Zeichenfolge mit einem neuen Parameter namens filter:

<a
  [routerLink]="['/users']"
  [queryParams]="{ filter: 'new' }"
  queryParamsHandling="merge"
>
  Users
</a>

Da queryParamsHandling in diesem Beispiel einen festen Zeichenkettenwert erhält und keine gebundene Expression verwendet, werden keine eckigen Klammern benötigt.

Werte von Query-Parametern auslesen

Der Dienst ActivatedRoute stellt zwei grundlegende Möglichkeiten bereit, um Query-Parameter in einer Komponente auszulesen. Ein Snapshot enthält den Zustand, der bei der Initialisierung der Komponente vorlag. Observables geben dagegen neue Werte aus, sobald sich die URL verändert. Seit Angular 16 existiert zusätzlich die Möglichkeit, Routenwerte automatisch mit Komponenteneingaben zu verbinden.

Query-Parameter mit ActivatedRoute.snapshot.queryParams auslesen

ActivatedRoute.snapshot ist ein ActivatedRouteSnapshot, der den Zustand der Route zum Zeitpunkt der Komponentenerstellung repräsentiert. Der Zugriff auf snapshot.queryParams erfolgt synchron und benötigt keine Subscription:

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({ ... })
export class ProductComponent implements OnInit {
  order: string | null = null;

  constructor(private route: ActivatedRoute) {}

  ngOnInit() {
    // Den Wert einmalig bei der Erstellung der Komponente auslesen
    this.order = this.route.snapshot.queryParams['order'] ?? null;
    console.log(this.order);
  }
}

Bei der URL http://localhost:4200/products?order=popular wird Folgendes ausgegeben:

Ausgabe

popular

Die Snapshot-Methode ist geeignet, wenn jede Navigation die aktuelle Komponente zerstört und eine neue Instanz erzeugt. Problematisch wird sie, wenn dieselbe Komponente aktiv bleibt und lediglich die Query-Zeichenfolge geändert wird. Ändert eine Person beispielsweise die Sortierung, ohne die Seite zu verlassen, enthält der vorhandene Snapshot weiterhin den ursprünglichen Wert.

Query-Parameter über das queryParams-Observable auslesen

Eine Subscription auf ActivatedRoute.queryParams liefert einen Datenstrom, der bei jeder Änderung der URL das vollständige Query-Parameter-Objekt ausgibt, solange die Komponente aktiv ist. Diese Vorgehensweise eignet sich für Komponenten, die Angular über mehrere Navigationsvorgänge hinweg wiederverwenden kann:

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { filter } from 'rxjs';

@Component({ ... })
export class ProductComponent implements OnInit {
  order: string = '';

  constructor(private route: ActivatedRoute) {}

  ngOnInit() {
    this.route.queryParams
      .pipe(filter(params => params['order'] !== undefined))
      .subscribe(params => {
        this.order = params['order'];
        console.log(this.order);
      });
  }
}

Für die URL http://localhost:4200/products?order=popular gibt die Subscription Folgendes aus:

Ausgabe

popular

Das Observable queryParams ist die übliche Wahl, wenn eine Komponente auf Änderungen an Parametern reagieren muss, ohne neu erstellt zu werden. Für den typisierten Zugriff auf einzelne Werte und die Unterstützung mehrfach vorkommender Parameter ist queryParamMap häufig besser geeignet.

Query-Parameter mit queryParamMap auslesen

ActivatedRoute.queryParamMap liefert ein Observable mit einem ParamMap-Objekt. Dieses Objekt stellt verschiedene Zugriffsmethoden bereit. Für einzelne Parameter ist dieser Ansatz häufig vorzuziehen, da ParamMap.get() bei einem fehlenden Schlüssel null statt undefined zurückgibt. Mit ParamMap.getAll() lassen sich außerdem Parameter verarbeiten, die mehrfach in derselben URL vorkommen.

Die URL /products?tag=angular&tag=router enthält beispielsweise zwei Werte für den Parameter tag. Der Aufruf getAll('tag') liefert beide Werte als Array.

Für die URL http://localhost:4200/products?order=popular&filter=new können die einzelnen Parameter mit paramMap.get() ausgelesen werden:

this.route.queryParamMap.subscribe(params => {
  const order = params.get('order');      // 'popular'
  const filterVal = params.get('filter'); // 'new'
  const keys = params.keys;               // ['order', 'filter']
  console.log(order, filterVal, keys);
});

Die Subscription gibt den Sortierwert, den Filterwert und die Namen aller aktiven Parameter aus:

Ausgabe

popular new ['order', 'filter']

queryParamMap ist eine zuverlässige Methode zum Auslesen von Angular-Query-Parametern. Durch get() und getAll() werden fehlende Werte eindeutig behandelt und vorhandene Parameter können einfach überprüft werden.

Snapshot oder Observable: Welche Methode ist geeignet?

Verwenden Sie snapshot.queryParams oder snapshot.queryParamMap, wenn die Komponente bei jeder Navigation neu erstellt wird und während ihres Lebenszyklus nicht auf Änderungen der URL reagieren muss. Dadurch bleibt der Code übersichtlich und benötigt keine zusätzliche reaktive Verarbeitung.

Nutzen Sie eine Subscription auf queryParams oder queryParamMap, wenn Angular die Komponente bei Navigationen innerhalb derselben Route möglicherweise weiterverwendet. Eine sortierbare Listenansicht ist ein typisches Beispiel. Die Sortierung wird geändert und die URL aktualisiert, während dieselbe Komponenteninstanz aktiv bleibt. Ein Snapshot enthält in diesem Fall weiterhin den ursprünglichen Wert und kann dazu führen, dass veraltete Daten angezeigt werden. Das Observable reagiert dagegen auf jede URL-Änderung, solange die Komponente aktiv ist.

Moderne Query-Parameter-Bindung mit @Input()

Angular 16 führte withComponentInputBinding() ein. Diese Router-Funktion ordnet Query-Parameter und weitere Routeninformationen automatisch den @Input()-Eigenschaften einer gerouteten Komponente zu. Für einfache Lesevorgänge ist dadurch keine Injection von ActivatedRoute mehr notwendig.

Aktivieren Sie die Funktion, indem Sie withComponentInputBinding() dem Aufruf von provideRouter() in der Datei app.config.ts hinzufügen:

// app.config.ts für eine eigenständige Anwendung ab Angular 16
import { ApplicationConfig } from '@angular/core';
import { provideRouter, withComponentInputBinding } from '@angular/router';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withComponentInputBinding())
  ]
};

Nachdem die Funktion aktiviert wurde, erstellen Sie eine @Input()-Eigenschaft, deren Name mit dem Schlüssel des Query-Parameters übereinstimmt:

import { Component, Input } from '@angular/core';

@Component({
  selector: 'app-product',
  standalone: true,
  template: `<p>Order: {{ order }}</p>`,
})
export class ProductComponent {
  // Angular weist den Query-Parameter ?order=... automatisch dieser Eigenschaft zu
  @Input() order: string | undefined;
}

Angular überträgt den Wert aus der Query-Zeichenfolge auf order, sobald die Komponente aktiviert oder der Parameter geändert wird. In Projekten ab Angular 16, die eigenständige Komponenten verwenden, ist dies eine übersichtliche Lösung für den schreibgeschützten Zugriff auf Query-Parameter.

queryParamMap in ein Signal umwandeln

Wird anstelle eines @Input() ein reaktives Signal benötigt, kann das Observable queryParamMap mithilfe von toSignal() aus @angular/core/rxjs-interop umgewandelt werden. Die seit Angular 14 verfügbare Funktion inject() ermöglicht außerdem den Zugriff auf ActivatedRoute, ohne eine Constructor-Injection zu verwenden:

import { Component, inject } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { toSignal } from '@angular/core/rxjs-interop';
import { map } from 'rxjs';

@Component({
  selector: 'app-product',
  standalone: true,
  template: `<p>Order: {{ order() }}</p>`,
})
export class ProductComponent {
  private route = inject(ActivatedRoute);

  // Ein schreibgeschütztes Signal, das bei Änderungen an ?order= aktualisiert wird
  readonly order = toSignal(
    this.route.queryParamMap.pipe(map(p => p.get('order')))
  );
}

Die Eigenschaft order ist ein schreibgeschütztes Signal und lässt sich mit der in Angular 16 eingeführten signalbasierten Änderungserkennung verwenden. Das Signal wird automatisch neu ausgewertet, sobald sich der Query-Parameter verändert. Das Template stellt anschließend den neuen Wert dar, ohne dass eine manuelle Subscription erforderlich ist.

Praktische Einsatzgebiete für Query-Parameter

Neben der Kenntnis der API ist es ebenso wichtig zu wissen, in welchen Situationen Query-Parameter sinnvoll sind. Drei typische Muster finden sich in nahezu jeder Angular-Anwendung.

Such- und Filterseiten

Such- und Filteroberflächen können ihren aktuellen Zustand in der URL speichern. Dadurch lässt sich eine bestimmte Ansicht teilen oder als Lesezeichen sichern. Eine URL wie /items?category=books&sort=price kann in einem neuen Tab geöffnet werden und erzeugt dort dieselbe gefilterte Darstellung. Ohne Query-Parameter würde dieser Zustand nur im Speicher der Komponente existieren und bei einem Neuladen der Seite verloren gehen.

Pagination

Für die Seitennavigation können Parameter wie page und pageSize verwendet werden. Dadurch können Benutzer unmittelbar eine bestimmte Seite aufrufen und nach einem Aktualisieren des Browsers an dieselbe Position zurückkehren. Ein übliches Format ist /products?page=2&pageSize=20. Fehlt pageSize, kann die Anwendung auf einen geeigneten Standardwert zurückgreifen.

Mehrstufige Abläufe

Mehrstufige Abläufe können queryParamsHandling: 'merge' einsetzen, um ausgewählte Werte über mehrere Navigationsschritte hinweg zu sammeln, ohne einen gemeinsamen Service zu benötigen. Wählt eine Person beispielsweise auf einer Seite einen Zeitraum und auf der nächsten Seite einen Standort, können beide Werte in der URL erhalten bleiben, sofern jede Navigation 'merge' verwendet.

Häufig gestellte Fragen

1. Wie werden Query-Parameter beim Angular Routing übergeben?

Query-Parameter können in Angular übergeben werden, indem beim Aufruf von Router.navigate ein queryParams-Objekt innerhalb von NavigationExtras angegeben wird. Das folgende Beispiel fügt während der programmgesteuerten Navigation einen Parameter namens order hinzu:

this.router.navigate(['/products'], { queryParams: { order: 'popular' } });

Dadurch entsteht eine URL wie /products?order=popular.

In einem Template kann dasselbe Ergebnis mit der Bindung [queryParams] und RouterLink erreicht werden:

<a [routerLink]="['/products']" [queryParams]="{ order: 'popular' }">
  Products
</a>

Beide Verfahren hängen optionale Query-Parameter an die Route an. Auf diese Weise können Anwendungszustände über die URL geteilt werden.

2. Wie wird einem RouterLink in Angular ein Query-Parameter hinzugefügt?

Um Query-Parameter in einem Template zu ergänzen, binden Sie die Eingabe [queryParams] eines Ankers oder eines anderen Elements mit RouterLink an ein Objekt. Die Schlüssel und Werte dieses Objekts bilden die gewünschten Parameter:

<a [routerLink]="['/products']" [queryParams]="{ order: 'popular' }">
  Products
</a>

Für dynamisch erzeugte Query-Parameter kann [queryParams] an eine Komponenteneigenschaft wie filterOptions gebunden werden. Die enthaltenen Werte können anschließend auf Benutzeraktionen oder Änderungen am Anwendungszustand reagieren.

Beispiel:

// In der Komponentenklasse
filterOptions = { order: 'popular', 'price-range': 'not-cheap' };

<a [routerLink]="['/products']" [queryParams]="filterOptions">
  Filtered Products
</a>

3. Worin unterscheiden sich Query-Parameter und Routenparameter in Angular?

Routenparameter befinden sich direkt in den Pfadsegmenten einer URL. Die Definition /products/:id enthält beispielsweise einen Routenparameter namens id. Dieser Wert ist erforderlich, damit die Route korrekt übereinstimmt, und muss deshalb in der URL vorhanden sein. Routenparameter werden normalerweise verwendet, um eine bestimmte Ressource zu identifizieren, beispielsweise ein einzelnes Produkt anhand seiner ID.

Query-Parameter stehen dagegen nach einem ? und werden als Schlüssel-Wert-Paare dargestellt. Die URL /products?order=popular verwendet beispielsweise einen Query-Parameter, um eine Sortierreihenfolge anzugeben. Query-Parameter sind optional und haben keinen Einfluss darauf, welche Route Angular auswählt. Sie steuern üblicherweise die Darstellung, Sortierung oder Filterung einer Ressource.

Query-Parameter können daher ergänzt oder weggelassen werden, ohne dass sich der Routenabgleich verändert.

4. Wie werden mehrere Query-Parameter in Angular übergeben?

Sie können beliebig viele Query-Parameter hinzufügen, indem Sie dem Objekt weitere Schlüssel-Wert-Paare zuweisen. Im folgenden Beispiel werden sowohl order als auch price-range übergeben.

Programmgesteuerte Navigation:

this.router.navigate(['/products'], {
  queryParams: { order: 'popular', 'price-range': 'not-cheap' }
});

Navigation im Template:

<a
  [routerLink]="['/products']"
  [queryParams]="{ order: 'popular', 'price-range': 'not-cheap' }"
>
  Products
</a>

Beide Methoden erzeugen eine URL in der folgenden Form:

/products?order=popular&price-range=not-cheap

Dieses Muster unterstützt eine beliebige Anzahl optionaler Parameter.

5. Worin unterscheiden sich snapshot.queryParams und eine Subscription auf queryParams?

Bei der Verwendung von snapshot.queryParams liest Angular die Query-Parameter genau einmal aus, nämlich bei der ersten Erstellung der Komponente. Diese Methode eignet sich für Situationen, in denen die Navigation die Komponente immer zerstört und anschließend neu erzeugt.

Beispiel:

const order = this.route.snapshot.queryParams['order'];

Eine Subscription auf queryParams ermöglicht der Komponente dagegen, auf Änderungen der Query-Parameter zu reagieren, während sie aktiv bleibt. Angular zerstört eine Komponente nicht zwangsläufig, wenn lediglich die Werte der Query-Parameter geändert werden. Diese Vorgehensweise ist deshalb für dynamische Oberflächen mit Filtern, Sortierungen oder paginierten Inhalten erforderlich.

Beispiel:

this.route.queryParams.subscribe(params => {
  this.order = params['order'];
});

Verwenden Sie einen Snapshot, wenn eine Route immer eine neue Komponenteninstanz erstellt. Nutzen Sie ein Observable, wenn die Komponente bei URL-Änderungen aktiv bleiben kann und fortlaufend aktuelle Parameterwerte empfangen muss.

6. Was bewirken queryParamsHandling: ‚preserve‘ und queryParamsHandling: ‚merge‘?

Mit queryParamsHandling: 'preserve' übernimmt Angular die gesamte aktuelle Query-Zeichenfolge unverändert in die Zielroute. Eine Navigation von /products?order=popular zu einer anderen Route kann mit 'preserve' beispielsweise die URL /users?order=popular erzeugen.

queryParamsHandling: 'merge' verbindet vorhandene Query-Parameter mit den neu angegebenen Parametern. Wird ein bereits vorhandener Schlüssel erneut angegeben, ersetzt der neue Wert den bisherigen Wert. Eine Navigation von /products?order=popular zu /users mit queryParams: { filter: 'new' } und queryParamsHandling: 'merge' erzeugt beispielsweise /users?order=popular&filter=new.

Die folgende Tabelle fasst den Unterschied zusammen:

7. Wie wird ein bestimmter Query-Parameter in einer Angular-Komponente ausgelesen?

Angular bietet mehrere Möglichkeiten, um einen bestimmten Query-Parameter auszulesen. Welche Variante geeignet ist, hängt vom gewünschten Verhalten und der verwendeten Angular-Version ab.

Soll die Komponente bei jeder Änderung der Query-Parameter reagieren, verwenden Sie eine Subscription auf das Observable ActivatedRoute.queryParamMap. Dieser Ansatz liefert zuverlässig alle aktualisierten Werte:

this.route.queryParamMap.subscribe(params => {
  const value = params.get('order'); // Ein String oder null, wenn der Parameter fehlt
});

Wenn der Query-Parameter nur einmal während der Initialisierung der Komponente gelesen werden muss, kann ActivatedRoute.snapshot.queryParamMap verwendet werden:

const value = this.route.snapshot.queryParamMap.get('order');

In Anwendungen ab Angular 16, die eigenständige Komponenten und withComponentInputBinding() verwenden, kann Angular Query-Parameter automatisch Eingabeeigenschaften einer Komponente zuweisen:

@Input() order: string | undefined;

Angular aktualisiert die Eingabeeigenschaft order anschließend, sobald sich der entsprechende Query-Parameter in der URL verändert.

Das ursprüngliche queryParams-Objekt liefert für nicht vorhandene Schlüssel undefined. queryParamMap.get() gibt dagegen null zurück. Prüfen Sie deshalb den jeweiligen Rückgabewert oder verwenden Sie den Nullish-Coalescing-Operator ??.

8. Können Query-Parameter in Angular einen Routenfehler oder eine fehlgeschlagene Navigation verursachen?

Nein. Query-Parameter beeinflussen nicht, welche Route Angular auswählt. Für die Erkennung und Aktivierung einer Route verwendet Angular ausschließlich den URL-Pfad. Werte hinter dem Pfad, beispielsweise ?key=value, werden beim Routenabgleich nicht berücksichtigt.

Angular ordnet deshalb /products, /products?order=popular und /products?foo=bar&baz=qux derselben Route zu. Ob Query-Parameter vorhanden sind oder fehlen, verändert die aktivierte Route nicht.

Die Komponentenlogik muss dennoch mit fehlenden oder unerwarteten Parameterwerten umgehen können. Prüfen Sie vor der Verwendung eines Query-Parameters, ob der Wert weder null noch undefined ist. Dadurch lassen sich Laufzeitfehler und unerwünschtes Verhalten vermeiden.

Beispiel:

const value = this.route.snapshot.queryParamMap.get('order');

if (value !== null) {
  // Den Wert verwenden
}

Mit diesem Muster kann die Anwendung optionale oder nicht vorhandene Query-Parameter sicher verarbeiten.

Fazit

In diesem Tutorial haben Sie queryParams und queryParamsHandling sowohl mit Router.navigate als auch mit RouterLink verwendet, um Angular-Query-Parameter zu definieren und zu verwalten. Darüber hinaus haben Sie Parameterwerte über ActivatedRoute.snapshot, das Observable queryParams und queryParamMap ausgelesen. Außerdem wurde gezeigt, wie withComponentInputBinding() ab Angular 16 den Zugriff auf Parameter in eigenständigen Komponenten vereinfacht und wie toSignal() Query-Parameter mit dem Signal-System von Angular verbindet.