vitarx-router 0.0.1 → 1.0.0-beta.2

package/README.md

@@ -1,5 +1,6 @@
 # VitarxRouter
 
+Vitarx前端框架的配套路由器
 ________________________________________________________________________
 
 ## 安装
@@ -8,7 +9,40 @@ ________________________________________________________________________
 npm install vitarx-router
 ```
 
-## 使用
-```javascript
-import { Router } from 'vitarx-router'
+## 简单示例
+
+```ts
+// main.ts
+import { createRouter } from 'vitarx-router'
+import Page1 from './Page/Page1.js'
+
+createRouter({
+  mode: 'path', // 路由模式，可选值：hash、path、memory
+  suffix: '*', // 允许任何后缀，例如 /x.html
+  routes: [
+    {
+      name: 'home', // 命名路由
+      path: '/',
+      widget: lazy(() => import('./Pages/home.js')),// 代码分块懒加载
+      children: [ // 嵌套路由
+        {
+          path: '/workbench',
+          widget: lazy(() => import('./Pages/home/workbench.js')) // 直接使用小部件
+        }
+      ]
+    },
+    { // 动态路由
+      path: '/page1/{name?}',// {name?}为可选参数，没有?为必填参数
+      widget: Page1
+    },
+    { // 命名视图
+      path: '/page3',
+      widget: { // 命名视图
+        'default': lazy(() => import('./Page/xxx.js')),
+        'right': lazy(() => import('./Page/xxx.js'))
+      }
+    }
+  ]
+})
+createApp('#root').render(App)
 ```

package/dist/router/index.d.ts

@@ -3,4 +3,5 @@ export { NavigateStatus } from './type.js';
 export { default as Router } from './router.js';
 export { default as WebHistoryRouter } from './web-history-router.js';
 export { default as MemoryRouter } from './memory-router.js';
+export { generateRouteIndex } from './utils.js';
 export * from './helper.js';

package/dist/router/router.d.ts

@@ -223,6 +223,22 @@ export default abstract class Router {
      * @return {RouteNormalized | undefined}
      */
     findParentRoute(route: RouteNormalized): RouteNormalized | undefined;
+    /**
+     * 根据路由目标创建导航数据
+     *
+     * @param {RouteTarget} target - 路由目标
+     */
+    createRouteLocation(target: RouteTarget): RouteLocation;
+    /**
+     * 路由跳转的通用方法
+     *
+     * `push`|`replace`方法最终都会调用此方法
+     *
+     * @protected
+     * @param {RouteTarget} target - 目标
+     * @return {Promise<NavigateResult>} - 是否导航成功
+     */
+    navigate(target: RouteTarget): Promise<NavigateResult>;
     /**
      * 该方法提供给`RouterView`完成渲染时调用
      *
@@ -281,8 +297,9 @@ export default abstract class Router {
      * @param path - 路径
      * @param query - ?查询参数
      * @param hash - #哈希值
+     * @return {string}
      */
-    protected makeFullPath(path: string, query: `?${string}` | '' | Record<string, string>, hash: HashStr): `${string}`;
+    protected makeFullPath(path: string, query: `?${string}` | '' | Record<string, string>, hash: HashStr): `/${string}`;
     /**
      * 添加历史记录
      *
@@ -309,13 +326,6 @@ export default abstract class Router {
      * @protected
      */
     protected isSameNavigate(to: RouteLocation, from: RouteLocation): boolean;
-    /**
-     * 根据路由目标创建导航数据
-     *
-     * @param {RouteTarget} target - 路由目标
-     * @protected
-     */
-    protected createRouteLocation(target: RouteTarget): RouteLocation;
     /**
      * 触发路由前置守卫
      *
@@ -331,16 +341,6 @@ export default abstract class Router {
      * @param {DeepReadonly<RouteLocation>} from - 前路由对象
      */
     protected onAfterEach(to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>): void;
-    /**
-     * 路由跳转的通用方法
-     *
-     * 仅供内部使用，外部请使用`push`|`replace`方法
-     *
-     * @protected
-     * @param {RouteTarget} target - 目标
-     * @return {Promise<NavigateResult>} - 是否导航成功
-     */
-    protected navigate(target: RouteTarget): Promise<NavigateResult>;
     /**
      * 更新路由数据
      *

package/dist/router/type.d.ts

@@ -156,6 +156,14 @@ export interface RouteLocation {
      * @default {}
      */
     query: Record<string, string>;
+    /**
+     * 路由线路配置的元数据
+     *
+     * 如果没有配置元数据，那它将会是空对象，未匹配到任何路由也会是空对象。
+     *
+     * @default {}
+     */
+    meta: RouteMeta;
     /**
      * 匹配的路由对象
      *
@@ -320,12 +328,10 @@ export interface RouterOptions<T_MODE extends HistoryMode = HistoryMode> {
     /**
      * 支持的后缀名，如：.html、.md等。
      *
-     * 默认支持所有后缀名进行匹配，如：`/page.html`、`/page.md`等。
-     *
      * 可选值类型：
-     * 1. 通配符：`*`：支持所有后缀名
+     * 1. 通配符：`*`：支持所有后缀名，如：`/page.html`、`/page.md`等。
      * 2. 字符串类型：`html`：支持html后缀名
-     * 3. 数组：`['html','md']`：同时支持html和md后缀名
+     * 3. 数组：`['html','md']`：同时支持html和md后缀名，注意不要以`.`开头
      * 4. false：不做任何处理，硬性匹配。
      * @default false
      */

package/dist/vitarx-router.js

@@ -1,57 +1,57 @@
-var D = Object.defineProperty;
-var j = (e) => {
+var q = Object.defineProperty;
+var I = (e) => {
   throw TypeError(e);
 };
-var M = (e, t, i) => t in e ? D(e, t, { enumerable: !0, configurable: !0, writable: !0, value: i }) : e[t] = i;
-var l = (e, t, i) => M(e, typeof t != "symbol" ? t + "" : t, i), B = (e, t, i) => t.has(e) || j("Cannot " + i);
-var f = (e, t, i) => (B(e, t, "read from private field"), i ? i.call(e) : t.get(e)), x = (e, t, i) => t.has(e) ? j("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, i), v = (e, t, i, n) => (B(e, t, "write to private field"), n ? n.call(e, i) : t.set(e, i), i);
-import { reactive as U, shallowReactive as G, createElement as V, LazyWidget as q, deepEqual as k, deepClone as K, Widget as J, shallowRef as Q, inject as X, provide as Z, watch as N, Fragment as tt } from "vitarx";
-var g = /* @__PURE__ */ ((e) => (e[e.success = 0] = "success", e[e.aborted = 1] = "aborted", e[e.cancelled = 2] = "cancelled", e[e.duplicated = 3] = "duplicated", e[e.not_matched = 4] = "not_matched", e[e.exception = 5] = "exception", e))(g || {});
-function T(e) {
+var K = (e, t, i) => t in e ? q(e, t, { enumerable: !0, configurable: !0, writable: !0, value: i }) : e[t] = i;
+var l = (e, t, i) => K(e, typeof t != "symbol" ? t + "" : t, i), H = (e, t, i) => t.has(e) || I("Cannot " + i);
+var f = (e, t, i) => (H(e, t, "read from private field"), i ? i.call(e) : t.get(e)), _ = (e, t, i) => t.has(e) ? I("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, i), v = (e, t, i, n) => (H(e, t, "write to private field"), n ? n.call(e, i) : t.set(e, i), i);
+import { reactive as J, shallowReactive as Q, markRaw as k, createElement as V, LazyWidget as X, deepClone as Z, deepEqual as S, Widget as M, shallowRef as N, inject as tt, provide as et, watch as it, Fragment as nt, Computed as L, isString as st } from "vitarx";
+var p = /* @__PURE__ */ ((e) => (e[e.success = 0] = "success", e[e.aborted = 1] = "aborted", e[e.cancelled = 2] = "cancelled", e[e.duplicated = 3] = "duplicated", e[e.not_matched = 4] = "not_matched", e[e.exception = 5] = "exception", e))(p || {});
+function B(e) {
   return typeof e == "boolean" || typeof e == "function" || typeof e == "object" && e !== null;
 }
-function et(e) {
+function rt(e) {
   if (e.widget === void 0) return;
   if (!("injectProps" in e)) {
-    e.injectProps = I(e, !0);
+    e.injectProps = W(e, !0);
     return;
   }
   const t = e.injectProps;
   if (typeof t == "object")
-    it(t) ? nt(e, t) : st(e, t);
-  else if (T(t))
-    e.injectProps = I(e, t);
+    ot(t) ? at(e, t) : ct(e, t);
+  else if (B(t))
+    e.injectProps = W(e, t);
   else
     throw new TypeError(
       `[Vitarx.Router][TYPE_ERROR]：${e.path} 路由线路配置的 injectProps 类型有误，它可以是布尔值、函数，亦或是一个{string:any}类型的对象。`
     );
 }
-function it(e) {
+function ot(e) {
   return Object.keys(e).length === 1 && "default" in e;
 }
-function nt(e, t) {
-  if (!T(t.default))
+function at(e, t) {
+  if (!B(t.default))
     throw new TypeError(
       `[Vitarx.Router][TYPE_ERROR]：${e.path} 路由线路配置的 injectProps.default 类型有误，它可以是布尔值、函数，亦或是一个{string:any}类型的对象。`
     );
 }
-function st(e, t) {
+function ct(e, t) {
   for (const i of Object.keys(e.widget))
     if (i in t) {
-      if (!T(t[i]))
+      if (!B(t[i]))
         throw new TypeError(
           `[Vitarx.Router][TYPE_ERROR]：${e.path} 路由线路配置的 injectProps.${i} 类型有误，它可以是布尔值、函数，亦或是一个{string:any}类型的对象。`
         );
     } else
       t[i] = !0;
 }
-function I(e, t) {
+function W(e, t) {
   const i = {};
   for (const n of Object.keys(e.widget))
     i[n] = t;
   return i;
 }
-function rt(e) {
+function ht(e) {
   if (!("widget" in e)) {
     if (e.children.length === 0)
       throw new TypeError(
@@ -76,42 +76,42 @@ function rt(e) {
       `[Vitarx.Router][TYPE_ERROR]：${e.path} 路由线路配置的 widget 类型有误，它可以是函数式小部件、类小部件，亦或是一个惰性加载器。`
     );
 }
-const F = Symbol("LazyLoader");
-function O(e) {
+const U = Symbol("LazyLoader");
+function T(e) {
   return /\{[^}]+}/.test(e);
 }
-function ot(e) {
+function ut(e) {
   const t = e.replace(/\s+/g, ""), i = /\{[\w-]+\?}/g, n = t.match(i);
   return n ? n.length : 0;
 }
-function H(e) {
+function A(e) {
   return "children" in e && e.children !== void 0 && e.children.length > 0;
 }
-function ct(e, t, i, n) {
+function lt(e, t, i, n) {
   let s = 0;
-  const r = (h, c) => {
-    const _ = t[h];
-    if (_ ? _ instanceof RegExp || (console.warn(
+  const r = (h, a) => {
+    const $ = t[h];
+    if ($ ? $ instanceof RegExp || (console.warn(
       `[Vitarx.Router][WARN]：${e} 动态路径${h}变量的自定义正则表达式必须是 RegExp 类型`
-    ), t[h] = n) : t[h] = n, c)
+    ), t[h] = n) : t[h] = n, a)
       return s++, `(?:(${t[h].source}))?`;
     if (s)
       throw new Error(
         `[Vitarx.Router][ERROR]：动态路径 ${e} 中，可选变量 ${h} 后不能存在任何必填变量`
       );
     return `(${t[h].source})`;
-  }, o = e.replace(/{([^}?]+)\?}/g, (h, c) => r(c, !0)).replace(/{([^}]+)}/g, (h, c) => r(c, !1)).replace(/\//g, "\\/").replace(/\/?$/, "/?"), u = i ? "" : "i", a = e.replace(/^\/|\/$/g, "").split("/").length;
+  }, o = e.replace(/{([^}?]+)\?}/g, (h, a) => r(a, !0)).replace(/{([^}]+)}/g, (h, a) => r(a, !1)).replace(/\//g, "\\/").replace(/\/?$/, "/?"), u = i ? "" : "i", c = e.replace(/^\/|\/$/g, "").split("/").length;
   return {
     regex: new RegExp(`^${o}$`, u),
-    length: a,
+    length: c,
     optional: s
   };
 }
-function d(e) {
-  return e = e.replace(/\s+/g, "").replace(/\/+/g, "/"), e.length ? e === "/" || e === "/#/" ? e : e.replace(/\/$/, "") : "/";
+function R(e) {
+  return e = `/${e}`.replace(/\s+/g, "").replace(/\/+/g, "/"), e.length ? e === "/" || e === "/#/" ? e : e.replace(/\/$/, "") : "/";
 }
-function S(e, t) {
-  if (!O(e)) return e;
+function C(e, t) {
+  if (!T(e)) return e;
   const i = e;
   return e = e.replace(/{([^}]+)\?*}/g, (n, s) => {
     const r = s.endsWith("?");
@@ -122,48 +122,56 @@ function S(e, t) {
       );
     }
     return String(t[s]).replace(/\s+/g, "_");
-  }), d(e);
+  }), R(e);
 }
-function at(e) {
-  return typeof e == "function" && e[F];
+function ft(e) {
+  return typeof e == "function" && e[U];
 }
-function W(e, t) {
+function D(e, t) {
   return typeof e != "string" || !e ? "" : (e = e.trim(), e.startsWith("#") ? e : `#${e}`);
 }
-function L(e) {
+function z(e) {
   e = decodeURIComponent(e);
   const t = new URLSearchParams(
     e.startsWith("?") ? e.substring(1) : e
   ), i = {};
   return t.forEach((n, s) => i[s] = n), i;
 }
-function ht(e) {
+function dt(e) {
   const t = new URLSearchParams(e).toString();
   return t ? `?${t}` : "";
 }
-function ut(e, t, i) {
-  let n = decodeURIComponent(e.pathname), s = decodeURIComponent(e.hash), r;
-  if (t === "path")
-    return r = L(e.search), n.startsWith(i) ? n = d(n.slice(i.length)) : n = d(n), { index: n, hash: s, query: r };
-  if (s.includes("#")) {
-    const o = s.slice(1), [u, a] = o.split("#"), [h, c] = u.split("?");
-    n = d(h || ""), s = a ? `#${a}` : "", r = L(c || "");
-  } else
-    n = i, r = L(e.search);
+function pt(e, t, i) {
+  let n = decodeURIComponent(e.pathname), s = decodeURIComponent(e.hash), r = z(e.search);
+  if (n = R(n.startsWith(i) ? n.slice(i.length) : n), t === "hash" && s.includes("#/")) {
+    const o = s.slice(1), [u, c] = o.split("#"), [h, a] = u.split("?");
+    n = R(h || ""), s = c ? `#${c}` : "", r = z(a || "");
+  }
   return { index: n, hash: s, query: r };
 }
-function lt(e) {
-  const t = Y(e);
+function Rt(e) {
+  const t = G(e);
   return t && (e = e.slice(0, -t.length)), {
     path: e,
     suffix: t
   };
 }
-function Y(e) {
+function G(e) {
   const t = e.match(/^(.*?)(\.[a-zA-Z0-9]+)$/);
   return t ? t[2] : "";
 }
-function ft(e) {
+function bt(e) {
+  const t = [], i = [];
+  function n(s, r = "") {
+    const o = R(r ? `${r}/${s.path}` : s.path);
+    s.widget && t.push(o), s.name && i.push(s.name), s.children && s.children.length > 0 && s.children.forEach((u) => n(u, o));
+  }
+  return e.forEach((s) => n(s)), {
+    paths: t,
+    names: i
+  };
+}
+function gt(e) {
   if (typeof e != "object" || e === null) return !1;
   const t = [
     "index",
@@ -172,41 +180,42 @@ function ft(e) {
     "hash",
     "params",
     "query",
-    "matched"
+    "matched",
+    "meta"
   ];
   for (const i of t)
     if (!Object.prototype.hasOwnProperty.call(e, i)) return !1;
   return !0;
 }
-function dt(e) {
+function mt(e) {
   if (e.meta = e.meta || {}, e.pattern = e.pattern || {}, e.children = e.children || [], !Array.isArray(e.children))
     throw new TypeError(
       `[Vitarx.Router][TYPE_ERROR]：${e.path} 路由线路配置 children 类型错误，它必须是数组类型。`
     );
   if (!e.path.trim())
     throw new TypeError("[Vitarx.Router][TYPE_ERROR]：路由线路配置 path 不能为空");
-  return e.path = d(e.path), rt(e), et(e), e;
+  return e.path = R(e.path), ht(e), rt(e), e;
 }
-const pt = ["path", "hash", "index", "fullPath"];
-function Rt(e, t) {
-  gt(e.matched, t.matched), A(e.params, t.params), A(e.query, t.query);
-  for (const i of pt)
+const wt = ["path", "hash", "index", "fullPath"];
+function yt(e, t) {
+  _t(e.matched, t.matched), j(e.params, t.params), j(e.query, t.query), j(e.meta, t.meta);
+  for (const i of wt)
     e[i] !== t[i] && (e[i] = t[i]);
 }
-function gt(e, t) {
+function _t(e, t) {
   for (let i = 0; i < t.length; i++)
     e[i] !== t[i] && (e[i] = t[i]);
   e.length > t.length && (e.length = t.length);
 }
-function A(e, t) {
+function j(e, t) {
   const i = Object.keys(e), n = Object.keys(t);
   for (const s of n)
-    t.hasOwnProperty(s) && (e[s] = t[s]);
+    Object.prototype.hasOwnProperty.call(t, s) && (e[s] = t[s]);
   for (const s in i)
     s in t || delete e[s];
 }
 var m;
-const R = class R {
+const g = class g {
   constructor(t) {
     // 配置
     l(this, "_options");
@@ -242,7 +251,7 @@ const R = class R {
     l(this, "_isBrowser", typeof window < "u" && typeof window.document < "u");
     // 滚动行为
     l(this, "_scrollBehavior", "auto");
-    if (f(R, m))
+    if (f(g, m))
       throw new Error("[Vitarx.Router.constructor]：路由器实例已存在，不能创建多个实例");
     this._options = {
       base: "/",
@@ -252,14 +261,15 @@ const R = class R {
       suffix: !1,
       pattern: /[\w.]+/,
       ...t
-    }, this._options.base = `/${this._options.base.replace(/^\/+|\/+$/g, "")}`, this._currentRouteLocation = U({
+    }, this._options.base = `/${this._options.base.replace(/^\/+|\/+$/g, "")}`, this._currentRouteLocation = J({
       index: this._options.base,
       path: this._options.base,
       hash: "",
       fullPath: this._options.base,
       params: {},
       query: {},
-      matched: G([])
+      matched: Q([]),
+      meta: k({})
     });
   }
   /**
@@ -268,9 +278,9 @@ const R = class R {
    * @return {Router} - 路由器实例
    */
   static get instance() {
-    if (!f(R, m))
+    if (!f(g, m))
       throw new Error("[Vitarx.Router.instance]：路由器实例未初始化");
-    return f(R, m);
+    return f(g, m);
   }
   /**
    * 是否运行在浏览器端
@@ -354,7 +364,7 @@ const R = class R {
    * @return {boolean} - 如果初始化完成，返回true，否则返回false
    */
   get initialized() {
-    return f(R, m) !== void 0;
+    return f(g, m) !== void 0;
   }
   /**
    * 受支持的`path`后缀名
@@ -408,9 +418,9 @@ const R = class R {
    */
   static routeView(t, i) {
     const n = t.widget;
-    if (!n.hasOwnProperty(i)) return;
+    if (!Object.prototype.hasOwnProperty.call(n, i)) return;
     const s = n[i];
-    return at(s) ? V(q, { children: s, key: t.path }) : V(s);
+    return ft(s) ? V(X, { children: s, key: t.path }) : V(s);
   }
   /**
    * 后退到上一个历史记录
@@ -451,7 +461,7 @@ const R = class R {
   removeRoute(t, i = !0) {
     const n = this.findRoute(t);
     if (n) {
-      if (H(n))
+      if (A(n))
         for (const s of n.children)
           this.removeRoute(s.path, !1);
       this._pathRoutes.delete(n.path), n.name && this._namedRoutes.delete(n.name), this.removeDynamicRoute(n.path), i && this.removedFromRoutes(n);
@@ -509,7 +519,7 @@ const R = class R {
    * @return {this} - 返回当前路由器实例
    */
   initialize() {
-    return f(R, m) ? this : (this.setupRoutes(this._options.routes), typeof this.options.scrollBehavior == "function" ? this._scrollBehaviorHandler = this.options.scrollBehavior : this._scrollBehavior = this.options.scrollBehavior, this.initializeRouter(), v(R, m, this), this);
+    return f(g, m) ? this : (this.setupRoutes(this._options.routes), typeof this.options.scrollBehavior == "function" ? this._scrollBehaviorHandler = this.options.scrollBehavior : this._scrollBehavior = this.options.scrollBehavior, this.initializeRouter(), v(g, m, this), this);
   }
   /**
    * 此方法用于浏览器端滚动到指定位置
@@ -541,6 +551,76 @@ const R = class R {
   findParentRoute(t) {
     return this._parentRoute.get(t);
   }
+  /**
+   * 根据路由目标创建导航数据
+   *
+   * @param {RouteTarget} target - 路由目标
+   */
+  createRouteLocation(t) {
+    if (gt(t)) return t;
+    const i = this.findRoute(t), { index: n, query: s = {}, params: r = {}, hash: o = "" } = t;
+    let u;
+    const c = [];
+    if (i) {
+      let O = G(n);
+      this.suffix && O && !i.path.endsWith(O) ? u = C(i.path + O, r) : u = C(i.path, r);
+      let P = this.findParentRoute(i);
+      for (; P; )
+        P.widget && c.unshift(P), P = this.findParentRoute(P);
+      c.push(i);
+    } else
+      u = R(n);
+    const h = (i == null ? void 0 : i.meta) || {}, a = D(o), $ = this.makeFullPath(u, s, a);
+    return { index: n, path: u, hash: a, fullPath: $, params: r, query: s, matched: c, meta: h };
+  }
+  /**
+   * 路由跳转的通用方法
+   *
+   * `push`|`replace`方法最终都会调用此方法
+   *
+   * @protected
+   * @param {RouteTarget} target - 目标
+   * @return {Promise<NavigateResult>} - 是否导航成功
+   */
+  navigate(t) {
+    const i = ++this._taskCounter;
+    this._currentTaskId = i;
+    const n = () => this._currentTaskId === i, s = Z(this.currentRouteLocation), r = async (o, u) => {
+      const c = this.createRouteLocation(o), h = (a = {}) => ({
+        from: s,
+        to: c,
+        status: p.success,
+        message: "导航成功",
+        redirectFrom: u ? t : void 0,
+        ...a
+      });
+      if (this.isSameNavigate(c, this.currentRouteLocation))
+        return h({
+          status: p.duplicated,
+          message: "导航到相同的路由，被系统阻止！"
+        });
+      try {
+        const a = await this.onBeforeEach(c, this.currentRouteLocation);
+        return a === !1 ? h({
+          status: p.aborted,
+          message: "导航被前置守卫钩子阻止"
+        }) : n() ? typeof a == "object" && a.index !== o.index ? (a.isReplace ?? (a.isReplace = !1), r(a, !0)) : c.matched.length ? (o.isReplace ? (this._pendingReplace = c, this.replaceHistory(c)) : (this._pendingPush = c, this.pushHistory(c)), h()) : h({
+          status: p.not_matched,
+          message: "未匹配到任何路由规则，被系统阻止！请检测目标索引是否正确。"
+        }) : h({
+          status: p.cancelled,
+          message: "已被新的导航请求替代，取消此次导航！"
+        });
+      } catch (a) {
+        return console.error("[Vitarx.Router.navigate][ERROR]：导航时捕获到了异常", a), h({
+          status: p.exception,
+          message: "导航时捕获到了异常",
+          error: a
+        });
+      }
+    };
+    return r(t, !1);
+  }
   /**
    * 该方法提供给`RouterView`完成渲染时调用
    *
@@ -580,7 +660,7 @@ const R = class R {
    * @protected
    */
   updateQuery(t) {
-    k(this._currentRouteLocation.query, t) || (this._currentRouteLocation.query = t, this._currentRouteLocation.fullPath = this.makeFullPath(
+    S(this._currentRouteLocation.query, t) || (this._currentRouteLocation.query = t, this._currentRouteLocation.fullPath = this.makeFullPath(
       this._currentRouteLocation.path,
       t,
       this._currentRouteLocation.hash
@@ -596,7 +676,7 @@ const R = class R {
    */
   updateHash(t) {
     typeof t != "string" && console.warn(`[Vitarx.Router.updateHash][WARN]：hash值只能是字符串类型，给定${t}`);
-    const i = W(t);
+    const i = D(t);
     i !== this._currentRouteLocation.hash && (this._currentRouteLocation.hash = i, this._currentRouteLocation.fullPath = this.makeFullPath(
       this._currentRouteLocation.path,
       this._currentRouteLocation.query,
@@ -612,8 +692,8 @@ const R = class R {
    * @return {MatchResult} 如果匹配失败则返回undefined
    */
   matchRoute(t) {
-    if (t = d(t), this._options.strict || (t = t.toLowerCase()), this.suffix) {
-      const { path: s, suffix: r } = lt(t);
+    if (t = R(t), this._options.strict || (t = t.toLowerCase()), this.suffix) {
+      const { path: s, suffix: r } = Rt(t);
       if (!this.isAllowedSuffix(r))
         return;
       t = s;
@@ -627,8 +707,8 @@ const R = class R {
         const o = s.exec(t);
         if (o) {
           const u = {};
-          return Object.keys(r.pattern).forEach((h, c) => {
-            u[h] = o[c + 1];
+          return Object.keys(r.pattern).forEach((h, a) => {
+            u[h] = o[a + 1];
           }), { route: r, params: u };
         }
       }
@@ -641,9 +721,10 @@ const R = class R {
    * @param path - 路径
    * @param query - ?查询参数
    * @param hash - #哈希值
+   * @return {string}
    */
   makeFullPath(t, i, n) {
-    return n && !n.startsWith("#") && (n = `#${n}`), typeof i == "object" && (i = ht(i)), this.mode === "hash" ? d(`${this.basePath}/#${t}${i}${n}`) : d(`${this.basePath}${t}${i}${n}`);
+    return n && !n.startsWith("#") && (n = `#${n}`), typeof i == "object" && (i = dt(i)), this.mode === "hash" ? R(`${this.basePath}/#${t}${i}${n}`) : R(`${this.basePath}${t}${i}${n}`);
   }
   /**
    * 判断是否相同的导航请求
@@ -653,38 +734,7 @@ const R = class R {
    * @protected
    */
   isSameNavigate(t, i) {
-    return k(t, i);
-  }
-  /**
-   * 根据路由目标创建导航数据
-   *
-   * @param {RouteTarget} target - 路由目标
-   * @protected
-   */
-  createRouteLocation(t) {
-    if (ft(t)) return t;
-    const i = this.findRoute(t), { index: n, query: s = {}, params: r = {}, hash: o = "" } = t;
-    let u;
-    const a = [];
-    if (i) {
-      let _ = Y(n);
-      this.suffix && _ && !i.path.endsWith(_) ? u = S(i.path + _, r) : u = S(i.path, r);
-      let E = this.findParentRoute(i);
-      for (; E; )
-        E.widget && a.unshift(E), E = this.findParentRoute(E);
-      a.push(i);
-    } else
-      u = d(n);
-    const h = W(o), c = this.makeFullPath(u, s, h);
-    return {
-      index: n,
-      path: u,
-      hash: h,
-      fullPath: c,
-      params: r,
-      query: s,
-      matched: a
-    };
+    return S(t, i);
   }
   /**
    * 触发路由前置守卫
@@ -707,54 +757,6 @@ const R = class R {
     var n;
     return (n = this._options.afterEach) == null ? void 0 : n.call(this, t, i);
   }
-  /**
-   * 路由跳转的通用方法
-   *
-   * 仅供内部使用，外部请使用`push`|`replace`方法
-   *
-   * @protected
-   * @param {RouteTarget} target - 目标
-   * @return {Promise<NavigateResult>} - 是否导航成功
-   */
-  navigate(t) {
-    const i = ++this._taskCounter;
-    this._currentTaskId = i;
-    const n = () => this._currentTaskId === i, s = K(this.currentRouteLocation), r = async (o, u) => {
-      const a = this.createRouteLocation(o), h = (c = {}) => ({
-        from: s,
-        to: a,
-        status: g.success,
-        message: "导航成功",
-        redirectFrom: u ? t : void 0,
-        ...c
-      });
-      if (this.isSameNavigate(a, this.currentRouteLocation))
-        return h({
-          status: g.duplicated,
-          message: "导航到相同的路由，被系统阻止！"
-        });
-      try {
-        const c = await this.onBeforeEach(a, this.currentRouteLocation);
-        return c === !1 ? h({
-          status: g.aborted,
-          message: "导航被前置守卫钩子阻止"
-        }) : n() ? typeof c == "object" && c.index !== o.index ? (c.isReplace ?? (c.isReplace = !1), r(c, !0)) : a.matched.length ? (o.isReplace ? (this._pendingReplace = a, this.replaceHistory(a)) : (this._pendingPush = a, this.pushHistory(a)), h()) : h({
-          status: g.not_matched,
-          message: "未匹配到任何路由规则，被系统阻止！请检测目标索引是否正确。"
-        }) : h({
-          status: g.cancelled,
-          message: "已被新的导航请求替代，取消此次导航！"
-        });
-      } catch (c) {
-        return console.error("[Vitarx.Router.navigate][ERROR]：导航时捕获到了异常", c), h({
-          status: g.exception,
-          message: "导航时捕获到了异常",
-          error: c
-        });
-      }
-    };
-    return r(t, !1);
-  }
   /**
    * 更新路由数据
    *
@@ -762,7 +764,7 @@ const R = class R {
    * @param {RouteLocation} newLocation - 新的路由数据对象
    */
   updateRouteLocation(t) {
-    Rt(this._currentRouteLocation, t);
+    yt(this._currentRouteLocation, t);
   }
   /**
    * 判断是否为允许的后缀
@@ -815,19 +817,19 @@ const R = class R {
    * @protected
    */
   removeDynamicRoute(t) {
-    if (!O(t)) return;
+    if (!T(t)) return;
     const n = t.split("/").filter(Boolean).length, s = (o) => {
       const u = this._dynamicRoutes.get(o);
       if (u) {
-        for (let a = 0; a < u.length; a++)
-          if (u[a].route.path === t) {
-            u.splice(a, 1);
+        for (let c = 0; c < u.length; c++)
+          if (u[c].route.path === t) {
+            u.splice(c, 1);
             break;
           }
       }
     };
     s(n);
-    const r = ot(t);
+    const r = ut(t);
     if (r > 0)
       for (let o = 1; o <= r; o++)
         s(n - o);
@@ -849,8 +851,8 @@ const R = class R {
    * @protected
    */
   registerRoute(t, i) {
-    const n = dt(t);
-    if (i && (n.path = d(`${i.path}${n.path}`), this._parentRoute.set(n, i)), H(n)) {
+    const n = mt(t);
+    if (i && (n.path = R(`${i.path}${n.path}`), this._parentRoute.set(n, i)), A(n)) {
       t.widget && this.recordRoute(n);
       for (const s of n.children)
         this.registerRoute(s, n);
@@ -883,14 +885,14 @@ const R = class R {
     const i = this.strictPath(t.path);
     if (this._pathRoutes.has(i))
       throw new Error(`[Vitarx.Router][ERROR]：检测到重复的路由路径(path): ${t.path}`);
-    this._pathRoutes.set(i, t), O(t.path) && this.recordDynamicRoute(t);
+    this._pathRoutes.set(i, t), T(t.path) && this.recordDynamicRoute(t);
   }
   /**
    * 添加动态路由
    * @param route
    */
   recordDynamicRoute(t) {
-    const { regex: i, length: n, optional: s } = ct(
+    const { regex: i, length: n, optional: s } = lt(
       t.path,
       t.pattern,
       this.options.strict,
@@ -906,9 +908,9 @@ const R = class R {
 m = new WeakMap(), /**
  * 路由器实例，单例模式，用于全局获取路由器实例
  */
-x(R, m);
-let p = R;
-class mt extends p {
+_(g, m);
+let d = g;
+class xt extends d {
   constructor(t) {
     super(t), ["path", "hash"].includes(t.mode) && (t.mode = "path"), t.mode === "hash" && this.ensureHash();
   }
@@ -918,7 +920,7 @@ class mt extends p {
    * @returns {RouteTarget} - 包含 index、hash 和 query 的对象
    */
   get currentRouteTarget() {
-    return ut(window.location, this.mode, this.basePath);
+    return pt(window.location, this.mode, this.basePath);
   }
   /**
    * window.history
@@ -999,10 +1001,21 @@ class mt extends p {
       hash: t.state.hash,
       query: t.state.query
     } : i = this.currentRouteTarget, this.replace(i).then((s) => {
-      if (!s.redirectFrom && s.status === g.not_matched && this.mode === "hash" && s.to.index.startsWith("/")) {
-        const r = s.to.index.slice(1), o = window.document.getElementById(r);
-        o && o.scrollIntoView({ behavior: this.scrollBehavior }), this.updateHash(`#${r}`), this.webHistory.replaceState(this.createState(s.from), "", s.from.fullPath);
-      }
+      if (!s.redirectFrom && this.mode === "hash" && s.status !== p.success)
+        if (s.status === p.not_matched) {
+          if (s.to.index.startsWith("/")) {
+            const r = s.to.index.slice(1), o = window.document.getElementById(r);
+            o && o.scrollIntoView({ behavior: this.scrollBehavior }), this.updateHash(`#${r}`), this.webHistory.replaceState(
+              this.createState(this.currentRouteLocation),
+              "",
+              this.currentRouteLocation.fullPath
+            );
+          }
+        } else s.status === p.duplicated && this.webHistory.replaceState(
+          this.createState(this.currentRouteLocation),
+          "",
+          this.currentRouteLocation.fullPath
+        );
     });
   }
   /**
@@ -1018,7 +1031,7 @@ class mt extends p {
     }
   }
 }
-class C extends p {
+class F extends d {
   constructor(i) {
     super(i);
     // 路由历史记录数组
@@ -1046,7 +1059,7 @@ class C extends p {
     if (s === n) return;
     const r = this._history[s];
     this._pendingGo = s, this.navigate(r).then((o) => {
-      o.status !== g.success && (this._pendingGo = null);
+      o.status !== p.success && (this._pendingGo = null);
     });
   }
   /**
@@ -1087,39 +1100,39 @@ class C extends p {
     this._currentIndex = s, this.completeNavigation(i), this._pendingGo = null;
   }
 }
-function _t(...e) {
+function Et(...e) {
   return e;
 }
-function xt(e) {
+function $t(e) {
   return e;
 }
-function Pt(e) {
+function Lt(e) {
   let t;
-  return !(window != null && window.location) && e.mode !== "memory" ? (console.warn("当前环境非浏览器端，强制使用内存模式路由"), e.mode = "memory", new C(e).initialize()) : (e.mode === "memory" ? t = new C(e) : t = new mt(e), t.initialize());
+  return !(window != null && window.location) && e.mode !== "memory" ? (console.warn("当前环境非浏览器端，强制使用内存模式路由"), e.mode = "memory", new F(e).initialize()) : (e.mode === "memory" ? t = new F(e) : t = new xt(e), t.initialize());
 }
-function Et() {
-  return p.instance;
+function Vt() {
+  return d.instance;
 }
-function vt() {
-  return p.instance.currentRouteLocation;
+function Ot() {
+  return d.instance.currentRouteLocation;
 }
-function bt(e) {
-  return e[F] = !0, e;
+function jt(e) {
+  return e[U] = !0, e;
 }
-var $, y, w, P;
-const b = class b extends J {
+var E, y, w, x;
+const b = class b extends M {
   constructor(i) {
     super(i);
     // 自身index
-    x(this, y);
+    _(this, y);
     // 当前匹配的路由配置
-    x(this, w);
+    _(this, w);
     // 当前视图元素
-    x(this, P, Q());
-    const n = X(f(b, $), -1, this);
-    v(this, y, n + 1), Z(f(b, $), f(this, y), this), v(this, w, this.matchedRoute), f(this, w) && (f(this, P).value = p.routeView(f(this, w), this.name)), N(this.location.matched, (s, r) => {
+    _(this, x, N());
+    const n = tt(f(b, E), -1, this);
+    v(this, y, n + 1), et(f(b, E), f(this, y), this), v(this, w, this.matchedRoute), f(this, w) && (f(this, x).value = d.routeView(f(this, w), this.name)), it(this.location.matched, (s, r) => {
       const o = r[this.index];
-      o !== f(this, w) && (v(this, w, o), f(this, P).value = o ? p.routeView(o, this.name) : void 0);
+      o !== f(this, w) && (v(this, w, o), f(this, x).value = o ? d.routeView(o, this.name) : void 0);
     });
   }
   /**
@@ -1155,7 +1168,7 @@ const b = class b extends J {
    * @protected
    */
   get currentElement() {
-    return f(this, P).value;
+    return f(this, x).value;
   }
   /**
    * 当前的路由位置对象
@@ -1163,7 +1176,7 @@ const b = class b extends J {
    * @protected
    */
   get location() {
-    return p.instance.currentRouteLocation;
+    return d.instance.currentRouteLocation;
   }
   /**
    * @inheritDoc
@@ -1195,7 +1208,7 @@ const b = class b extends J {
    * @protected
    */
   build() {
-    return this.currentElement || V(tt);
+    return this.currentElement || V(nt);
   }
   /**
    * 视图渲染完成通知路由器
@@ -1203,21 +1216,96 @@ const b = class b extends J {
    * @private
    */
   completeViewRender() {
-    this.isLastView && p.instance._completeViewRender();
+    this.isLastView && d.instance._completeViewRender();
   }
 };
-$ = new WeakMap(), y = new WeakMap(), w = new WeakMap(), P = new WeakMap(), x(b, $, Symbol("RouterViewCounter"));
-let z = b;
+E = new WeakMap(), y = new WeakMap(), w = new WeakMap(), x = new WeakMap(), _(b, E, Symbol("RouterViewCounter"));
+let Y = b;
+class kt extends M {
+  constructor(i) {
+    super(i);
+    /**
+     * 路由目标
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    l(this, "target");
+    /**
+     * 路由目标对应的`RouteLocation`对象
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    l(this, "location");
+    /**
+     * 激活状态
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    l(this, "active");
+    l(this, "htmlProps");
+    this.target = new L(() => k(st(i.to) ? { index: i.to } : i.to)), this.location = new L(() => {
+      const n = d.instance.createRouteLocation(this.target.value);
+      return n.matched.length || console.trace(
+        `[Vitarx.RouterLink][WARN]：索引：${this.target.value.index}，未匹配到任何有效的路由线路，请检查to属性是否配置正确！`
+      ), k(n);
+    }), this.active = new L(() => this.location.value.fullPath === d.instance.currentRouteLocation.fullPath), this.htmlProps = new L(() => {
+      const n = {
+        href: this.href,
+        onClick: (s) => this.navigate(s),
+        children: this.children,
+        style: this.props.style,
+        class: this.props.class
+      };
+      return this.isActive && (n.active = !0), this.isDisabled && (n.disabled = !0), n;
+    });
+  }
+  /**
+   * 当前是否处于激活状态
+   */
+  get isActive() {
+    return this.active.value && !this.isDisabled;
+  }
+  get isDisabled() {
+    return this.props.disabled ?? !1;
+  }
+  /**
+   * 路由目标地址
+   */
+  get href() {
+    return this.location.value.fullPath;
+  }
+  /**
+   * 导航到目标路由
+   *
+   * 该方法用于处理`a`标签的点击事件
+   *
+   * @param e
+   */
+  navigate(i) {
+    i.stopPropagation(), i.preventDefault(), !this.isDisabled && d.instance.navigate(this.location.value).then();
+  }
+  build() {
+    return V("a", this.htmlProps.value);
+  }
+}
 export {
-  C as MemoryRouter,
-  g as NavigateStatus,
-  p as Router,
-  z as RouterView,
-  mt as WebHistoryRouter,
-  Pt as createRouter,
-  xt as defineRoute,
-  _t as defineRoutes,
-  bt as lazy,
-  vt as useRoute,
-  Et as useRouter
+  F as MemoryRouter,
+  p as NavigateStatus,
+  d as Router,
+  kt as RouterLink,
+  Y as RouterView,
+  xt as WebHistoryRouter,
+  Lt as createRouter,
+  $t as defineRoute,
+  Et as defineRoutes,
+  bt as generateRouteIndex,
+  jt as lazy,
+  Ot as useRoute,
+  Vt as useRouter
 };

package/dist/widget/RouterLink.d.ts

@@ -0,0 +1,80 @@
+import { Computed, Element, WebRuntimeDom, Widget } from 'vitarx';
+import { RouteIndex, RouteLocation, RouteTarget } from '../router/index.js';
+export interface RouterLinkProps {
+    /**
+     * 要跳转的目标
+     *
+     * 可以是路由目标对象，也可以是路由索引
+     */
+    to: RouteTarget | RouteIndex;
+    /**
+     * 子节点插槽
+     */
+    children: Element | Element[] | string;
+    /**
+     * a 标签的style属性
+     */
+    style?: WebRuntimeDom.HTMLStyleProperties;
+    /**
+     * a 标签的class属性
+     */
+    class?: WebRuntimeDom.HTMLClassProperties;
+    /**
+     * 是否禁用
+     *
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * # 路由跳转小部件
+ *
+ * 它只是简单的实现了一个a标签，点击后跳转到目标路由，
+ * 如果有更高级的定制需求，往往你可以项目中自行编写一个小部件来实现任何你想要的效果。
+ */
+export declare class RouterLink extends Widget<RouterLinkProps> {
+    /**
+     * 路由目标
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected target: Computed<RouteTarget>;
+    /**
+     * 路由目标对应的`RouteLocation`对象
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected location: Computed<RouteLocation>;
+    /**
+     * 激活状态
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected active: Computed<boolean>;
+    protected htmlProps: Computed<WebRuntimeDom.HtmlProperties<HTMLAnchorElement>>;
+    constructor(props: RouterLinkProps);
+    /**
+     * 当前是否处于激活状态
+     */
+    get isActive(): boolean;
+    get isDisabled(): boolean;
+    /**
+     * 路由目标地址
+     */
+    get href(): string;
+    /**
+     * 导航到目标路由
+     *
+     * 该方法用于处理`a`标签的点击事件
+     *
+     * @param e
+     */
+    protected navigate(e: MouseEvent): void;
+    protected build(): Element;
+}

package/dist/widget/index.d.ts

@@ -1 +1,2 @@
 export * from './RouterView.js';
+export * from './RouterLink.js';

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "vitarx-router",
-  "version": "0.0.1",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "main": "dist/vitarx-router.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "dev": "vite --force",
-    "build": "rimraf dist && tsc --p tsconfig-build.json && vite build",
+    "build:lib": "rimraf dist && tsc --p tsconfig-lib.json && vite --config vite.config.lib.ts build",
+    "build": "rimraf dist-web && vite build",
     "preview": "vite preview",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build:lib",
     "push": "npm publish --access=public"
   },
   "peerDependencies": {
@@ -18,7 +19,7 @@
     "@types/node": "^22.10.0",
     "prettier": "^3.3.1",
     "typescript": "^5.2.2",
-    "vite": "^5.2.0",
+    "vite": "^6.0.5",
     "vite-plugin-dts": "^4.3.0",
     "vite-plugin-vitarx": "^1.0.0-beta.13"
   },