WebWidget router

这是 WebWidget 的路由插件。

安装

npm install @web-sandbox.js/router --save

使用

<web-widget name="home" src="/index.widget.js" inactive></web-widget>
<web-widget name="news" src="/news.widget.js" inactive></web-widget>
<web-widget name="about" src="/about.widget.js" inactive></web-widget>
<web-widget name="vue-router" src="/vue-router.widget.js" inactive></web-widget>

为 WebWidget 容器添加 inactive 属性，让其不再受 DOM 生命周期控制，以便让交给路由控制它的挂载与卸载行为。

import '@web-sandbox.js/web-widget';
import { collection, navigate, history } from  '@web-sandbox.js/router';

// 注册应用
collection.add(
  document.querySelector('[name=home]'),
  location => location.pathname === '/'
);

collection.add(
  document.querySelector('[name=news]'),
  location => location.pathname.startsWith('/news')
);

collection.add(
  document.querySelector('[name=about]'),
  location => location.pathname.startsWith('/about')
);

collection.add(
  document.querySelector('[name=vue-router]'),
  location => location.pathname.startsWith('/vue-router')
);

function reroute() {
  // 通知应用集合进行状态变更
  collection.change(location);
}

// 监听路由变更
history.listen(reroute);
reroute();

// 提供全局导航 API（屏蔽了 hash 与 history 模式差异）
window.navigate = navigate;

API

WebWidget router 由三个领域 API 组合而成。

import { collection, navigate, history } from  '@web-sandbox.js/router';

• collection 应用集合管理器
• history 历史记录对象
• navigate 导航器

collection

管理应用集合。

add

注册应用。

collection.add(webWidgetElement, activeWhen);

参数

• webWidgetElement: HTMLWebWidgetElement 元素实例
• activeWhen: 应用活动状态回调函数，每次路由变更的时候（change）它都会触发。它接收 location 参数，通过返回值告诉 collection 是否挂载或卸载应用

delete

移除注册的应用。

collection.delete(webWidgetElement);

参数

• webWidgetElement: HTMLWebWidgetElement 元素实例

change

触发应用状态变更。

collection.change(location);

参数

• location: 即 window.location

catch

应用发生异常后的回调用函数。它的默认行为是向异步向全局抛出异常，这样 window.onerror 监听器可以处理，而覆盖它可以实现自定义的错误监控。

collection.catch = error => {
  // ...
};

history

历史记录对象，来自 history。历史对象可以使用以下方法以编程方式更改当前位置:

• history.push(to: To, state?: State)
• history.replace(to: To, state?: State)
• history.go(delta: number)
• history.back()
• history.forward()

示范

// Push a new entry onto the history stack.
history.push('/home');

// Push a new entry onto the history stack with a query string
// and some state. Location state does not appear in the URL.
history.push('/home?the=query', { some: 'state' });

// If you prefer, use a location-like object to specify the URL.
// This is equivalent to the example above.
history.push({
  pathname: '/home',
  search: '?the=query'
}, {
  some: state
});

// Go back to the previous history entry. The following
// two lines are synonymous.
history.go(-1);
history.back();

navigate

导航器。

navigate(target);

参数

• target: 支持 string 或 HTMLAnchorElement、Event 对象

运行示例

npm run examples

常见问题

应用的二级路由如何处理？

WebWidget router 只负责管理一级路由，二级路由应当有应用自己管理，例如使用 vue-router 等。

为什么不提供配置的形式管理路由？

的确使用配置的形式有助于提高开发体验，但 WebWidget router 的核心职责是提供关键功能，这样使得它能够具备更好的可扩展性，因此你可以基于这些关键功能来实现更多的功能。