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

$locationShimlink

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

Location service that provides a drop-in replacement for the $location service\nprovided in AngularJS.

\n\n \n
\n \n \n \n
\n\nclass $locationShim {\n constructor($injector: any, location: Location, platformLocation: PlatformLocation, urlCodec: UrlCodec, locationStrategy: LocationStrategy)\n onChange(fn: (url: string, state: unknown, oldUrl: string, oldState: unknown) => void, err: (e: Error) => void = (e: Error) => { })\n $$parse(url: string)\n $$parseLinkUrl(url: string, relHref?: string): boolean\n absUrl(): string\n url(url?: string): string | this\n protocol(): string\n host(): string\n port(): number | null\n path(path?: string | number): string | this\n search(search?: string | number | { [key: string]: unknown; }, paramValue?: string | number | boolean | string[]): {...}\n hash(hash?: string | number): string | this\n replace(): this\n state(state?: unknown): unknown | this\n}\n\n\n \n \n\n
\n\n\n \n
\n

See alsolink

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

Constructorlink

\n\n\n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n \n\n constructor($injector: any, location: Location, platformLocation: PlatformLocation, urlCodec: UrlCodec, locationStrategy: LocationStrategy)\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 \n \n \n \n \n \n \n \n
\n \n $injector\n any\n \n \n
\n \n location\n Location\n \n \n
\n \n platformLocation\n PlatformLocation\n \n \n
\n \n urlCodec\n UrlCodec\n \n \n
\n \n locationStrategy\n LocationStrategy\n \n \n
\n\n \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
\n

\n onChange()\n \n link

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

Registers listeners for URL changes. This API is used to catch updates performed by the\nAngularJS framework. These changes are a subset of the $locationChangeStart and\n$locationChangeSuccess events which fire when AngularJS updates its internally-referenced\nversion of the browser URL.

\n\n
\n
\n \n\n onChange(fn: (url: string, state: unknown, oldUrl: string, oldState: unknown) => void, err: (e: Error) => void = (e: Error) => { })\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n fn\n (url: string, state: unknown, oldUrl: string, oldState: unknown) => void\n

The callback function that is triggered for the listener when the URL changes.

\n\n
\n \n err\n (e: Error) => void\n

The callback function that is triggered when an error occurs.

\n

Optional. Default is (e: Error) => { }.

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

It's possible for $locationChange events to happen, but for the browser URL\n(window.location) to remain unchanged. This onChange callback will fire only when AngularJS\nactually updates the browser URL (window.location).

\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 $$parse()\n \n link

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

Parses the provided URL, and sets the current URL to the parsed result.

\n\n
\n
\n \n\n $$parse(url: string)\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n url\n string\n

The 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
\n

\n $$parseLinkUrl()\n \n link

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

Parses the provided URL and its relative URL.

\n\n
\n
\n \n\n $$parseLinkUrl(url: string, relHref?: string): boolean\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n url\n string\n

The full URL string.

\n\n
\n \n relHref\n string\n

A URL string relative to the full URL string.

\n

Optional. Default is undefined.

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

boolean

\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 absUrl()\n \n link

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

Retrieves the full URL representation with all segments encoded according to\nrules specified in\nRFC 3986.

\n\n
\n
\n \n\n absUrl(): string\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

string

\n\n \n\n\n \n\n \n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet absUrl = $location.absUrl();\n// => \"http://example.com/#/some/path?foo=bar&baz=xoxo\"\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 url()\n \n link

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

Retrieves the current URL, or sets a new URL. When setting a URL,\nchanges the path, search, and hash, and returns a reference to its own instance.

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

There are no parameters.

\n\n \n
Returns
\n

string

\n\n \n\n\n \n\n \n
\n
\n
\n \n\n url(url: string): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n url\n string\n \n \n
\n\n \n
Returns
\n

this

\n\n \n\n\n \n\n \n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet url = $location.url();\n// => \"/some/path?foo=bar&baz=xoxo\"\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 protocol()\n \n link

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

Retrieves the protocol of the current URL.

\n\n
\n
\n \n\n protocol(): string\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

string

\n\n \n\n\n \n\n \n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet protocol = $location.protocol();\n// => \"http\"\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 host()\n \n link

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

Retrieves the protocol of the current URL.

\n\n
\n
\n \n\n host(): string\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

string

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

In contrast to the non-AngularJS version location.host which returns hostname:port, this\nreturns the hostname portion only.

\n\n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet host = $location.host();\n// => \"example.com\"\n\n// given URL http://user:password@example.com:8080/#/some/path?foo=bar&baz=xoxo\nhost = $location.host();\n// => \"example.com\"\nhost = location.host;\n// => \"example.com:8080\"\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 port()\n \n link

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

Retrieves the port of the current URL.

\n\n
\n
\n \n\n port(): number | null\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

number | null

\n\n \n\n\n \n\n \n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet port = $location.port();\n// => 80\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 path()\n \n link

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

Retrieves the path of the current URL, or changes the path and returns a reference to its own\ninstance.

\n\n
\n\n path(): string\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

string

\n\n \n\n\n \n\n \n
\n
\n
\n \n\n path(path: string | number): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n path\n string | number\n \n \n
\n\n \n
Returns
\n

this

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

Paths should always begin with forward slash (/). This method adds the forward slash\nif it is missing.

\n\n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet path = $location.path();\n// => \"/some/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 search()\n \n link

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

3 overloads...

\n \n Show All\n Hide All\n expand_more\n \n
\n \n
\n \n \n
Overload #1
\n
\n \n
\n

Retrieves a map of the search parameters of the current URL, or changes a search\npart and returns a reference to its own instance.

\n\n
\n\n search(): {\n [key: string]: unknown;\n}\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

`{

\n

}: The parsedsearchobject of the current URL, or the changedsearch` object.

\n\n \n\n\n \n\n \n
\n
\n \n
Overload #2
\n
\n \n\n search(search: string | number | { [key: string]: unknown; }): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n search\n string | number | { [key: string]: unknown; }\n \n \n
\n\n \n
Returns
\n

this

\n\n \n\n\n \n\n \n
\n
\n \n
Overload #3
\n
\n \n\n search(search: string | number | { [key: string]: unknown; }, paramValue: string | number | boolean | string[]): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n search\n string | number | { [key: string]: unknown; }\n \n \n
\n \n paramValue\n string | number | boolean | string[]\n \n \n
\n\n \n
Returns
\n

this

\n\n \n\n\n \n\n \n
\n \n \n
\n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo\nlet searchObject = $location.search();\n// => {foo: 'bar', baz: 'xoxo'}\n\n// set foo to 'yipee'\n$location.search('foo', 'yipee');\n// $location.search() => {foo: 'yipee', baz: 'xoxo'}\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 hash()\n \n link

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

Retrieves the current hash fragment, or changes the hash fragment and returns a reference to\nits own instance.

\n\n
\n\n hash(): string\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

string

\n\n \n\n\n \n\n \n
\n
\n
\n \n\n hash(hash: string | number): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n hash\n string | number\n \n \n
\n\n \n
Returns
\n

this

\n\n \n\n\n \n\n \n
\n
\n \n// given URL http://example.com/#/some/path?foo=bar&baz=xoxo#hashValue\nlet hash = $location.hash();\n// => \"hashValue\"\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 replace()\n \n link

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

Changes to $location during the current $digest will replace the current\nhistory record, instead of adding a new one.

\n\n
\n
\n \n\n replace(): this\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

this

\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

\n state()\n \n link

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

Retrieves the history state object when called without any parameter.

\n\n
\n\n state(): unknown\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

unknown

\n\n \n\n\n \n\n \n
\n
\n
\n \n\n state(state: unknown): this\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n state\n unknown\n \n \n
\n\n \n
Returns
\n

this

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

Change the history state object when called with one parameter and return $location.\nThe state object is later passed to pushState or replaceState.

\n

This method is supported only in HTML5 mode and only in browsers supporting\nthe HTML5 History API methods such as pushState and replaceState. If you need to support\nolder browsers (like Android < 4.0), don't use this method.

\n\n
\n\n \n
\n\n\n\n \n\n\n
\n
\n\n\n" }