--@ui-router——$state服务原版详解

$state

service in module ui.router.state

Description

$state service is responsible for representing states as well as transitioning between them. It also provides interfaces to ask for current state or even states you're coming from.

Dependencies

• $rootScope
• $q
• $view
• $injector
• $resolve
• $stateParams
• $urlRouter

Methods

• get(stateOrName, context)

  Returns the state configuration object for any specific state or all states.

  Parameters

  Param	Type	Details
  stateOrName (optional)	stringobject	(absolute or relative) If provided, will only get the config for the requested state. If not provided, returns an array of ALL state configs.
  context (optional)	stringobject	When stateOrName is a relative state reference, the state will be retrieved relative to context.

  Returns

  Object|Array

  State configuration object or array of all objects.

• go(to, params, options)

  Convenience method for transitioning to a new state. $state.go calls $state.transitionTo internally but automatically sets options to { location: true, inherit: true, relative: $state.$current, notify: true }. This allows you to easily use an absolute or relative to path and specify only the parameters you'd like to update (while letting unspecified parameters inherit from the currently active ancestor states).

  Parameters

  Param	Type	Details
  to	string	Absolute state name or relative state path. Some examples: $state.go('contact.detail') - will go to the contact.detail state $state.go('^') - will go to a parent state $state.go('^.sibling') - will go to a sibling state $state.go('.child.grandchild') - will go to grandchild state
  params (optional)	object	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 currently defined parameters. This allows, for example, going to a sibling state that shares parameters specified in a parent state. Parameter inheritance only works between common ancestor states, I.e. transitioning to a sibling will get you the parameters for all parents, transitioning to a child will get you all current parameters, etc.
  options (optional)	object	Options object. The options are: location - {boolean=true|string=} - If true will update the url in the location bar, if false will not. If string, must be "replace", which will update url and also replace last history record. inherit - {boolean=true}, If true will inherit url parameters from current url. relative - {object=$state.$current}, When transitioning with relative path (e.g '^'), defines which state to be relative from. notify - {boolean=true}, If true will broadcast $stateChangeStart and $stateChangeSuccess events. reload (v0.2.5) - {boolean=false}, If true will force transition even if the state or params have not changed, aka a reload of the same state. It differs from reloadOnSearch because you'd use this when you want to force a reload when everything is the same, including search params.

  Returns

  promise

  A promise representing the state of the new transition. Possible success values: $state.current Possible rejection values: 'transition superseded' - when a newer transition has been started after this one 'transition prevented' - when event.preventDefault() has been called in a $stateChangeStart listener 'transition aborted' - when event.preventDefault() has been called in a $stateNotFound listener or when a $stateNotFound event.retry promise errors. 'transition failed' - when a state has been unsuccessfully found after 2 tries. resolve error - when an error has occurred with a resolve

  Example

  1. var app = angular.module('app', ['ui.router']);
  2.  
  3. app.controller('ctrl', function ($scope, $state) {
  4. $scope.changeState = function () {
  5. $state.go('contact.detail');
  6. };
  7. });

  

• href(stateOrName, params, options)

  A url generation method that returns the compiled url for the given state populated with the given params.

  Parameters

  Param	Type	Details
  stateOrName	stringobject	The state name or state object you'd like to generate a url from.
  params (optional)	object	An object of parameter values to fill the state's required parameters.
  options (optional)	object	Options object. The options are: lossy - {boolean=true} - If true, and if there is no url associated with the state provided in the first parameter, then the constructed href url will be built from the first navigable ancestor (aka ancestor with a valid url). inherit - {boolean=true}, If true will inherit url parameters from current url. relative - {object=$state.$current}, When transitioning with relative path (e.g '^'), defines which state to be relative from. absolute - {boolean=false}, If true will generate an absolute url, e.g. "http://www.example.com/fullurl".

  Returns

  string

  compiled state url

  Example

  1. expect($state.href("about.person", { person: "bob" })).toEqual("/about/bob");

• includes(stateOrName, params, options)

  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.

  Parameters

  Param	Type	Details
  stateOrName	string	A partial name, relative name, or glob pattern to be searched for within the current state name.
  params (optional)	object	A param object, e.g. {sectionId: section.id}, that you'd like to test against the current active state.
  options (optional)	object	An options object. The options are: relative - {string|object=} - If stateOrName is a relative state reference and options.relative is set, .includes will test relative to options.relative state (or name).

  Returns

  boolean

  Returns true if it does include the state

  Example

  Partial and relative names

  1. $state.$current.name = 'contacts.details.item';
  2.  
  3. // Using partial names
  4. $state.includes("contacts"); // returns true
  5. $state.includes("contacts.details"); // returns true
  6. $state.includes("contacts.details.item"); // returns true
  7. $state.includes("contacts.list"); // returns false
  8. $state.includes("about"); // returns false
  9.  
  10. // Using relative names (. and ^), typically from a template
  11. // E.g. from the 'contacts.details' template
  12. <div ng-class="{highlighted: $state.includes('.item')}">Item</div>

  Basic globbing patterns

  1. $state.$current.name = 'contacts.details.item.url';
  2.  
  3. $state.includes("*.details.*.*"); // returns true
  4. $state.includes("*.details.**"); // returns true
  5. $state.includes("**.item.**"); // returns true
  6. $state.includes("*.details.item.url"); // returns true
  7. $state.includes("*.details.*.url"); // returns true
  8. $state.includes("*.details.*"); // returns false
  9. $state.includes("item.**"); // returns false

• is(stateOrName, params, options)

  Similar to $state.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.

  Parameters

  Param	Type	Details
  stateOrName	stringobject	The state name (absolute or relative) or state object you'd like to check.
  params (optional)	object	A param object, e.g. {sectionId: section.id}, that you'd like to test against the current active state.
  options (optional)	object	An options object. The options are: relative - {string|object} - 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 is the state.

  Example

  1. $state.$current.name = 'contacts.details.item';
  2.  
  3. // absolute name
  4. $state.is('contact.details.item'); // returns true
  5. $state.is(contactDetailItemStateObject); // returns true
  6.  
  7. // relative name (. and ^), typically from a template
  8. // E.g. from the 'contacts.details' template
  9. <div ng-class="{highlighted: $state.is('.item')}">Item</div>

• reload(state)

  A method that force reloads the current state. All resolves are re-resolved, controllers reinstantiated, and events re-fired.

  Parameters

  Param	Type	Details
  state (optional)	string=object	A state name or a state object, which is the root of the resolves to be re-resolved.

  Returns

  promise

  A promise representing the state of the new transition. See $state.go.

  Example

  1. //assuming app application consists of 3 states: 'contacts', 'contacts.detail', 'contacts.detail.item'
  2. //and current state is 'contacts.detail.item'
  3. var app angular.module('app', ['ui.router']);
  4.  
  5. app.controller('ctrl', function ($scope, $state) {
  6. $scope.reload = function(){
  7. //will reload 'contact.detail' and 'contact.detail.item' states
  8. $state.reload('contact.detail');
  9. }
  10. });

  reload() is just an alias for:

  1. $state.transitionTo($state.current, $stateParams, {
  2. reload: true, inherit: false, notify: true
  3. });

• transitionTo(to, toParams, options)

  Low-level method for transitioning to a new state. $state.go uses transitionTo internally. $state.go is recommended in most situations.

  Parameters

  Param	Type	Details
  to	string	State name.
  toParams (optional)	object	A map of the parameters that will be sent to the state, will populate $stateParams.
  options (optional)	object	Options object. The options are: location - {boolean=true|string=} - If true will update the url in the location bar, if false will not. If string, must be "replace", which will update url and also replace last history record. inherit - {boolean=false}, If true will inherit url parameters from current url. relative - {object=}, When transitioning with relative path (e.g '^'), defines which state to be relative from. notify - {boolean=true}, If true will broadcast $stateChangeStart and $stateChangeSuccess events. reload (v0.2.5) - {boolean=false|string=|object=}, If true will force transition even if the state or params have not changed, aka a reload of the same state. It differs from reloadOnSearch because you'd use this when you want to force a reload when everything is the same, including search params. if String, then will reload the state with the name given in reload, and any children. if Object, then a stateObj is expected, will reload the state found in stateObj, and any children.

  Returns

  promise

  A promise representing the state of the new transition. See $state.go.

  Example

  1. var app = angular.module('app', ['ui.router']);
  2.  
  3. app.controller('ctrl', function ($scope, $state) {
  4. $scope.changeState = function () {
  5. $state.transitionTo('contact.detail');
  6. };
  7. });

Properties

• params

  A param object, e.g. {sectionId: section.id)}, that you'd like to test against the current active state.

• current

  A reference to the state's config object. However you passed it in. Useful for accessing custom data.

• transition

  Currently pending transition. A promise that'll resolve or reject.

Events

• $stateChangeError

  Fired when an error occurs during transition. It's important to note that if you have any errors in your resolve functions (javascript errors, non-existent services, etc) they will not throw traditionally. You must listen for this $stateChangeError event to catch ALL errors.

  Type:

  broadcast

  Target:

  root scope

  Parameters

  Param	Type	Details
  event	Object	Event object.
  toState	State	The state being transitioned to.
  toParams	Object	The params supplied to the toState.
  fromState	State	The current state, pre-transition.
  fromParams	Object	The params supplied to the fromState.
  error	Error	The resolve error object.

• $stateChangeStart

  Fired when the state transition begins. You can use event.preventDefault() to prevent the transition from happening and then the transition promise will be rejected with a 'transition prevented' value.

  Type:

  broadcast

  Target:

  root scope

  Parameters

  Param	Type	Details
  event	Object	Event object.
  toState	State	The state being transitioned to.
  toParams	Object	The params supplied to the toState.
  fromState	State	The current state, pre-transition.
  fromParams	Object	The params supplied to the fromState.

  Example

  1. $rootScope.$on('$stateChangeStart',
  2. function(event, toState, toParams, fromState, fromParams){
  3. event.preventDefault();
  4. // transitionTo() promise will be rejected with
  5. // a 'transition prevented' error
  6. })

• $stateChangeSuccess

  Fired once the state transition is complete.

  Type:

  broadcast

  Target:

  root scope

  Parameters

  Param	Type	Details
  event	Object	Event object.
  toState	State	The state being transitioned to.
  toParams	Object	The params supplied to the toState.
  fromState	State	The current state, pre-transition.
  fromParams	Object	The params supplied to the fromState.

• $stateNotFound

  Fired when a requested state cannot be found using the provided state name during transition. The event is broadcast allowing any handlers a single chance to deal with the error (usually by lazy-loading the unfound state). A special unfoundState object is passed to the listener handler, you can see its three properties in the example. You can use event.preventDefault() to abort the transition and the promise returned from go will be rejected with a 'transition aborted' value.

  Type:

  broadcast

  Target:

  root scope

  Parameters

  Param	Type	Details
  event	Object	Event object.
  unfoundState	Object	Unfound State information. Contains: to, toParams, options properties.
  fromState	State	Current state object.
  fromParams	Object	Current state params.

  Example

  1. // somewhere, assume lazy.state has not been defined
  2. $state.go("lazy.state", {a:1, b:2}, {inherit:false});
  3.  
  4. // somewhere else
  5. $scope.$on('$stateNotFound',
  6. function(event, unfoundState, fromState, fromParams){
  7. console.log(unfoundState.to); // "lazy.state"
  8. console.log(unfoundState.toParams); // {a:1, b:2}
  9. console.log(unfoundState.options); // {inherit:false} + default options
  10. })