Dojo 路由

路由

dojo/framework/src/routing/README.md

commit b682b06ace25eea86d190e56dd81042565b35ed1

Dojo 应用程序的路由

• 路由

  • Features

    • Route 配置

      • 路径参数

    • Router

      • History Managers

        • Hash History
        • State History
        • Memory History
      • Outlet Event
    • Router Context Injection

    • Outlets

      • Global Error Outlet
    • Link
    • ActiveLink

Features

部件（Widget）是 Dojo 应用程序的基本概念，所以 Dojo 路由提供了一组与应用程序中的部件直接集成的组件。这些组件能将部件注册到路由上，且不须要掌握路由相关的任何知识。Dojo 应用程序中的路由包括如下内容：

• Outlet 部件封装器指定 route 的 outlet key 和表现视图之间的映射关系
• Route 配置，用于在路径和 outlet key 之间创建映射关系
• Router 基于当前路径解析 Route
• History 提供器负责向 Router 通知路径的更改
• Registry 将 Router 注入到部件系统中

Route 配置

RouteConfig 用于注册应用程序的路由，它定义了路由的 path、关联的 outlet 以及嵌套的子 RouteConfig。一个完整的路由就是由递归嵌套的 Route 构成的。

路由配置示例：

import { RouteConfig } from '@dojo/framework/routing/interfaces';

const config: RouteConfig[] = [
    {
        path: 'foo',
        outlet: 'root',
        children: [
            {
                path: 'bar',
                outlet: 'bar'
            },
            {
                path: 'baz',
                outlet: 'baz',
                children: [
                    {
                        path: 'qux',
                        outlet: 'qux'
                    }
                ]
            }
        ]
    }
];

此配置将注册如下路由和 outlet：

Route	Outlet
/foo	root
/foo/bar	bar
/foo/baz	baz
/foo/baz/qux	qux

路径参数

在 RouteConfig 的 path 属性中，在 path 的值中使用大括号可定义路径参数。 Parameters will match any segment and the value of that segment is made available to matching outlets via the mapParams Outlet options. The parameters provided to child outlets will include any parameters from matching parent routes.

const config = [
    {
        path: 'foo/{foo}',
        outlet: 'foo'
    }
];

具备路径参数的路由，可为每一个路由指定默认的参数。当用没有指定参数的 outlet 生成一个连接，或者当前路由中不存在参数时，可以使用这些默认参数值。

const config = [
    {
        path: 'foo/{foo}',
        outlet: 'foo',
        defaultParams: {
            foo: 'bar'
        }
    }
];

可以使用可选的配属属性 defaultRoute 来设置默认路由，若是当前路由没有匹配到已注册的路由，就使用此路由。

const config = [
    {
        path: 'foo/{foo}',
        outlet: 'foo',
        defaultRoute: true
    }
];

Router

Router 用于注册 route 配置，将 route 配置信息传入 Router 的构造函数便可：

const router = new Router(config);

会自动为 router 注册一个 HashHistory 历史管理器（history manager）。可在第二个参数中传入其余历史管理器。

import { MemoryHistory } from '@dojo/framework/routing/MemoryHistory';

const router = new Router(config, { HistoryManager: MemoryHistory });

使用应用程序路由配置建立路由后，须要让应用程序中的全部组件可以使用这些路由。这是经过使用 @dojo/framework/widget-core/Registry 中的 Registry，定义一个将 invalidator 链接到 router 的 nav 事件的注入器，并返回 router 实例实现的。这里使用 key 来定义注入器，路由器的默认 key 值为 router。

import { Registry } from '@dojo/framework/widget-core/Registry';
import { Injector } from '@dojo/framework/widget-core/Injector';

const registry = new Registry();

// 假设咱们有一个可用的 router 实例
registry.defineInjector('router', () => {
    router.on('nav', () => invalidator());
    return () => router;
};

注意： 路由提供了 注册 router 的快捷方法。

最后，为了让应用程序中的全部部件都能使用 registry，须要将其传给 vdom renderer 的 .mount() 方法。

const r = renderer(() => v(App, {}));
r.mount({ registry });

History Managers

路由自带三个历史管理器，用于监视和更改导航状态：HashHistory、StateHistory 和 MemoryHistory。默认使用 HashHistory，可是可在建立 Router 时传入不一样的 HistoryManager。

const router = new Router(config, { HistoryManager: MemoryHistory });

Hash History

基于哈希的管理器使用片断标识符（fragment identifier）来存储导航状态，是 @dojo/framework/routing 中的默认管理器。

import { Router } from '@dojo/framework/routing/Router';
import { HashHistory } from '@dojo/framework/routing/history/HashHistory';

const router = new Router(config, { HistoryManager: HashHistory });

历史管理器有 current、set(path: string) 和 prefix(path: string) 三个API。HashHistory 类假定全局对象是浏览器的 window 对象，但能够显式提供对象。管理器使用 window.location.hash 和 hashchange 事件的事件监听器。current 访问器返回当前路径，不带 # 前缀。

State History

基于状态的历史管理器使用浏览器的 history API：pushState() 和 replaceState()，来添加和修改历史纪录。状态历史管理器须要服务器端支持才能有效工做。

Memory History

MemoryHistory 不依赖任何浏览器 API，而是保持其自身的内部路径状态。不要在生产应用程序中使用它，但在测试路由时却颇有用。

import { Router } from '@dojo/framework/routing/Router';
import { MemoryHistory } from '@dojo/framework/routing/history/MemoryHistory';

const router = new Router(config, { HistoryManager: MemoryHistory });

Outlet Event

当每次进入或离开 outlet 时，都会触发 router 实例的 outlet 事件。outlet 上下文、enter 或 exit 操做都会传给事件处理函数。

router.on('outlet', ({ outlet, action }) => {
    if (action === 'enter') {
        if (outlet.id === 'my-outlet') {
            // do something, perhaps fetch data or set state
        }
    }
});

Router Context Injection

RouterInjector 模块导出一个帮助函数 registerRouterInjector，它组合了 Router 实例的实例化，注册 router 配置信息和为提供的 registry 定义注入器，而后返回 router 实例。

import { Registry } from '@dojo/framework/widget-core/Registry';
import { registerRouterInjector } from '@dojo/framework/routing/RoutingInjector';

const registry = new Registry();
const router = registerRouterInjector(config, registry);

可以使用 RouterInjectiorOptions 覆盖默认值：

import { Registry } from '@dojo/framework/widget-core/Registry';
import { registerRouterInjector } from '@dojo/framework/routing/RoutingInjector';
import { MemoryHistory } from './history/MemoryHistory';

const registry = new Registry();
const history = new MemoryHistory();

const router = registerRouterInjector(config, registry, { history, key: 'custom-router-key' });

Outlets

路由集成的一个基本概念是 outlet，它是与注册的应用程序 route 关联的惟一标识符。Outlet 是一个标准的 dojo 部件，可在应用程序的任何地方使用。Outlet 部件有一个精简的 API：

• id: 匹配时执行 renderer 的 outlet 标识。
• renderer: 当 outlet 匹配时调用的渲染函数。
• routerKey (可选): 在 registry 中定义路由时使用的 key - 默认为 router。

接收渲染的 outlet 名称和一个 renderer 函数，当 outlet 匹配时，该函数返回要渲染的 DNode。

render() {
    return v('div', [
        w(Outlet, { id: 'my-outlet', renderer: () => {
            return w(MyWidget, {});
        }})
    ])
}

可为 renderer 函数传入 MatchDetails 参数，该参数提供路由专有信息，用于肯定要渲染的内容和计算传入部件的属性值。

interface MatchDetails {
    /**
     * Query params from the matching route for the outlet
     */
    queryParams: Params;

    /**
     * Params from the matching route for the outlet
     */
    params: Params;

    /**
     * Match type of the route for the outlet, either `index`, `partial` or `error`
     */
    type: MatchType;

    /**
     * The router instance
     */
    router: RouterInterface;

    /**
     * Function returns true if the outlet match was an `error` type
     */
    isError(): boolean;

    /**
     * Function returns true if the outlet match was an `index` type
     */
    isExact(): boolean;
}

render() {
    return v('div', [
        w(Outlet, { id: 'my-outlet', renderer: (matchDetails: MatchDetails) => {
            if (matchDetails.isError()) {
                return w(ErrorWidget, {});
            }
            if (matchDetails.isExact()) {
                return w(IndexWidget, { id: matchDetails.params.id });
            }
            return w(OtherWidget, { id: matchDetails.params.id });
        }})
    ])
}

Global Error Outlet

只要注册了一个 error 匹配类型，就会自动为匹配的 outlet 添加一个全局 outlet，名为 errorOutlet。这个 outlet 用于为任何未知的路由渲染一个部件。

render() {
    return w(Outlet, {
        id: 'errorOutlet',
        renderer: (matchDetails: MatchDetails) => {
            return w(ErrorWidget, properties);
        }
    });
}

Link

Link 组件是对 DOM 节点 a 的封装，容许用户为建立的连接指定一个 outlet。也能够经过将 isOutlet 属性值设置为 false 来使用静态路由。

若是生成的连接须要指定在 route 中不存在的路径或查询参数，可以使用 params 属性传入。

import { Link } from '@dojo/framework/routing/Link';

render() {
    return v('div', [
        w(Link, { to: 'foo', params: { foo: 'bar' }}, [ 'Link Text' ]),
        w(Link, { to: '#/static-route', isOutlet: false, [ 'Other Link Text' ])
    ]);
}

全部标准的 VNodeProperties 均可用于 Link 组件，由于最终是使用 @dojo/framework/widget-core 中的 v() 来建立一个 a 元素。

ActiveLink

ActiveLink 组件是对 Link 组件的封装，若是连接处于激活状态，则能够为 a 节点设置样式类。

import { ActiveLink } from '@dojo/framework/routing/ActiveLink';

render() {
    return v('div', [
        w(ActiveLink, { to: 'foo', params: { foo: 'bar' }, activeClasses: [ 'link-active' ]}, [ 'Link Text' ])
    ]);
}