{ "id": "api/common/Location", "title": "Location", "contents": "\n\n
\n
\n
\n \n API > @angular/common\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

Locationlink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

A service that applications can use to interact with a browser's URL.

\n\n

See more...

\n
\n \n \n \n
\n\nclass Location {\n static normalizeQueryParams: (params: string) => string\n static joinWithSlash: (start: string, end: string) => string\n static stripTrailingSlash: (url: string) => string\n path(includeHash: boolean = false): string\n getState(): unknown\n isCurrentPathEqualTo(path: string, query: string = ''): boolean\n normalize(url: string): string\n prepareExternalUrl(url: string): string\n go(path: string, query: string = '', state: any = null): void\n replaceState(path: string, query: string = '', state: any = null): void\n forward(): void\n back(): void\n onUrlChange(fn: (url: string, state: unknown) => void)\n subscribe(onNext: (value: PopStateEvent) => void, onThrow?: (exception: any) => void, onReturn?: () => void): SubscriptionLike\n}\n\n\n \n \n
\n

Subclasseslink

\n \n\n\n\n\n
\n \n\n
\n\n\n \n\n \n \n
\n

Descriptionlink

\n

Depending on the LocationStrategy used, Location persists\nto the URL's path or the URL's hash segment.

\n\n

Further information available in the Usage Notes...

\n
\n\n \n
\n

Static propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n static normalizeQueryParams: (params: string) => string\n \n \n

Normalizes URL parameters by prepending with ? if needed.

\n\n \n
\n \n static joinWithSlash: (start: string, end: string) => string\n \n \n

Joins two parts of a URL with a slash if needed.

\n\n \n
\n \n static stripTrailingSlash: (url: string) => string\n \n \n

Removes a trailing slash from a URL string if needed.\nLooks for the first occurrence of either #, ?, or the end of the\nline as / characters and removes the trailing slash if one exists.

\n\n \n
\n
\n\n\n\n\n\n\n\n\n\n\n\n
\n

Methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n path()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Normalizes the URL path for this location.

\n\n
\n
\n \n\n path(includeHash: boolean = false): string\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n includeHash\n boolean\n

True to include an anchor fragment in the path.

\n

Optional. Default is false.

\n\n
\n\n \n
Returns
\n

string: The normalized URL path.

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n getState()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Reports the current state of the location history.

\n\n
\n
\n \n\n getState(): unknown\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

unknown: The current value of the history.state object.

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n isCurrentPathEqualTo()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Normalizes the given path and compares to the current normalized path.

\n\n
\n
\n \n\n isCurrentPathEqualTo(path: string, query: string = ''): boolean\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n path\n string\n

The given URL path.

\n\n
\n \n query\n string\n

Query parameters.

\n

Optional. Default is ''.

\n\n
\n\n \n
Returns
\n

boolean: True if the given URL path is equal to the current normalized path, false\notherwise.

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n normalize()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Normalizes a URL path by stripping any trailing slashes.

\n\n
\n
\n \n\n normalize(url: string): string\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n url\n string\n

String representing a URL.

\n\n
\n\n \n
Returns
\n

string: The normalized URL string.

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n prepareExternalUrl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Normalizes an external URL path.\nIf the given URL doesn't begin with a leading slash ('/'), adds one\nbefore normalizing. Adds a hash if HashLocationStrategy is\nin use, or the APP_BASE_HREF if the PathLocationStrategy is in use.

\n\n
\n
\n \n\n prepareExternalUrl(url: string): string\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n url\n string\n

String representing a URL.

\n\n
\n\n \n
Returns
\n

string: A normalized platform-specific URL.

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n go()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Changes the browser's URL to a normalized version of a given URL, and pushes a\nnew item onto the platform's history.

\n\n
\n
\n \n\n go(path: string, query: string = '', state: any = null): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n path\n string\n

URL path to normalize.

\n\n
\n \n query\n string\n

Query parameters.

\n

Optional. Default is ''.

\n\n
\n \n state\n any\n

Location history state.

\n

Optional. Default is null.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n replaceState()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Changes the browser's URL to a normalized version of the given URL, and replaces\nthe top item on the platform's history stack.

\n\n
\n
\n \n\n replaceState(path: string, query: string = '', state: any = null): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n path\n string\n

URL path to normalize.

\n\n
\n \n query\n string\n

Query parameters.

\n

Optional. Default is ''.

\n\n
\n \n state\n any\n

Location history state.

\n

Optional. Default is null.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n forward()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Navigates forward in the platform's history.

\n\n
\n
\n \n\n forward(): void\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n back()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Navigates back in the platform's history.

\n\n
\n
\n \n\n back(): void\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n onUrlChange()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Registers a URL change listener. Use to catch updates performed by the Angular\nframework that are not detectible through \"popstate\" or \"hashchange\" events.

\n\n
\n
\n \n\n onUrlChange(fn: (url: string, state: unknown) => void)\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n fn\n (url: string, state: unknown) => void\n

The change handler function, which take a URL and a location history state.

\n\n
\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n subscribe()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Subscribes to the platform's popState events.

\n\n
\n
\n \n\n subscribe(onNext: (value: PopStateEvent) => void, onThrow?: (exception: any) => void, onReturn?: () => void): SubscriptionLike\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n onNext\n (value: PopStateEvent) => void\n \n \n
\n \n onThrow\n (exception: any) => void\n

Optional. Default is undefined.

\n \n
\n \n onReturn\n () => void\n

Optional. Default is undefined.

\n \n
\n\n \n
Returns
\n

SubscriptionLike: Subscribed events.

\n\n \n\n\n \n\n \n
\n
\n\n \n
\n\n\n\n \n
\n

Usage noteslink

\n

It's better to use the Router#navigate service to trigger route changes. Use\nLocation only if you need to interact with or create normalized URLs outside of\nrouting.

\n

Location is responsible for normalizing the URL against the application's base href.\nA normalized URL is absolute from the URL host, includes the application's base href, and has no\ntrailing slash:

\n
    \n
  • /my/app/user/123 is normalized
    • \n
  • my/app/user/123 is not normalized
    • \n
  • /my/app/user/123/ is not normalized
    • \n
\n

Examplelink

\n\nimport {Location, LocationStrategy, PathLocationStrategy} from '@angular/common';\nimport {Component} from '@angular/core';\n\n@Component({\n selector: 'path-location',\n providers: [Location, {provide: LocationStrategy, useClass: PathLocationStrategy}],\n template: `\n <h1>PathLocationStrategy</h1>\n Current URL is: <code>{{location.path()}}</code><br>\n Normalize: <code>/foo/bar/</code> is: <code>{{location.normalize('foo/bar')}}</code><br>\n `\n})\nexport class PathLocationComponent {\n location: Location;\n constructor(location: Location) {\n this.location = location;\n }\n}\n\n\n\n
\n\n\n\n
\n
\n\n\n" }