Angular router.navigate() delta

Question

As described in the manual, router.navigate accepts a delta, but the manual but isn't specific enough on that:

Navigate based on the provided array of commands and a starting point. If no starting route is provided, the navigation is absolute.

...

In opposite to navigateByUrl, navigate always takes a delta that is applied to the current URL.

Does it just apply a relative URL or something more complex? What kind of delta does it refer to in case of absolute navigation then?

Answer 1

Does it just apply a relative URL or something more complex?

It is a relative URL built from the pieces you provide via commands param and taking into account additional parameters you pass in extras (the NavigationExtras object).

For example, you can use relativeTo to navigate from the active route or from the root route. You can set the query parameters or fragment for the URL you navigate to (queryParams and fragment in extras) or you can preserve query parameters that are present in the current url (queryParamsHandling in extras).

And so on, so in general, it is actually something more complex than just a navigation by URL as we build the URL dynamically.

What kind of delta does it refer to in case of absolute navigation then?

It is same for relative and absolute navigation - the delta is the set of changes (commands) to apply to the current route (relative) or to the root route (absolute) to transfer the application to the new state (vs just providing the new URL via the navigateByUrl).

In the simple case, if you do something like this.router.navigate(['/heroes']) it actually is not very different from using the navigateByUrl, but consider these examples (see the createUrlTree which actually converts commands and extras to the final URL):

// create /team/33/(user/11//right:chat)
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: 'chat'}}]);

// remove the right secondary node
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: null}}]);

So even for the absolute navigation, the navigate method provides a set of additional tools to dynamically build the URL. You could do this with navigateByUrl, but you would probably parse / concat / do other manipluations with strings (or would develop own tool similar to what navigate and createUrlTree provide).

Answer 2

in relative mode, the delta is applied to the current route. It natively calls navigateByUrl using this code

/**
   * Navigate based on the provided array of commands and a starting point.
   * If no starting route is provided, the navigation is absolute.
   *
   * Returns a promise that:
   * - resolves to 'true' when navigation succeeds,
   * - resolves to 'false' when navigation fails,
   * - is rejected when an error happens.
   *
   * ### Usage
   *
   * ```
   * router.navigate(['team', 33, 'user', 11], {relativeTo: route});
   *
   * // Navigate without updating the URL
   * router.navigate(['team', 33, 'user', 11], {relativeTo: route, skipLocationChange: true});
   * ```
   *
   * In opposite to `navigateByUrl`, `navigate` always takes a delta that is applied to the current
   * URL.
   */
  navigate(commands: any[], extras: NavigationExtras = {skipLocationChange: false}):
      Promise<boolean> {
    validateCommands(commands);
    return this.navigateByUrl(this.createUrlTree(commands, extras), extras);
  }

many examples are included in the source code https://github.com/angular/angular/blob/master/packages/router/src/router.ts