vue-router3 源码注释系列 /src/create-matcher.js

/* @flow */

import type VueRouter from './index'
import {
    resolvePath } from './util/path'
import {
    assert, warn } from './util/warn'
import {
    createRoute } from './util/route'
import {
    fillParams } from './util/params'
import {
    createRouteMap } from './create-route-map'
import {
    normalizeLocation } from './util/location'
import {
    decode } from './util/query'

export type Matcher = {
   
  match: (
    raw: RawLocation,
    current?: Route,
    redirectedFrom?: Location
  ) => Route,
  addRoutes: (routes: Array<RouteConfig>) => void,
  addRoute: (
    parentNameOrRoute: string | RouteConfig,
    route?: RouteConfig
  ) => void,
  getRoutes: () => Array<RouteRecord>,
}

/*
  createMatcher
  返回对象为：{
      match,     //根据 raw 来匹配对应的 record，并创建一个新的 route 并返回。
      addRoute,  //添加一条 route 路由数据。
      getRoutes, //获取所有的 route config 转化的 record 数据对象。
      addRoutes, //批量添加多条 route 路由数据。
  }
 */
export function createMatcher(
  routes: Array<RouteConfig>,
  router: VueRouter
): Matcher {
   
  /**
   * 根据 routes 数据生成 route map 对象。
   * route map 的三个对象: {
        pathList, //记录所有 route 的完整的绝对路径 path。
        pathMap,  //记录所有的 router record 对象，以 path 作为 key 进行存储。
        nameMap   //记录所有的 router record 对象，以 name 作为 key 就行存储。
   * }
   */
  const {
    pathList, pathMap, nameMap } = createRouteMap(routes)

  /*

    addRoutes() 批量新增 route 路由数据。
    当 router.addRoutes(xxx) 的时候，就会调用 matchers.addRoutes() 方法。
    需要注意的是：通过 addRoutes 去添加 routes。
      (1) 如果旧的 path 存在，则新的会被忽略掉。
      (2) 旧的 path 是不会被移除的。 
  */
  function addRoutes(routes) {
   
    createRouteMap(routes, pathList, pathMap, nameMap)
  }

  /*
    addRoute()  添加一条 route 路由数据。
    两种传参方式：
     (1) matchers.add( parentOrRoute ) // 此时参数就是要新增的 route 对象。
     (2) matchers.add( parentOrRoute, route ) //此时第一个参数是 parent route 的 name，用于查找 parent router record 对象。 
  */
  function addRoute(parentOrRoute, route) {
   
    //如果 parentOrRoute 是字符串，则当作 name，在 nameMap 中查找对应的 router record 对象。
    //如果 parentOrRoute 是对象，则当作要被新增的 route 数据对象。
    const parent =
      typeof parentOrRoute !== 'object' ? nameMap[parentOrRoute] : undefined

    //如果 route 存在，则使用 route 作为路由数据源对象。
    //如果 parentOrRoute 是字符串，则找到父 router record 对象。
    //  当然也可能 parent 为 undefined，则 route 对应的 router record 对象会被添加到 "/+${route.path}" 下。
    createRouteMap([route || parentOrRoute], pathList, pathMap, nameMap, parent)

    /*
       对于 parent router record 对象，如果存在 alias，则需要将所有的 alias，包装成 route。
       保证 /parent-alias/child-path 也能够正确访问到子路由。
    */
    if (parent && parent.alias.length) {
   
      createRouteMap(
        //针对 parent 存在 alias 的情形，需要将 alias 数据包装成 route，以保证所有包含别名路径的子路由，也能正确访问，
        parent.alias.map((alias) => ({
    path: alias, children: [route] })),
        pathList,
        pathMap,
        nameMap,
        parent
      )
    }
  }

  /*
    getRoutes()
    返回一个数组，包含所有的 router record 对象。（包含所有的 alias 生成的 router record 对象。）
  */
  function getRoutes() {