@types/ember__routing
Version:
TypeScript definitions for @ember/routing
363 lines (347 loc) • 13.7 kB
TypeScript
// eslint-disable-next-line @definitelytyped/no-self-import
import RouteInfo, { RouteInfoWithAttributes } from "@ember/routing/route-info";
// eslint-disable-next-line @definitelytyped/no-self-import
import Transition from "@ember/routing/transition";
import Service from "@ember/service";
// eslint-disable-next-line @definitelytyped/strict-export-declare-modifiers
type RouteModel = object | string | number;
// https://emberjs.com/api/ember/release/classes/RouterService
/**
* The Router service is the public API that provides component/view layer access to the router.
*/
export default class RouterService extends Service {
//
/**
* A `RouteInfo` that represents the current leaf route.
* It is guaranteed to change whenever a route transition happens
* (even when that transition only changes parameters and doesn't change the active route)
*/
readonly currentRoute: RouteInfo;
/**
* Name of the current route.
* This property represent the logical name of the route,
* which is comma separated.
* For the following router:
* ```app/router.js
* Router.map(function() {
* this.route('about');
* this.route('blog', function () {
* this.route('post', { path: ':post_id' });
* });
* });
* ```
* It will return:
* * `index` when you visit `/`
* * `about` when you visit `/about`
* * `blog.index` when you visit `/blog`
* * `blog.post` when you visit `/blog/some-post-id`
*/
readonly currentRouteName: string;
//
/**
* Current URL for the application.
* This property represent the URL path for this route.
* For the following router:
* ```app/router.js
* Router.map(function() {
* this.route('about');
* this.route('blog', function () {
* this.route('post', { path: ':post_id' });
* });
* });
* ```
* It will return:
* * `/` when you visit `/`
* * `/about` when you visit `/about`
* * `/blog` when you visit `/blog`
* * `/blog/some-post-id` when you visit `/blog/some-post-id`
*/
readonly currentURL: string;
/**
* The `rootURL` property represents the URL of the root of
* the application, '/' by default.
* This prefix is assumed on all routes defined on this app.
* If you change the `rootURL` in your environment configuration
* like so:
* ```config/environment.js
* 'use strict';
* module.exports = function(environment) {
* let ENV = {
* modulePrefix: 'router-service',
* environment,
* rootURL: '/my-root',
* …
* }
* ]
* ```
* This property will return `/my-root`.
*/
readonly rootURL: string;
/**
* Determines whether a route is active.
*
* @param routeName the name of the route
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route
* @param options optional hash with a queryParams property containing a
* mapping of query parameters
*/
isActive(routeName: string, options?: { queryParams: object }): boolean;
isActive(
routeName: string,
models: RouteModel,
options?: { queryParams: object },
): boolean;
isActive(
routeName: string,
modelsA: RouteModel,
modelsB: RouteModel,
options?: { queryParams: object },
): boolean;
isActive(
routeName: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
options?: { queryParams: object },
): boolean;
isActive(
routeName: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
modelsD: RouteModel,
options?: { queryParams: object },
): boolean;
// https://emberjs.com/api/ember/4.0/classes/RouterService/methods/isActive?anchor=replaceWith
/**
* Transition into another route while replacing the current URL, if
* possible. The route may be either a single route or route path.
*
* @param routeNameOrUrl the name of the route or a URL
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @param options optional hash with a queryParams property
* containing a mapping of query parameters
* @returns the Transition object associated with this attempted transition
*/
replaceWith(
routeNameOrUrl: string,
options?: { queryParams: object },
): Transition;
replaceWith(
routeNameOrUrl: string,
models: RouteModel,
options?: { queryParams: object },
): Transition;
replaceWith(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
options?: { queryParams: object },
): Transition;
replaceWith(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
options?: { queryParams: object },
): Transition;
replaceWith(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
modelsD: RouteModel,
options?: { queryParams: object },
): Transition;
// https://emberjs.com/api/ember/release/classes/RouterService/methods/isActive?anchor=transitionTo
/**
* Transition the application into another route. The route may
* be either a single route or route path:
*
* See [transitionTo](https://api.emberjs.com/ember/release/classes/Route/methods/transitionTo?anchor=transitionTo) for more info.
*
* Calling `transitionTo` from the Router service will cause default query parameter values to be included in the URL.
* This behavior is different from calling `transitionTo` on a route or `transitionToRoute` on a controller.
* See the [Router Service RFC](https://github.com/emberjs/rfcs/blob/master/text/0095-router-service.md#query-parameter-semantics) for more info.
*
* In the following example we use the Router service to navigate to a route with a
* specific model from a Component.
*
* ```app/components/example.js
* import Component from '@glimmer/component';
* import { action } from '@ember/object';
* import { inject as service } from '@ember/service';
*
* export default class extends Component {
* @service router;
*
* @action
* goToComments(post) {
* this.router.transitionTo('comments', post);
* }
* }
* ```
*
* @param routeNameOrUrl the name of the route or a URL
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @param options optional hash with a queryParams property
* containing a mapping of query parameters. May be
* supplied as the only parameter to trigger a
* query-parameter-only transition.
* @returns the Transition object associated with this attempted transition
*/
transitionTo(
routeNameOrUrl: string,
options?: { queryParams: object },
): Transition;
transitionTo(
routeNameOrUrl: string,
models: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(
routeNameOrUrl: string,
modelsA: RouteModel,
modelsB: RouteModel,
modelsC: RouteModel,
modelsD: RouteModel,
options?: { queryParams: object },
): Transition;
transitionTo(options: { queryParams: object }): Transition;
// https://emberjs.com/api/ember/4.3.0/classes/RouterService/methods/isActive?anchor=urlFor
/**
* Generate a URL based on the supplied route name.
*
* @param routeName the name of the route or a URL
* @param models the model(s) or identifier(s) to be used while
* transitioning to the route.
* @param options optional hash with a queryParams property containing
* a mapping of query parameters
* @returns the string representing the generated URL
*/
urlFor(routeName: string, ...args: RouteModel[] | [...RouteModel[], { queryParams: object }]): string;
// https://api.emberjs.com/ember/3.6/classes/RouterService/events/routeDidChange?anchor=routeDidChange
/**
* Register a callback for an event.
*
* The `routeWillChange` event is fired at the beginning of any attempted transition with a `Transition` object as the sole argument.
* This action can be used for aborting, redirecting, or decorating the transition from the currently active routes.
*
* The `routeDidChange` event only fires once a transition has settled.
* This includes aborts and error substates.
* Like the `routeWillChange` event it recieves a `Transition` as the sole argument.
*
* @param name the name of the event
* @param callback the callback to execute
*/
on(
name: "routeDidChange" | "routeWillChange",
callback: (transition: Transition) => void,
): RouterService;
// https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=off
/**
* Removes a callback for an event.
*
* The `routeWillChange` event is fired at the beginning of any attempted transition with a `Transition` object as the sole argument.
* This action can be used for aborting, redirecting, or decorating the transition from the currently active routes.
*
* The `routeDidChange` event only fires once a transition has settled.
* This includes aborts and error substates.
*
* @param name the name of the event 'routeWillChange' | 'routeDidChange'
* @param callback the callback to remove
*/
off(
name: "routeDidChange" | "routeWillChange",
callback: (transition: Transition) => void,
): RouterService;
/**
* https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=has
*
* Checks to see if object has any subscriptions for named event.
*
* @param name
*/
has(name: string): boolean;
/**
* https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=one
*
* Subscribes a function to a named event and then cancels the subscription after the first time the
* event is triggered. It is good to use one when you only care about the first time an event has taken place.
*
* @param name the name of the event
* @param callback the callback to execute
*/
one(
name: "routeDidChange" | "routeWillChange",
callback: (transition: Transition) => void,
): RouterService;
/**
* https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=trigger
*
* Triggers a named event for the object.
* Any additional arguments will be passed as parameters to the functions that are subscribed to the event.
*
* @param name the name of the event
* @param args arguments to pass to the event
*/
trigger(
name: string,
args: any,
): void;
/**
* Takes a string URL and returns a `RouteInfo` for the leafmost route represented
* by the URL. Returns `null` if the URL is not recognized. This method expects to
* receive the actual URL as seen by the browser including the app's `rootURL`.
* See [RouteInfo](/ember/release/classes/RouteInfo) for more info.
* In the following example `recognize` is used to verify if a path belongs to our
* application before transitioning to it.
* ```
* import Component from '@ember/component';
* import { inject as service } from '@ember/service';
* export default class extends Component {
* @service router;
* path = '/';
* click() {
* if (this.router.recognize(this.path)) {
* this.router.transitionTo(this.path);
* }
* }
* }
* ```
*/
recognize(url: string): RouteInfo;
/**
* Takes a string URL and returns a promise that resolves to a
* `RouteInfoWithAttributes` for the leafmost route represented by the URL.
* The promise rejects if the URL is not recognized or an unhandled exception
* is encountered. This method expects to receive the actual URL as seen by
* the browser including the app's `rootURL`.
*/
recognizeAndLoad(url: string): RouteInfoWithAttributes;
/**
* Refreshes all currently active routes, doing a full transition.
* If a route name is provided and refers to a currently active route,
* it will refresh only that route and its descendents.
* Returns a promise that will be resolved once the refresh is complete.
* All resetController, beforeModel, model, afterModel, redirect, and setupController
* hooks will be called again. You will get new data from the model hook.
*/
refresh(pivotRouteName?: string): Transition;
}