Como usar parâmetros de consulta em Angular

Introdução

Parâmetros de consulta em Angular permitem passar parâmetros opcionais em qualquer rota na aplicação. Parâmetros de consulta são diferentes dos parâmetros regulares de rota, que só estão disponíveis em uma rota e não são opcionais (por exemplo, /product/:id).

Neste artigo, vamos fazer referência a um exemplo de uma aplicação que exibe uma lista de produtos. Vamos fornecer valores opcionais de order e price-range sobre o qual o componente que recebe pode ler e atuar. Os valores fornecidos afetarão a ordenação e a filtragem da lista de produtos.

Usando parâmetros de consulta com Router.navigate

Se você estiver navegando até a rota usando imperativamente Router.navigate, você irá passar parâmetros de consulta com queryParams.

Em nosso exemplo, se quisermos encaminhar os visitantes para os produtos com a lista ordenada por popularidade, isto seria algo assim:

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

Isso resultará em uma URL como esta:

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

Também é possível fornecer vários parâmetros de consulta. Em nosso exemplo, se quisermos encaminhar os visitantes para os produtos com a lista ordenada por popularidade e filtrada com uma faixa de preços cara, isso seria assim:

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

Isso resultará em uma URL como esta:

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

Agora, você tem uma compreensão de como queryParams pode ser usado para definir parâmetros de consulta.

Preservando ou mesclando parâmetros de consulta com queryParamsHandling

Por padrão, os parâmetros de consulta são perdidos em qualquer ação de navegação subsequente. Para evitar isso, é possível definir queryParamsHandling como 'preserve' ou 'merge'.

Em nosso exemplo, se quisermos encaminhar os visitantes de uma página com o parâmetro de consulta { order: 'popular' } para a página /users mantendo os parâmetros de consulta, usaríamos 'preserve':

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

Isso resultará em uma URL como esta:

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

Em nosso exemplo, se quisermos encaminhar os visitantes de uma página com o parâmetro de consulta { order: 'popular' } para a página /users enquanto passamos os parâmetros de consulta { filter: 'new' }, usaríamos 'merge':

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

Isso resultará em uma URL como esta:

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

Agora, você tem uma compreensão de como queryParamsHandling pode ser usado para preservar e mesclar parâmetros de consulta.

Usando parâmetros de consulta com RouterLink

Em nosso exemplo, se em vez disso você estiver usando a diretiva RouterLink para navegar até a rota, você usaria queryParams dessa forma:

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

E, em nosso exemplo, se você quiser 'preservar' ou 'mesclar' parâmetros de consulta na navegação subsequente, você usaria queryParamsHandling desta forma:

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

Agora, você entende como queryParams e queryParamsHandling podem ser usados com RouterLink.

Acessando valores de parâmetros de consulta

Agora que sabemos como passar parâmetros de consulta opcionais para uma rota, vamos ver como acessar esses valores nas rotas resultantes. A classe ActivatedRoute possui uma propriedade queryParams que retorna um observável dos parâmetros de consulta disponíveis na URL atual.

Dada a seguinte URL de rota:

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

Podemos acessar o parâmetro de consulta order desta forma:

// ...
import { ActivatedRoute } from '@angular/router';
import 'rxjs/add/operator/filter';

@Component({ ... })
export class ProductComponent implements OnInit {
  order: string;
  constructor(private route: ActivatedRoute) { }

  ngOnInit() {
    this.route.queryParams
      .filter(params => params.order)
      .subscribe(params => {
        console.log(params); // { order: "popular" }

        this.order = params.order;
        console.log(this.order); // popular
      }
    );
  }
}

No log de console veríamos o objeto params:

Output
{ order: "popular" }

E o valor params.order:

Output
popular

Também há queryParamMap, que retorna um observável com um objeto paramMap.

Dada a seguinte URL de rota:

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

Podemos acessar os parâmetros de consulta desta forma:

this.route.queryParamMap
  .subscribe((params) => {
    this.orderObj = { ...params.keys, ...params };
  }
);

Utilizamos o operador de propagação de objetos aqui e essa é a forma resultante dos dados em orderObj:

{
  "0": "order",
  "1": "filter",
  "params": {
    "order": "popular",
    "filter": "new"
  }
}

Agora, você tem uma compreensão de como queryParams e queryParamMap podem ser usados para acessar valores nas rotas resultantes.

Conclusão

Neste artigo, você usou diferentes exemplos para definir e obter parâmetros de consulta em Angular. Apresentamos queryParams e queryParamsHandling com Router.navigate e RouterLink. Também apresentamos queryParams e queryParamMap com ActivatedRoute.

Se você gostaria de aprender mais sobre o Angular, confira nossa página de tópico sobre Angular para exercícios e projetos de programação.