@uirouter/core
Version:
UI-Router Core: Framework agnostic, State-based routing for JavaScript Single Page Apps
351 lines (350 loc) • 14.6 kB
TypeScript
import { HookResult, TransitionOptions } from '../transition/interface';
import { Transition } from '../transition/transition';
import { HrefOptions, LazyLoadResult, StateDeclaration, StateOrName, TransitionPromise } from './interface';
import { StateObject } from './stateObject';
import { TargetState } from './targetState';
import { RawParams } from '../params/interface';
import { UIRouter } from '../router';
import { UIInjector } from '../interface';
import { StateParams } from '../params/stateParams';
export declare type OnInvalidCallback = (toState?: TargetState, fromState?: TargetState, injector?: UIInjector) => HookResult;
/**
* Provides services related to ui-router states.
*
* This API is located at `router.stateService` ([[UIRouter.stateService]])
*/
export declare class StateService {
private router;
/** @internal */
invalidCallbacks: OnInvalidCallback[];
/**
* The [[Transition]] currently in progress (or null)
*
* @deprecated This is a passthrough through to [[UIRouterGlobals.transition]]
*/
transition: Transition;
/**
* The latest successful state parameters
*
* @deprecated This is a passthrough through to [[UIRouterGlobals.params]]
*/
params: StateParams;
/**
* The current [[StateDeclaration]]
*
* @deprecated This is a passthrough through to [[UIRouterGlobals.current]]
*/
current: StateDeclaration;
/**
* The current [[StateObject]] (an internal API)
*
* @deprecated This is a passthrough through to [[UIRouterGlobals.$current]]
*/
$current: StateObject;
/** @internal */
constructor(/** @internal */ router: UIRouter);
/** @internal */
dispose(): void;
/**
* Handler for when [[transitionTo]] is called with an invalid state.
*
* Invokes the [[onInvalid]] callbacks, in natural order.
* Each callback's return value is checked in sequence until one of them returns an instance of TargetState.
* The results of the callbacks are wrapped in $q.when(), so the callbacks may return promises.
*
* If a callback returns an TargetState, then it is used as arguments to $state.transitionTo() and the result returned.
*
* @internal
*/
private _handleInvalidTargetState;
/**
* Registers an Invalid State handler
*
* Registers a [[OnInvalidCallback]] function to be invoked when [[StateService.transitionTo]]
* has been called with an invalid state reference parameter
*
* Example:
* ```js
* stateService.onInvalid(function(to, from, injector) {
* if (to.name() === 'foo') {
* let lazyLoader = injector.get('LazyLoadService');
* return lazyLoader.load('foo')
* .then(() => stateService.target('foo'));
* }
* });
* ```
*
* @param {function} callback invoked when the toState is invalid
* This function receives the (invalid) toState, the fromState, and an injector.
* The function may optionally return a [[TargetState]] or a Promise for a TargetState.
* If one is returned, it is treated as a redirect.
*
* @returns a function which deregisters the callback
*/
onInvalid(callback: OnInvalidCallback): Function;
/**
* Reloads the current state
*
* A method that force reloads the current state, or a partial state hierarchy.
* All resolves are re-resolved, and components reinstantiated.
*
* #### Example:
* ```js
* let app angular.module('app', ['ui.router']);
*
* app.controller('ctrl', function ($scope, $state) {
* $scope.reload = function(){
* $state.reload();
* }
* });
* ```
*
* Note: `reload()` is just an alias for:
*
* ```js
* $state.transitionTo($state.current, $state.params, {
* reload: true, inherit: false
* });
* ```
*
* @param reloadState A state name or a state object.
* If present, this state and all its children will be reloaded, but ancestors will not reload.
*
* #### Example:
* ```js
* //assuming app application consists of 3 states: 'contacts', 'contacts.detail', 'contacts.detail.item'
* //and current state is 'contacts.detail.item'
* let app angular.module('app', ['ui.router']);
*
* app.controller('ctrl', function ($scope, $state) {
* $scope.reload = function(){
* //will reload 'contact.detail' and nested 'contact.detail.item' states
* $state.reload('contact.detail');
* }
* });
* ```
*
* @returns A promise representing the state of the new transition. See [[StateService.go]]
*/
reload(reloadState?: StateOrName): Promise<StateObject>;
/**
* Transition to a different state and/or parameters
*
* Convenience method for transitioning to a new state.
*
* `$state.go` calls `$state.transitionTo` internally but automatically sets options to
* `{ location: true, inherit: true, relative: router.globals.$current, notify: true }`.
* This allows you to use either an absolute or relative `to` argument (because of `relative: router.globals.$current`).
* It also allows you to specify * only the parameters you'd like to update, while letting unspecified parameters
* inherit from the current parameter values (because of `inherit: true`).
*
* #### Example:
* ```js
* let app = angular.module('app', ['ui.router']);
*
* app.controller('ctrl', function ($scope, $state) {
* $scope.changeState = function () {
* $state.go('contact.detail');
* };
* });
* ```
*
* @param to Absolute state name, state object, or relative state path (relative to current state).
*
* Some examples:
*
* - `$state.go('contact.detail')` - will go to the `contact.detail` state
* - `$state.go('^')` - will go to the parent state
* - `$state.go('^.sibling')` - if current state is `home.child`, will go to the `home.sibling` state
* - `$state.go('.child.grandchild')` - if current state is home, will go to the `home.child.grandchild` state
*
* @param params A map of the parameters that will be sent to the state, will populate $stateParams.
*
* Any parameters that are not specified will be inherited from current parameter values (because of `inherit: true`).
* This allows, for example, going to a sibling state that shares parameters defined by a parent state.
*
* @param options Transition options
*
* @returns {promise} A promise representing the state of the new transition.
*/
go(to: StateOrName, params?: RawParams, options?: TransitionOptions): TransitionPromise;
/**
* Creates a [[TargetState]]
*
* This is a factory method for creating a TargetState
*
* This may be returned from a Transition Hook to redirect a transition, for example.
*/
target(identifier: StateOrName, params?: RawParams, options?: TransitionOptions): TargetState;
/** @internal */
private getCurrentPath;
/**
* Low-level method for transitioning to a new state.
*
* The [[go]] method (which uses `transitionTo` internally) is recommended in most situations.
*
* #### Example:
* ```js
* let app = angular.module('app', ['ui.router']);
*
* app.controller('ctrl', function ($scope, $state) {
* $scope.changeState = function () {
* $state.transitionTo('contact.detail');
* };
* });
* ```
*
* @param to State name or state object.
* @param toParams A map of the parameters that will be sent to the state,
* will populate $stateParams.
* @param options Transition options
*
* @returns A promise representing the state of the new transition. See [[go]]
*/
transitionTo(to: StateOrName, toParams?: RawParams, options?: TransitionOptions): TransitionPromise;
/**
* Checks if the current state *is* the provided state
*
* Similar to [[includes]] but only checks for the full state name.
* If params is supplied then it will be tested for strict equality against the current
* active params object, so all params must match with none missing and no extras.
*
* #### Example:
* ```js
* $state.$current.name = 'contacts.details.item';
*
* // absolute name
* $state.is('contact.details.item'); // returns true
* $state.is(contactDetailItemStateObject); // returns true
* ```
*
* // relative name (. and ^), typically from a template
* // E.g. from the 'contacts.details' template
* ```html
* <div ng-class="{highlighted: $state.is('.item')}">Item</div>
* ```
*
* @param stateOrName The state name (absolute or relative) or state object you'd like to check.
* @param params A param object, e.g. `{sectionId: section.id}`, that you'd like
* to test against the current active state.
* @param options An options object. The options are:
* - `relative`: If `stateOrName` is a relative state name and `options.relative` is set, .is will
* test relative to `options.relative` state (or name).
*
* @returns Returns true if it is the state.
*/
is(stateOrName: StateOrName, params?: RawParams, options?: {
relative?: StateOrName;
}): boolean;
/**
* Checks if the current state *includes* the provided state
*
* A method to determine if the current active state is equal to or is the child of the
* state stateName. If any params are passed then they will be tested for a match as well.
* Not all the parameters need to be passed, just the ones you'd like to test for equality.
*
* #### Example when `$state.$current.name === 'contacts.details.item'`
* ```js
* // Using partial names
* $state.includes("contacts"); // returns true
* $state.includes("contacts.details"); // returns true
* $state.includes("contacts.details.item"); // returns true
* $state.includes("contacts.list"); // returns false
* $state.includes("about"); // returns false
* ```
*
* #### Glob Examples when `* $state.$current.name === 'contacts.details.item.url'`:
* ```js
* $state.includes("*.details.*.*"); // returns true
* $state.includes("*.details.**"); // returns true
* $state.includes("**.item.**"); // returns true
* $state.includes("*.details.item.url"); // returns true
* $state.includes("*.details.*.url"); // returns true
* $state.includes("*.details.*"); // returns false
* $state.includes("item.**"); // returns false
* ```
*
* @param stateOrName A partial name, relative name, glob pattern,
* or state object to be searched for within the current state name.
* @param params A param object, e.g. `{sectionId: section.id}`,
* that you'd like to test against the current active state.
* @param options An options object. The options are:
* - `relative`: If `stateOrName` is a relative state name and `options.relative` is set, .is will
* test relative to `options.relative` state (or name).
*
* @returns {boolean} Returns true if it does include the state
*/
includes(stateOrName: StateOrName, params?: RawParams, options?: TransitionOptions): boolean;
/**
* Generates a URL for a state and parameters
*
* Returns the url for the given state populated with the given params.
*
* #### Example:
* ```js
* expect($state.href("about.person", { person: "bob" })).toEqual("/about/bob");
* ```
*
* @param stateOrName The state name or state object you'd like to generate a url from.
* @param params An object of parameter values to fill the state's required parameters.
* @param options Options object. The options are:
*
* @returns {string} compiled state url
*/
href(stateOrName: StateOrName, params?: RawParams, options?: HrefOptions): string;
/** @internal */
private _defaultErrorHandler;
/**
* Sets or gets the default [[transitionTo]] error handler.
*
* The error handler is called when a [[Transition]] is rejected or when any error occurred during the Transition.
* This includes errors caused by resolves and transition hooks.
*
* Note:
* This handler does not receive certain Transition rejections.
* Redirected and Ignored Transitions are not considered to be errors by [[StateService.transitionTo]].
*
* The built-in default error handler logs the error to the console.
*
* You can provide your own custom handler.
*
* #### Example:
* ```js
* stateService.defaultErrorHandler(function() {
* // Do not log transitionTo errors
* });
* ```
*
* @param handler a global error handler function
* @returns the current global error handler
*/
defaultErrorHandler(handler?: (error: any) => void): (error: any) => void;
/**
* Gets a registered [[StateDeclaration]] object
*
* Returns the state declaration object for any specific state, or for all registered states.
*
* @param stateOrName (absolute or relative) If provided, will only get the declaration object for the requested state.
* If not provided, returns an array of ALL states.
* @param base When `stateOrName` is a relative state reference (such as `.bar.baz`), the state will be retrieved relative to this state.
*
* @returns a [[StateDeclaration]] object (or array of all registered [[StateDeclaration]] objects.)
* @deprecated use [[StateRegistry.get]]
*/
get(stateOrName: StateOrName, base: StateOrName): StateDeclaration;
get(stateOrName: StateOrName): StateDeclaration;
get(): StateDeclaration[];
/**
* Lazy loads a state
*
* Explicitly runs a state's [[StateDeclaration.lazyLoad]] function.
*
* @param stateOrName the state that should be lazy loaded
* @param transition the optional Transition context to use (if the lazyLoad function requires an injector, etc)
* Note: If no transition is provided, a noop transition is created using the from the current state to the current state.
* This noop transition is not actually run.
*
* @returns a promise to lazy load
*/
lazyLoad(stateOrName: StateOrName, transition?: Transition): Promise<LazyLoadResult>;
}