路由系统 #10

aui · 2022-02-07T02:39:15Z

aui
Feb 7, 2022
Maintainer

开始时间: 2022-02-03
实施: https://github.com/growing-web/web-router/tree/dev

描述

Web Router 是一个由 Growing Web 提出的路由技术标准，它定义了路由配置与接口的标准实现。

Web Router 路由系统在 Growing Web 架构中的位置：

            Start
              ▼
     ┌────────┴───────┐
     │ Backend Router │
     └────────┬───────┘
              ▼
       ┌──────┴─────┐
       │ Web Router │ 
       └──────┬─────┘
              ▼
  ┌───────────┴───────────┐
  │ Application Container │
  │      (Web Widget)     │
  └───────────┬───────────┘
              ▼
┌─────────────┴──────────────┐
│ Front-End Framework Router │
│ (React, Vue, Angular, ...) │
└─────────────┬──────────────┘
              ▼
       ┌──────┴──────┐
       │ Application │
       └──────┬──────┘
              ▼
             End

动机

技术栈中立

如今，越来越多的 Web 框架使用了基于浏览器的路由技术来提升用户体验以及组件解耦，通常这样的路由的实现会与具体的 Web 框架绑在一起，这样的好处是能够提供高效的开发体验，但是应用规模变得庞大后，这样的设计将会增加技术升级的难度，也让不同技术栈与版本的应用集成变得困难。技术栈中立的路由系统将只关注最本质的东西，这样应用在需要的时候可以从局部开始升级技术栈，而不影响其他模块。

可拆卸

一个“微应用”应当工作在路由驱动的架构中，也能够在页面中一个小区块中工作，因此路由系统在“微前端”架构中应当是可选的，它允许从大系统中拆卸为独立的部分。

可组合

路由系统是一个基础的服务，它应当充当好桥梁的角色，将更多的服务交给其他工具完成，例如元素加载器、应用容器、其他前端框架的路由系统等。

基本示例

路由

Web Router 使用 HTML 标签来配置路由。

<script type="routemap">
{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    }   
  ]
}
</script>

<web-router></web-router>

上述例子中，<script type="routemap"> 为路由的配置，<web-router> 元素为路由的出口。

以如下配置举例：

{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    },
    {
      "path": "news",
      "element": "examples-news"
    },
    {
      "path": "news/:id",
      "element": "examples-news-detail",
      "attributes": {
        "data-id": "isdkkD"
      }
    }   
  ]
}

当访问 /news 的时候，将会创建匹配的元素。

<web-router>
  <examples-news routepattern="/news"></examples-news>
</web-router>

获取 URL 参数

当路由匹配后，创建的组件将会包含 routeparam-* 属性，其记录了路由的参数信息。

<examples-news-detail routepattern="/news/:id" routeparam-id="1024"></examples-news-detail>

const element = document.querySelector('examples-news-detail');
const id = element.getAttribute('routeparam-id'); // "1024"

后代路由

当父路由路径末尾包含 /* 的时候能够匹配所有的后代路由。

{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    },
    {
      "path": "/news/*",
      "element": "examples-news"
    }   
  ]
}

上述例子中，无论 URL 是 /news 、/news/1024、 /news/1024/new 都会被匹配到。

404 路由

使用 * 可以匹配任何路径，因此它能够充当 404 的路由。

{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    },
    {
      "path": "/news/*",
      "element": "examples-news"
    },
    {
      "path": "*",
      "element": "examples-404"
    }
  ]
}

按需加载元素

Web Router 的核心功能只包括路由配置以及渲染匹配的元素，加载元素不是它的职责，这些功能可以交给诸如“自定义元素加载器”来实现。

例如与 Web Component 的模块化加载器—— Web Component Modules 一起工作：

<script type="routemap">
{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    },
    {
      "path": "/news/*",
      "element": "examples-news",
      "attributes": {
        "is": "web-component-module",
        "import": "@examples/news"
      }
    }
  ]
}
</script>
<web-router></web-router>

<script type="module">
  import '@web-widget/web-component-module';
</script>

访问 /news 时将创建：

<examples-news is="web-component-module" import="@examples/news" routepattern="/news"></examples-news>

Web Component Modules 会根据 is="web-component-module" 标记与import 属性加载自定义元素的 class 并且注册自定义元素。

与前端框架配合

和上述按需加载元素的问题类似，Web Router 可以借助第三方的“应用容器”与各种前端框架构建的应用一起工作，而不必须使用 Web Component 编写应用。

例如与“应用容器”—— Web Widget 一起工作：

<script type="routemap">
{
  "routes": [
    {
      "path": "/",
      "element": "examples-home"
    },
    {
      "path": "/news",
      "element": "web-widget",
      "attributes": {
        "import": "@examples/news"
      }
    }
  ]
}
</script>
<web-router></web-router>

<script type="module">
  import '@web-widget/container';
</script>

访问 /news 时将创建：

<web-widget import="@examples/news" routepattern="/news"></web-widget>

Web Widget 将会根据 import 属性加载应用的入口文件，然后调用应用生命周期。

详细设计

匹配语法

Web Router 的匹配语法不区分大小写。

标准

/stocks/latest

这条路由只能是完全匹配的。

变量

/stocks/:type

该路由包含变量 type，它可以被路由创建的元素获取到。

后代

/stocks/*

该路由匹配自身与后代路径。例如 /stocks、/stocks/、/stocks/3434/edit。

任意

该路由匹配任意的路径，用来做 404 等后备。

匹配优先级

优先级从上至下。

路由配置

<script type="routemap">
{
  "routes": [
    {
      "path": "/",
      "element": "examples-home",
      "attributes": {}
    }   
  ]
}
</script>

路由使用 HTML 标签来声明，这样做的目的是为了能够被序列化，并且能够清晰的知道将在哪里渲染激活后的元素。路由是静态声明的，这也意味着通过 JavaScript 动态创建的将不会生效。

path 路径
element 元素名
attributes 属性

渲染

<web-router> 元素充当路由渲染容器。当路由规则激活后，将会创建元素到 <web-router> 元素末尾，而非激活的元素将会被删除或隐藏。

路由创建的元素会添加 routepattern 属性，它等价于 <web-route> 的 path。

<my-element routepattern="/foo"></my-element>

如果路由中包含变量，那么创建的元素中会添加 routeparam-* 属性以记录参数值。

<my-element routepattern="/foo/:id/:type" routeparam-id="1024" routeparam-type="edit"></my-element>

异步元素

默认情况下匹配的路由以同步更新元素，但是当元素具备诸如“应用容器”特征的时候，Web Router 会将它们当作异步元素处理，以改善用户体验。

包含所有下述方法将被当作“应用容器”元素：

load()
bootstrap()
mount()
unload()

针对“应用容器”元素的具体处理逻辑取决于 Web Router 具体的路由系统实现（也可以完全忽略异步元素）。

base

（需要补充说明 <base> 元素对路由的影响）

SSR 服务器可以完全忽略它也不用担心引起 SEO 问题。
<web-link> 的导航功能必须由 JavaScript 定义才能使用（毕竟 Web Router 不是浏览器标准），这会导致应用从 Web Router 中拆卸后就无法工作了。
is 属性也是 Web Components 的一部分，它容易实现。

属性

href: 目标 URL。
state: 附加在路由上的状态对象。例如 <a is="web-link" state="{"id":"1024"}">。
replace: 是否用一个新位置替换历史堆栈中的当前位置。
~~active: 导航高亮时会自动增加此属性。~~
end: 它将确保当其后代路径匹配时，<a> 不会标记为 active。例如，要呈现仅在网站根目录而不是任何其他 URL 的链接，你可以使用 <a is="web-link" href="/" end>Home</a>。

导航接口

WebRouter.navigate(to, { replace, state })

参数

to : string 新地址。
replace: boolean 是否用一个新位置替换历史堆栈中的当前位置。
state : object 要与新位置关联的数据。

最佳实践

Web Router API 是一个底层 API，它被设计为给其他工具使用，因此最好不要直接让应用调用 Web Router API。好的做法是封装成工具函数或者一个自定义元素后再使用，这样可以避免应用与 Web Router 环境产生强耦合。

export function navigate(to, options) {
  if (typeof WebRouter !== 'undefined') {
    WebRouter.navigate(to, options);
  } else {
    location.href = to;
  }
}

事件

如下行为将会触发 Web Router 导航流程：

用户点击 <a is="web-link"> 元素
浏览器前进后退
程序调用 WebRouter.navigate() 接口

导航变更的时候，会在 window 上触发一系列的导航事件。

                Start
                  ▼
       ┌──────────┴───────────┐
       │ navigationwillchange ├───────────┐
       └──────────┬───────────┘           │
               Default                 Prevent
                  ▼                       ▼
         ┌────────┴────────┐              │
         │ navigationstart │              │
         └────────┬────────┘              │
        ┌─────────┴──────────┐            │ 
     Success              Failure         │
        ▼                    ▼            │
┌───────┴───────┐   ┌────────┴────────┐   │
│ navigationend │   │ navigationerror │   │
└───────┬───────┘   └────────┬────────┘   │
        └─────────┬──────────┴────────────┘
                  ▼
                 End

上述所有的事件类型都接收 NavigationChangeEvent Event 对象。它的属性：

newPathname: 即将前往的新地址
oldPathname: 旧地址
state: 状态对象

window.addEventListener('navigationstart', (event) => {
  console.log('oldPathname', event.oldPathname, 'newPathname', event.newPathname);
});

navigationwillchange

导航即将要开始。此事件可以被取消，取消后将阻止默认的导航行为。

window.addEventListener(
  'navigationwillchange',
  event => {
    // Check if we should navigate away from this page
    if (!confirm('You have unsafed data. Do you wish to discard it?')) {
      event.preventDefault();
    }
  }
);

navigationstart

导航开始。

navigationend

导航完成。

navigationerror

导航错误。例如元素挂载时出错。

采用策略

这个提案将会在 Growing Web 组织的仓库中开发，包命名为：@growing-web/web-router。
Web Widget 将提供插件以连接 Web Router，例如为应用注入路由的参数信息等。

兼容性

与 Vue2.x 兼容性

is 属性是 Web Component 对原生标签的扩展的标记，但是 Vue 2.x 故意将 is="xxx" 属性当作自己的属性来处理，这会导致导航标签无法工作（Vue 3.x 号称避免了与 Web Component 冲突问题）。

<a is="web-link" href="/">Home</a>

Vue 2.x 将会生成：

<web-link href="/">Home</web-link>

在 Vue 2.x 中使用 v-html 来输出 <a is="web-link"> 标签可以避免这样的问题发生。

或许还有更好的办法解决此问题，欢迎在 RFC 评论中指出。

与 Safari 兼容性

Safari 似乎不支持扩展原生标签，这会导致 <a is="web-link"> 降级到原生的 <a> 标签的浏览器默认功能，即它会重载入整个页面。详情：WebKit bug 182671。

社区解决方案：Safari不支持build-in自定义元素的兼容处理

未来的可能性

Web Router 的设计参考了流行的 Web 前端框架路由系统，当前它只定义了最核心的部分，保留了发展的可能，包括如下特性：

嵌套路由
滚动行为控制
重定向
过渡动效

示例：嵌套路由

{
  "routes": [
    {
      "path": "/",
      "element": "app-layout",
      "children": [
        {
          "path": "news",
          "element": "examples-news"
        },
        {
          "path": "*",
          "element": "examples-404"
        }
      ]
    }
  ]
}

当访问 /news，会生成如下结构的 DOM：

<web-router>
  <app-layout routepattern="/">
    <examples-news routepattern="/news"></examples-news>
  </app-layout>
</web-router>

示例：Layout

上述例子中，<examples-news> 的渲染位置可以由 <app-layout> 元素的 <slot> 决定：

class AppLayoutElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <header>...</header>
      <main>
        <slot><!--Web Router Outlet--></slot>
      </main>
      <footer>...</footer>
    `;
  }
}

customElements.define('app-layout', AppLayoutElement);

参考

WaiSiuKei · 2022-02-07T04:24:35Z

WaiSiuKei
Feb 7, 2022

是否支持多个路由匹配同一元素，比如

<web-router>
  <web-route path="/news" element="examples-news"></web-route>
  <web-route path="/news/:id" element="examples-news"></web-route>
</web-router>

3 replies

aui Feb 7, 2022
Maintainer Author

支持。使用「后代匹配」可以简写上述的配置：

<web-router>
  <web-route path="/news/*" element="examples-news"></web-route>
</web-router>

WaiSiuKei Feb 7, 2022

但是后代匹配来实现的话，无法对不同路由独立设置属性，而且还会影响更下一级的子路由，比如如下的意图无法实现

<web-router>
  <web-route path="/news" element="examples-news" title="all news"></web-route>
  <web-route path="/news/:id" element="examples-news" title="news A"></web-route>
  <web-route path="/news/:id/:comment" element="news-comments"></web-route>
</web-router>

aui Feb 7, 2022
Maintainer Author

我可能表达有误解，最原始的问题的回答「是否支持多个路由匹配同一元素」——支持 :-)

anncwb · 2022-02-07T06:05:24Z

anncwb
Feb 7, 2022
Maintainer

有两个疑问：

看下来 route-params 类似 /news/xxx 格式，可以支持 query格式吗？e.g: /news?id=111
<a is="web-link"></a> 是否可以封装成 web-component 组件, 从而进行语义化，如<web-route-link href="/">Home</web-route-link>，跟其它标签保持一致

2 replies

aui Feb 7, 2022
Maintainer Author

`route-params` 的问题

route-params 只包含路径上的变量，不包含 URLSearchParams。作为对比，Vue Router 与 React Router 也是将这两个概念区分的。

你的问题提醒了我：Web Router 是否有必要包含 route-params 的概念？如果能够删除它，那么更容易理解，也有助于保持长久的稳定。

`<a is="web-link">` 的问题

is="web-link" 它扩展了浏览器内置的元素，也是 Web Component 的一种形式（它继承的是 HTMLAnchorElement）。<a is="web-link"> 设计的目的是接近原始的 HTML 标签，它对 SSR 友好，甚至没有 JS 也可以使用基本的导航功能。

<web-route-link> 是一个更容易理解的设计，因为不用受限于 a 的 href 语义，我们可以设计得更加易用。额外担心是这样的设计将会让应用与 Web Router 产生耦合：没有 Web Router 的环境后应用就无法独立工作。

aui Feb 9, 2022
Maintainer Author

第二个问题的观点已经补充在 RFC 文档了😄

kinglisky · 2022-02-08T01:53:49Z

kinglisky
Feb 8, 2022

<examples-news-detail route-path="/news/:id" route-params="{&quot;id&quot;:&quot;1024&quot;}"></examples-news-detail>

const element = document.querySelector('examples-news-detail');
const id = element.route.params.id; // "1024"

现在路由参数是需要挂在目标元素吗？是否可以提供如：

window.WebRouter.route.params
window.WebRouter.route.query

用于获取当前路由参数，这样可以把参数从目标元素移除，还是因为考虑到 SSR 才需要在目标元素附加参数？

1 reply

aui Feb 8, 2022
Maintainer Author

在 WebRouter 增加 API 是一个不错的方案！后续也许也会扩充更多的 API（如果有必要）。

目前 params 的设计受主流的路由库的设计影响，而不是来自解决我们问题的需要，所以我们需要重新思考它是否可以被移除：目前我看到它只是一个辅助用途的功能，而 Vue Router 或者对应的工具函数来解析 URL 可以比 Web Router 路由系统做得更好。

kinglisky · 2022-02-08T02:06:04Z

kinglisky
Feb 8, 2022

有个想法，在目标元素引用路由参数，和 SVG 的 symbol 和 use 类似：

<svg>
<!-- symbol definition  NEVER draw -->
<symbol id="sym01" viewBox="0 0 150 110">
  <circle cx="50" cy="50" r="40" stroke-width="8" stroke="red" fill="red"/>
  <circle cx="90" cy="60" r="40" stroke-width="8" stroke="green" fill="white"/>
</symbol>

<!-- actual drawing by "use" element -->
<use xlink:href="#sym01"
     x="0" y="0" width="100" height="50"/>
<use xlink:href="#sym01"
     x="0" y="50" width="75" height="38"/>
<use xlink:href="#sym01"
     x="0" y="100" width="50" height="25"/>
</svg>

web-router 中：

<web-router id="web-router" params="{&quot;id&quot;:&quot;1024&quot;}>
    <web-route path="/" element="examples-home"></web-route>
    <web-route path="/news" element="examples-news"></web-route>
    <web-route path="/news/:id" element="examples-news-detail"></web-route>
    <web-route path="/about" element="examples-about"></web-route>

    <examples-news id="#web-router.params.id" ></examples-news>
</web-router>

其实和 vue 组件引用路由参数形式有点像

<template>
    <component :id="$route.params.id"></component>   
</template>

1 reply

aui Feb 9, 2022
Maintainer Author

我更新了 params 的设计：#10 (comment)

params 不是 Web Router 的核心，我想它应该变得更加简单（可以原始），避免理解与实现层面增加复杂度。

rick-you · 2022-02-08T11:08:14Z

rick-you
Feb 8, 2022

似乎无法定义激活路由的渲染位置，类似 react-router 的 outlet

4 replies

aui Feb 9, 2022
Maintainer Author

似乎 outlet 只能在嵌套路由中才有意义？如果我对 outlet 没有理解错的话，它像 Web Components 的 Slot，自定义元素可以通过 Slot 实现同样的效果。

假设未来的 Web Router 技术标准支持嵌套路由：

<web-router>
  <web-route path="/" element="app-layout">
    <web-route index title="首页" element="web-widget" import="@examples/home"></web-route>
    <web-route path="news" element="web-widget" import="@examples/news"></web-route>
    <web-route path="about" element="web-widget" title="关于" import="@examples/about" data-id="xxxx"></web-route>
    <web-route path="vue-router/*" element="web-widget" import="@examples/vue-router"></web-route>
    <web-route path="*" element="web-widget" import="@examples/404"></web-route>
  </web-route>
</web-router>

当访问 /，会生成如下结构的 DOM：

<web-router>
  <!--...-->
  <app-layout>
    <web-widget import="@examples/home"></web-widget>
  </app-layout>
</web-router>

这个例子中，<web-widget> 的渲染位置可以由 <app-layout> 元素的 <slot> 决定：

class AppLayoutElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <header>...</header>
      <main>
        <slot><!--Web Router Outlet--></slot>
      </main>
      <footer></footer>
    `;
  }
}

customElements.define('app-layout', AppLayoutElement);

我没有真正使用过 React Router，也许 outlet 理解是不全的，欢迎告诉我:-)

rick-you Feb 9, 2022

outlet 可以精确指定，当前激活路由渲染的位置。vue-router 中也有一样的标签 router-view，如：

<div id="app">
  <h1>Hello App!</h1>
  <p>
    <!-- use the router-link component for navigation. -->
    <!-- specify the link by passing the `to` prop. -->
    <!-- `<router-link>` will render an `<a>` tag with the correct `href` attribute -->
    <router-link to="/">Go to Home</router-link>
    <router-link to="/about">Go to About</router-link>
  </p>
  <!-- route outlet -->
  <!-- component matched by the route will render here -->
  <router-view></router-view>
</div>

目前路由渲染的位置，感觉比较隐晦。如果有 outlet 可以实现类似这种结构。

<web-router>
  <app-layout>
    <web-widget import="navbar"></web-widget>
    <web-widget import="main">
      <web-widget import="aside"></web-widget>
      <outlet></outlet>
    </web-widget>
  </app-layout>
</web-router>

这样可以将路由的渲染和路由配置分开。实现比较复杂的布局结构。

rick-you Feb 9, 2022

如果没有 outlet 的话：
路由结构就和渲染结构是一致的。整个路由渲染会 append 到 web-router 下。
每个拥有嵌套路由的父路由都是一个 layout，必须实现 slot ，用来渲染子路由。
这样的实现似乎也没什么问题。

aui Feb 10, 2022
Maintainer Author

因为它是一个可以被添加的特性，因此我们当前可以保持现有的设计，如果后续有必要的情况在考虑增加特性。

aui · 2022-02-09T06:25:41Z

aui
Feb 9, 2022
Maintainer Author

更新：

route-path 变更为 routepattern。
route-params 变更为 routeparam-*（* 为具体的参数名，类似 HTML5 data-*）。

原因：

一些 Web 前端框架（例如 Vue Router）会给元素注入 $route.path，它被定义为 matched path，这会导致概念混淆。重命名为 routepattern 后，保留 routepath 作为后续使用。
接近 W3C 的属性命名风格，两个单词将合并在一起（例如 autofocus）

0 replies

aui · 2022-02-18T03:37:42Z

aui
Feb 18, 2022
Maintainer Author

更新：删除 title 的定义。
原因：title 是用来描述页面标题，这会导致 Web Router 需要考虑国际化的问题，而这样的问题通常交给具体应用程序定义会更好。

0 replies

aui · 2022-10-14T07:46:22Z

aui
Oct 14, 2022
Maintainer Author

更新：使用 <script type="routemap"> 标签作为 HTML 配置
原因：与 <script type="importmap"> 规范的风格保持一致，也有利于后端渲染共享相同的配置

0 replies

路由系统 #10

aui Feb 7, 2022 Maintainer

描述

动机

基本示例

路由

导航

获取 URL 参数

后代路由

404 路由

按需加载元素

与前端框架配合

详细设计

匹配语法

标准

变量

后代

任意

匹配优先级

路由配置

渲染

异步元素

base

导航

导航标签

属性

导航接口

参数

最佳实践

事件

navigationwillchange

navigationstart

navigationend

navigationerror

采用策略

兼容性

与 Vue2.x 兼容性

与 Safari 兼容性

未来的可能性

示例：嵌套路由

示例：Layout

参考

Replies: 8 comments · 11 replies

WaiSiuKei Feb 7, 2022

aui Feb 7, 2022 Maintainer Author

WaiSiuKei Feb 7, 2022

aui Feb 7, 2022 Maintainer Author

anncwb Feb 7, 2022 Maintainer

aui Feb 7, 2022 Maintainer Author

route-params 的问题

<a is="web-link"> 的问题

aui Feb 9, 2022 Maintainer Author

kinglisky Feb 8, 2022

aui Feb 8, 2022 Maintainer Author

kinglisky Feb 8, 2022

aui Feb 9, 2022 Maintainer Author

rick-you Feb 8, 2022

aui Feb 9, 2022 Maintainer Author

rick-you Feb 9, 2022

rick-you Feb 9, 2022

aui Feb 10, 2022 Maintainer Author

aui Feb 9, 2022 Maintainer Author

aui Feb 18, 2022 Maintainer Author

aui Oct 14, 2022 Maintainer Author

aui
Feb 7, 2022
Maintainer

Replies: 8 comments 11 replies

WaiSiuKei
Feb 7, 2022

aui Feb 7, 2022
Maintainer Author

aui Feb 7, 2022
Maintainer Author

anncwb
Feb 7, 2022
Maintainer

aui Feb 7, 2022
Maintainer Author

`route-params` 的问题

`<a is="web-link">` 的问题

aui Feb 9, 2022
Maintainer Author

kinglisky
Feb 8, 2022

aui Feb 8, 2022
Maintainer Author

kinglisky
Feb 8, 2022

aui Feb 9, 2022
Maintainer Author

rick-you
Feb 8, 2022

aui Feb 9, 2022
Maintainer Author

aui Feb 10, 2022
Maintainer Author

aui
Feb 9, 2022
Maintainer Author

aui
Feb 18, 2022
Maintainer Author

aui
Oct 14, 2022
Maintainer Author