vitarx-router 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/vitarx-router.d.ts

@@ -0,0 +1,1302 @@
+import { Computed } from 'vitarx';
+import { Element as Element_2 } from 'vitarx';
+import { LazyLoader } from 'vitarx';
+import { Reactive } from 'vitarx';
+import { VNode } from 'vitarx';
+import { WebRuntimeDom } from 'vitarx';
+import { Widget } from 'vitarx';
+import { WidgetType } from 'vitarx';
+
+/**
+ * 全局路由后置钩子
+ *
+ * 此时视图已经渲染完成，可以做一些操作，如：修改页面标题等。
+ *
+ * @this {Router} - 路由器实例
+ * @param {DeepReadonly<RouteLocation>} to - 当前路由数据
+ * @param {DeepReadonly<RouteLocation>} from - 从哪个路由跳转过来
+ */
+declare type AfterEachCallback = (this: Router, to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>) => void;
+
+/**
+ * 允许的路由小部件联合类型
+ */
+declare type AllowedRouteWidget = RouteWidget | NamedRouteWidget;
+
+/**
+ * 全局路由前置钩子
+ *
+ * 此时路由导航还未正式开始，此钩子常用于鉴权，如果不符合条件，可以返回false阻止路由，亦可以返回重定向目标。
+ *
+ * @this {Router} - 路由器实例
+ * @param {DeepReadonly<RouteLocation>} to - 要跳转的目标路由
+ * @param {DeepReadonly<RouteLocation>} from - 从哪个路由跳转过来
+ * @returns {boolean | RouteTarget | void} - 返回false表示阻止路由跳转，返回{@link RouteTarget}重定向目标
+ */
+export declare type BeforeEachCallback = (this: Router, to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>) => BeforeEachCallbackResult;
+
+/**
+ * 路由前置钩子返回值
+ *
+ * 1. 返回false表示阻止路由跳转，true表示继续路由跳转
+ * 2. 返回{@link RouteTarget}重定向目标
+ * 3. 返回void表示继续路由跳转
+ * @note 如果返回promise，则promise resolve的值会被作为返回值
+ */
+export declare type BeforeEachCallbackResult = boolean | RouteTarget | void | Promise<boolean | RouteTarget | void>;
+
+/**
+ * 创建内存路由器
+ *
+ * 不支持浏览器的前进后退等操作，只能通过实例中的方法来管理路由。
+ *
+ * 你必须调用一次`router.replace(target)`方法来跳转到目标路由。
+ *
+ * @param {RouterOptions} options - 配置
+ * @return {MemoryRouter} - 内存路由器实例
+ */
+export declare function createRouter(options: RouterOptions & {
+    mode: 'memory';
+}): MemoryRouter;
+
+/**
+ * 创建History路由器
+ *
+ * 基于History API实现路由功能，支持浏览器前进后退、刷新等操作。
+ *
+ * 它与`MemoryRouter`路由不同的是，它不需要初始化过后调用`router.replace(target)`方法来替换默认路由，
+ * 内部会自动根据`window.location`去匹配路由。
+ *
+ * @param {RouterOptions} options - 路由配置
+ * @return {WebHistoryRouter} - HistoryRouter实例
+ */
+export declare function createRouter(options: RouterOptions | (RouterOptions & {
+    mode: 'path' | 'hash';
+})): WebHistoryRouter;
+
+/**
+ * 定义路由
+ *
+ * 使用defineRoute定义路由可以获得更好的代码提示。
+ *
+ * @param {Route} route - 路由配置
+ */
+export declare function defineRoute(route: Route): Route;
+
+/**
+ * 定义路由表
+ *
+ * 使用defineRoutes定义路由表可以获得更好的代码提示。
+ *
+ * @param {Route[]} routes - 路由配置表
+ */
+export declare function defineRoutes(...routes: Route[]): Route[];
+
+/**
+ * 动态路由记录
+ */
+export declare interface DynamicRouteRecord {
+    regex: RegExp;
+    route: RouteNormalized;
+}
+
+/**
+ * hash字符串类型
+ */
+export declare type HashStr = `#${string}` | '';
+
+/**
+ * 路由模式
+ */
+export declare type HistoryMode = 'hash' | 'path' | 'memory';
+
+/**
+ * 已初始化的路由配置
+ */
+export declare type InitializedRouterOptions = MakeRequired<RouterOptions, Exclude<keyof RouterOptions, 'beforeEach' | 'afterEach'>>;
+
+/**
+ * 命名的props
+ */
+export declare type InjectNamedProps<k extends string = string> = Record<k, InjectProps>;
+
+/**
+ * 路由参数注入
+ */
+export declare type InjectProps = boolean | Record<string, any> | ((route: RouteLocation) => Record<string, any>);
+
+/**
+ * ## 标记延迟加载
+ *
+ * 由于直接定义`() => import('./xxx.js')`会导致类型与函数式组件冲突，
+ * 在未执行函数之前难以有效判断其类型，所以这里使用Symbol标记懒加载器。
+ *
+ * @example
+ * lazy(() => import('./xxx.js'))
+ *
+ * @template T - WidgetType
+ * @param {LazyLoader<T>} lazyLoader - 函数返回的import即是惰性加载器
+ */
+export declare function lazy<T extends WidgetType>(lazyLoader: LazyLoader<T>): LazyLoad<T>;
+
+declare const LAZY_LOADER_SYMBOL: unique symbol;
+
+declare type LAZY_LOADER_SYMBOL = typeof LAZY_LOADER_SYMBOL;
+
+/**
+ * 延迟加载/惰性加载
+ */
+export declare interface LazyLoad<T> {
+    [LAZY_LOADER_SYMBOL]: boolean;
+    (): Promise<{
+        default: T;
+    }>;
+}
+
+/**
+ * 路由匹配结果
+ */
+export declare type MatchResult = {
+    /**
+     * 匹配的路由对象
+     */
+    route: RouteNormalized;
+    /**
+     * path参数
+     *
+     * 非动态路由path，值固定为undefined
+     */
+    params: Record<string, string> | undefined;
+} | undefined;
+
+/**
+ * 基于内存实现的路由器
+ *
+ * 仅支持路由器操作前进、后退、跳转等操作
+ *
+ * > 注意：不要在浏览器端使用，因为浏览器端有原生的history对象，使用内存模式会和浏览器端的历史记录冲突，导致路由异常。
+ */
+export declare class MemoryRouter extends Router {
+    protected _history: RouteLocation[];
+    protected _pendingGo: number | null;
+    constructor(options: RouterOptions<'memory'>);
+    private _currentIndex;
+    /**
+     * 当前历史路由索引
+     *
+     * @protected
+     */
+    protected get currentIndex(): number;
+    /**
+     * @inheritDoc
+     */
+    go(delta?: number): void;
+    /**
+     * @inheritDoc
+     */
+    protected initializeRouter(): void;
+    /**
+     * 添加历史记录
+     */
+    protected pushHistory(data: RouteLocation): void;
+    /**
+     * 替换历史记录
+     */
+    protected replaceHistory(data: RouteLocation): void;
+    /**
+     * 更新历史记录
+     *
+     * @param {RouteLocation} data - 目标路由
+     * @param {boolean} isReplace - 是否为替换操作
+     * @private
+     */
+    private _updateHistory;
+}
+
+/**
+ * 命名的路由视图小部件
+ */
+declare type NamedRouteWidget<K extends string = string> = Record<K, RouteWidget>;
+
+/**
+ * 导航结果
+ */
+export declare interface NavigateResult {
+    /**
+     * 状态
+     *
+     * @see NavigateStatus
+     */
+    status: NavigateStatus;
+    /**
+     * 状态描述
+     */
+    message: string;
+    /**
+     * 最终的导航数据
+     *
+     * 它和守卫钩子`to`参数一致。
+     */
+    to: Readonly<RouteLocation>;
+    /**
+     * 导航完成前的路由数据
+     *
+     * 它和守卫钩子`from`参数一致。
+     */
+    from: Readonly<RouteLocation>;
+    /**
+     * 如果在守卫过程中被重定向，则redirectFrom为最初的路由目标，否则为undefined。
+     */
+    redirectFrom: RouteTarget | undefined;
+    /**
+     * 捕获到的异常
+     */
+    error?: unknown;
+}
+
+/**
+ * 导航结果
+ *
+ * 枚举值：
+ * 0. success: 导航成功
+ * 1. aborted: 导航被阻止
+ * 2. cancelled: 导航被取消
+ * 3. duplicated: 重复导航
+ * 4. not_matched: 路由未匹配
+ * 5. exception: 捕获到异常
+ */
+export declare enum NavigateStatus {
+    /**
+     * 导航成功
+     */
+    success = 0,
+    /**
+     * 导航被阻止
+     */
+    aborted = 1,
+    /**
+     * 导航被取消
+     *
+     * 正在等待中间件处理结果时又触发了新的导航请求
+     */
+    cancelled = 2,
+    /**
+     * 重复导航
+     */
+    duplicated = 3,
+    /**
+     * 路由未匹配
+     */
+    not_matched = 4,
+    /**
+     * 捕获到异常
+     */
+    exception = 5
+}
+
+/**
+ * 路由路线配置
+ *
+ * @template WIDGET 允许的路由小部件类型，用于类型重载
+ */
+export declare interface Route<WIDGET extends AllowedRouteWidget = AllowedRouteWidget> {
+    /**
+     * 路由路径
+     *
+     * 支持动态路由参数
+     *
+     * example:
+     * `/user` // 静态路径
+     * `/user/{id}` // 必填参数
+     * `/user/{id?}` // 可选参数
+     * `/user/{id?}/{name}` // 错误的用例，可选参数后面不能再有其他参数
+     */
+    path: RoutePath;
+    /**
+     * 动态路由参数匹配规则
+     *
+     * @example
+     * path:`/user/[id]`
+     * pattern:{id:'\d+'}
+     */
+    pattern?: Record<string, RegExp>;
+    /**
+     * 路由名称
+     *
+     * 必须全局保持唯一！
+     */
+    name?: string;
+    /**
+     * 要展示的Widget
+     *
+     * 支持两种类型：
+     *  1. WidgetType: `YourWidget` 可以是函数式小部件，也可以是类小部件
+     *  2. LazyLoad: `() => import('./YourWidget')` 代码分块，懒加载，它会自动被LazyWidget包裹。
+     *  3. undefined: 自身不展示任何ui，仅做为父路由，使children继承父路由的`path`和`pattern`。
+     *  4. Record<string, WidgetType | LazyLoad<WidgetType>>: 命名的小部件，同级的`RouterView`会根据name属性展示对应的小部件。
+     */
+    widget?: WIDGET;
+    /**
+     * 子路由
+     *
+     * 子路由path不要以父路由path开头，内部会自动拼接。
+     */
+    children?: Route[];
+    /**
+     * 路由元数据
+     *
+     * 存储一些自定义的数据，不会影响路由匹配
+     */
+    meta?: RouteMeta;
+    /**
+     * 将路由参数注入到小部件实例的props中
+     *
+     * 如果是命名视图，则必须定义给每个命名视图定义`props`配置
+     *
+     * @default true
+     */
+    injectProps?: (WIDGET extends NamedRouteWidget<infer k> ? InjectNamedProps<k> : InjectProps) | boolean;
+}
+
+/**
+ * 路由索引
+ */
+export declare type RouteIndex = RoutePath | RouteName | VitarxRouterRouteIndexTyped;
+
+/**
+ * 路由匹配的详情数据
+ *
+ * 所有和url相关的数据都已`decodeURIComponent`解码
+ */
+export declare interface RouteLocation {
+    /**
+     * 路由索引，调用`push`|`replace`时传入的index
+     */
+    index: RouteIndex;
+    /**
+     * 完整的path，包含了query和hash
+     *
+     * 1. path|memory模式：`${base}${path}${query}${hash}`
+     * 2. hash模式：`${base}/#${path}${query}${hash}`
+     */
+    fullPath: string;
+    /**
+     * pathname
+     *
+     * 如果是`hash`模式，pathname和`window.location.pathname`获取的值是不一致的，因为它是从`window.location.hash`中提取出来的
+     */
+    path: `/${string}`;
+    /**
+     * hash
+     *
+     * 带有#前缀，空字符串代表没有hash。
+     *
+     * @default ''
+     */
+    hash: HashStr;
+    /**
+     * 动态路由path匹配的参数，包括调用`push`|`replace`时传入的params
+     *
+     * > 注意：必须是能够被序列化的参数，否则会导致异常。
+     *
+     * @default {}
+     */
+    params: Record<string, any>;
+    /**
+     * search参数
+     *
+     * @default {}
+     */
+    query: Record<string, string>;
+    /**
+     * 路由线路配置的元数据
+     *
+     * 如果没有配置元数据，那它将会是空对象，未匹配到任何路由也会是空对象。
+     *
+     * @default {}
+     */
+    meta: RouteMeta;
+    /**
+     * 匹配的路由对象
+     *
+     * > 注意：如果数组中存在多个`RouteNormalized`对象，则说明是嵌套路由，第一个则是最顶层的父路由，最后一个是精确匹配到的路由。
+     *
+     * 未匹配到路由时，它会是空数组。
+     *
+     * @default []
+     */
+    matched: RouteNormalized[];
+}
+
+/**
+ * 路由元数据
+ */
+export declare interface RouteMeta {
+    [key: string]: any;
+}
+
+/**
+ * 命名路由
+ */
+export declare type RouteName = string;
+
+/**
+ * 规范化过后的路由线路配置
+ */
+export declare interface RouteNormalized extends MakeRequired<Route, 'meta' | 'pattern'> {
+    children: RouteNormalized[];
+    widget: undefined | Record<string, RouteWidget>;
+    injectProps: undefined | InjectNamedProps;
+}
+
+export declare interface RouteOptions {
+    /**
+     * 命名视图
+     *
+     * @default 'default'
+     */
+    name?: string;
+}
+
+/**
+ * 路由路径
+ */
+export declare type RoutePath = `/${string}`;
+
+/**
+ * 路由器基类
+ */
+export declare abstract class Router {
+    #private;
+    private readonly _options;
+    private readonly _namedRoutes;
+    private readonly _dynamicRoutes;
+    private readonly _pathRoutes;
+    private readonly _parentRoute;
+    private _currentTaskId;
+    private _taskCounter;
+    /**
+     * 是否正在执行 replace 操作
+     *
+     * @private
+     */
+    private _pendingReplace;
+    /**
+     * 是否正在执行 push 操作
+     *
+     * @private
+     */
+    private _pendingPush;
+    private _scrollBehaviorHandler;
+    private readonly _currentRouteLocation;
+    protected constructor(options: RouterOptions);
+    /**
+     * 获取单例实例
+     *
+     * @return {Router} - 路由器实例
+     */
+    static get instance(): Router;
+    private _isBrowser;
+    /**
+     * 是否运行在浏览器端
+     */
+    get isBrowser(): boolean;
+    private _scrollBehavior;
+    /**
+     * 滚动行为
+     *
+     * 如果options.scrollBehavior为函数，则scrollBehavior固定为auto'。
+     */
+    get scrollBehavior(): _ScrollBehavior;
+    /**
+     * 获取配置
+     *
+     * @return {Readonly<InitializedRouterOptions>} - 初始化配置
+     */
+    get options(): Readonly<InitializedRouterOptions>;
+    /**
+     * 路由器模式
+     */
+    get mode(): HistoryMode;
+    /**
+     * 获取所有路由映射
+     *
+     * map键值是path，值是路由对象
+     *
+     * @return {Map<string, Route>}
+     */
+    get pathRoutes(): ReadonlyMap<string, Route>;
+    /**
+     * 获取所有命名路由映射
+     *
+     * map键值是name，值是路由对象
+     *
+     * @return {Map<string, Route>}
+     */
+    get namedRoutes(): ReadonlyMap<string, Route>;
+    /**
+     * 动态路由记录
+     *
+     * map键值是path段长度，值是Array<{regex: RegExp,route:RouteNormalized}>
+     */
+    get dynamicRoutes(): Map<number, DynamicRouteRecord[]>;
+    /**
+     * ## 获取已规范的路由表
+     *
+     * 它的内存地址始终指向的是初始化时传入的路由表，但它的数据结构是经过内部规范化处理过的。
+     *
+     * 所有嵌套`Route`的path都会被自动补全为完整的路径
+     *
+     * > 注意：不要尝试修改已规范化的路由表！请使用`removeRoute`和`addRoute`方法实现路由的变更。
+     *
+     * @return {RouteNormalized[]}
+     */
+    get routes(): ReadonlyArray<RouteNormalized>;
+    /**
+     * 基本路径
+     */
+    get basePath(): `/${string}`;
+    /**
+     * 判断路由器是否初始化完成
+     *
+     * @return {boolean} - 如果初始化完成，返回true，否则返回false
+     */
+    get initialized(): boolean;
+    /**
+     * 受支持的`path`后缀名
+     */
+    get suffix(): Exclude<RouterOptions['suffix'], void>;
+    /**
+     * 当前路由数据
+     *
+     * 它是只读的，不要在外部修改它！
+     *
+     * @return {Readonly<RouteLocation>} - 当前路由数据
+     */
+    get currentRouteLocation(): Readonly<Reactive<RouteLocation>>;
+    /**
+     * 是否处于等待状态
+     *
+     * @protected
+     */
+    protected get isPendingNavigation(): boolean;
+    /**
+     * 等待替换完成的数据
+     *
+     * @protected
+     */
+    protected get pendingReplaceData(): RouteLocation | null;
+    /**
+     * 等待跳转完成的数据
+     *
+     * @protected
+     */
+    protected get pendingPushData(): RouteLocation | null;
+    /* Excluded from this release type: routeView */
+    /**
+     * 跳转指定的历史记录位置
+     *
+     * 如果未向该函数传参或delta相等于 0，则该函数与调用location.reload()具有相同的效果。
+     *
+     * @param {number} delta - 跳转的步数（正数为前进，负数为后退）
+     */
+    abstract go(delta?: number): void;
+    /**
+     * 后退到上一个历史记录
+     */
+    back(): void;
+    /**
+     * 前进到下一个历史记录
+     */
+    forward(): void;
+    /**
+     * 替换当前页面
+     *
+     * @param {RouteTarget} target - 目标
+     * @return {boolean} - 是否跳转成功，非内存模式始终返回true
+     */
+    replace(target: RouteTarget | RouteIndex): Promise<NavigateResult>;
+    /**
+     * 跳转到新的页面
+     *
+     * @param {RouteTarget} target - 目标
+     * @return {boolean} - 是否跳转成功，非内存模式始终返回true
+     */
+    push(target: RouteTarget | RouteIndex): Promise<NavigateResult>;
+    /**
+     * 删除路由
+     *
+     * @param {string} index 路由索引，如果/开头则匹配path，其他匹配name
+     * @param {boolean} isRemoveFromRoutes 是否从路由表中移除，内部递归时传递的参数，无需外部传入！
+     */
+    removeRoute(index: RouteIndex, isRemoveFromRoutes?: boolean): void;
+    /**
+     * 添加路由
+     *
+     * @param {Route} route - 路由描述对象
+     * @param {string} parent - 父路由的path或name，不传入则添加至路由表根节点
+     */
+    addRoute(route: Route, parent?: string): void;
+    /**
+     * 超找路由
+     *
+     * 传入的是`path`则会调用`matchRoute`方法，传入的是`name`则会调用`getNamedRoute`方法
+     *
+     * @param {RouteIndex|RouteTarget} target - 路由索引，如果index以/开头则匹配path，其他匹配name
+     * @return {RouteNormalized | undefined} - 路由对象，如果不存在则返回undefined
+     */
+    findRoute(target: RouteIndex | RouteTarget): RouteNormalized | undefined;
+    /**
+     * 查找命名路由
+     *
+     * @param {string} name - 路由名称
+     */
+    findNamedRoute(name: RouteName): RouteNormalized | undefined;
+    /**
+     * 初始化路由器
+     *
+     * 只能初始化一次，多次初始化无效。
+     *
+     * 如果你使用的`createRouter(options)`助手函数创建的路由器实例则无需调用该方法。
+     *
+     * @return {this} - 返回当前路由器实例
+     */
+    initialize(): this;
+    /**
+     * 此方法用于浏览器端滚动到指定位置
+     *
+     * @param scrollTarget
+     * @protected
+     */
+    scrollTo(scrollTarget: ScrollTarget | undefined): void;
+    /**
+     * 获取路由的父路由
+     *
+     * @param route - 路由对象
+     * @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>;
+    /* Excluded from this release type: _completeViewRender */
+    /**
+     * 完成导航
+     *
+     * 所有子类在完成导航的后续处理过后必须调用该方法！
+     *
+     * @param {RouteLocation} data - 如果是由`replace`或`push`方法发起的导航则无需传入此参数。
+     * @param {_ScrollToOptions} savedPosition - 保存的滚动位置信息，用于恢复滚动位置
+     * @protected
+     */
+    protected completeNavigation(data?: RouteLocation, savedPosition?: _ScrollToOptions): void;
+    /**
+     * 更新当前导航数据中的query参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {Record<string, string>} query - 新的query参数对象
+     * @protected
+     */
+    protected updateQuery(query: Record<string, string>): void;
+    /**
+     * 更新当前导航数据中的hash参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {`#${string}` | ''} hash - 新的hash参数，如果为空则表示无hash
+     * @protected
+     */
+    protected updateHash(hash: `#${string}` | ''): void;
+    /**
+     * 初始化路由器
+     *
+     * 子类可重写此方法以完成路由器的初始化
+     *
+     * @private
+     */
+    protected abstract initializeRouter(): void;
+    /**
+     * 路由匹配
+     *
+     *
+     * @param {string} path - 路径
+     *
+     * @return {MatchResult} 如果匹配失败则返回undefined
+     */
+    protected matchRoute(path: RoutePath): MatchResult;
+    /**
+     * 创建完整路径
+     *
+     * @protected
+     * @param path - 路径
+     * @param query - ?查询参数
+     * @param hash - #哈希值
+     * @return {string}
+     */
+    protected makeFullPath(path: string, query: `?${string}` | '' | Record<string, string>, hash: HashStr): `/${string}`;
+    /**
+     * 添加历史记录
+     *
+     * 子类必须实现该方法
+     *
+     * @param data
+     * @protected
+     */
+    protected abstract pushHistory(data: RouteLocation): void;
+    /**
+     * 替换历史记录
+     *
+     * 子类必须实现该方法
+     *
+     * @param {RouteLocation} data - 目标路由
+     * @protected
+     */
+    protected abstract replaceHistory(data: RouteLocation): void;
+    /**
+     * 判断是否相同的导航请求
+     *
+     * @param to
+     * @param from
+     * @protected
+     */
+    protected isSameNavigate(to: RouteLocation, from: RouteLocation): boolean;
+    /**
+     * 触发路由前置守卫
+     *
+     * @param {DeepReadonly<RouteLocation>} to - 路由目标对象
+     * @param {DeepReadonly<RouteLocation>} from - 前路由对象
+     * @return {false | RouteTarget} - 返回false表示阻止导航，返回新的路由目标对象则表示导航到新的目标
+     */
+    protected onBeforeEach(to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>): BeforeEachCallbackResult;
+    /**
+     * 触发路由后置守卫
+     *
+     * @param {DeepReadonly<RouteLocation>} to - 路由目标对象
+     * @param {DeepReadonly<RouteLocation>} from - 前路由对象
+     */
+    protected onAfterEach(to: DeepReadonly<RouteLocation>, from: DeepReadonly<RouteLocation>): void;
+    /**
+     * 更新路由数据
+     *
+     * @private
+     * @param {RouteLocation} newLocation - 新的路由数据对象
+     */
+    private updateRouteLocation;
+    /**
+     * 判断是否为允许的后缀
+     *
+     * @param suffix
+     * @private
+     */
+    private isAllowedSuffix;
+    /**
+     * 触发滚动行为
+     *
+     * @param {RouteLocation} to - 目标导航数据对象
+     * @param {RouteLocation} from - 前导航数据对象
+     * @param {_ScrollToOptions | undefined} savedPosition - 保存的滚动位置
+     * @private
+     */
+    private onScrollBehavior;
+    /**
+     * 从源路由表中删除路由
+     *
+     * @param route
+     * @protected
+     */
+    private removedFromRoutes;
+    /**
+     * 删除动态路由映射
+     *
+     * @param path
+     * @protected
+     */
+    private removeDynamicRoute;
+    /**
+     * 初始化路由表
+     *
+     * @param routes
+     */
+    private setupRoutes;
+    /**
+     * 注册路由
+     *
+     * @param {Route} route - 路由对象
+     * @param {RouteNormalized} group - 路由所在的分组
+     * @protected
+     */
+    private registerRoute;
+    /**
+     * 如果路径是严格匹配，则转换为小写
+     *
+     * @param path
+     * @private
+     */
+    private strictPath;
+    /**
+     * 记录路由
+     *
+     * @param {Route} route - 路由对象
+     * @protected
+     */
+    private recordRoute;
+    /**
+     * 添加动态路由
+     * @param route
+     */
+    private recordDynamicRoute;
+}
+
+/**
+ * # 路由跳转小部件
+ *
+ * 它只是简单的实现了一个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_2;
+}
+
+export declare interface RouterLinkProps {
+    /**
+     * 要跳转的目标
+     *
+     * 可以是路由目标对象，也可以是路由索引
+     */
+    to: RouteTarget | RouteIndex;
+    /**
+     * 子节点插槽
+     */
+    children: Element_2 | Element_2[] | string;
+    /**
+     * a 标签的style属性
+     */
+    style?: WebRuntimeDom.HTMLStyleProperties;
+    /**
+     * a 标签的class属性
+     */
+    class?: WebRuntimeDom.HTMLClassProperties;
+    /**
+     * 是否禁用
+     *
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+/**
+ * 路由器配置
+ */
+export declare interface RouterOptions<T_MODE extends HistoryMode = HistoryMode> {
+    /**
+     * 根路径
+     *
+     * 假设你的项目在`/sub-path`目录下运行，那么你需要设置该值为`/sub-path`，它与`vite.base`配置值应保持一致。
+     *
+     * @default '/'
+     */
+    base?: `/${string}`;
+    /**
+     * 历史记录模式
+     *
+     * 可选值如下：
+     * 1. path模式：使用path值作为路由标识，如：`/page1`
+     * 2. hash模式：使用hash值作为路由标识，如：`/#/page1`
+     * 3. memory模式：内存模式，用于非浏览器端，或不需要使用浏览器回退和前进功能时使用。
+     *
+     * @note 使用memory模式需在路由器实例化完成后使用replace替换掉初始的伪路由，另外两种模式是浏览器端使用的，会自动完成这个操作！
+     * @default 'path' 默认视为是浏览器端
+     */
+    mode?: T_MODE;
+    /**
+     * 是否严格匹配路由
+     *
+     * 严格匹配指：区分大小写
+     *
+     * @default false
+     */
+    strict?: boolean;
+    /**
+     * 路由表
+     *
+     * @note 注意：路由表传入过后，不应该在外部进行修改，如需修改需使用`Router.removeRoute`或`Router.addRoute`方法。
+     */
+    routes: Route[];
+    /**
+     * 全局路由前置钩子
+     *
+     * @see BeforeEachCallback
+     */
+    beforeEach?: BeforeEachCallback;
+    /**
+     * 全局路由后置钩子
+     *
+     * @see AfterEachCallback
+     */
+    afterEach?: AfterEachCallback;
+    /**
+     * 滚动行为
+     *
+     * 可以传入`ScrollBehavior`或`ScrollBehaviorHandler`函数自定义滚动行为。
+     *
+     * @default 'smooth'
+     */
+    scrollBehavior?: _ScrollBehavior | ScrollBehaviorHandler;
+    /**
+     * 支持的后缀名，如：.html、.md等。
+     *
+     * 可选值类型：
+     * 1. 通配符：`*`：支持所有后缀名，如：`/page.html`、`/page.md`等。
+     * 2. 字符串类型：`html`：支持html后缀名
+     * 3. 数组：`['html','md']`：同时支持html和md后缀名，注意不要以`.`开头
+     * 4. false：不做任何处理，硬性匹配。
+     * @default false
+     */
+    suffix?: '*' | string | string[] | false;
+    /**
+     * 默认path变量匹配模式
+     *
+     * @default '/[\w.]+/'
+     */
+    pattern?: RegExp;
+}
+
+/**
+ * # 路由器视图
+ *
+ * 用于渲染路由线路配置的`widget`，可以在子组件中嵌套`RouterView`，但应用内只能存在一个根视图。
+ *
+ * 如需实现页面缓存等功能，可以重写该类的{@link build}方法。
+ */
+export declare class RouterView extends Widget<RouteOptions> {
+    #private;
+    constructor(props: RouteOptions);
+    /**
+     * 当前路由器视图所在层级索引
+     *
+     * `index`的值从0开始，它与`RouteLocation.matched`数组下标一一对应
+     */
+    get index(): number;
+    /**
+     * 是否为最后一个路由视图
+     */
+    get isLastView(): boolean;
+    /**
+     * 视图名称
+     *
+     * @default 'default'
+     */
+    get name(): string;
+    get matchedRoute(): RouteNormalized | undefined;
+    /**
+     * 当前路由器视图要显示的虚拟节点
+     *
+     * 注意未匹配时会返回`undefined`，匹配成功时返回的是`VNode<WidgetType>`
+     *
+     * @protected
+     */
+    protected get currentElement(): VNode | undefined;
+    /**
+     * 当前的路由位置对象
+     *
+     * @protected
+     */
+    protected get location(): Readonly<Reactive<RouteLocation>>;
+    /**
+     * @inheritDoc
+     */
+    protected onMounted(): void;
+    /**
+     * @inheritDoc
+     */
+    protected onUpdated(): void;
+    /**
+     * ## 构建视图
+     *
+     * 可以重写该方法添加自定义的视图元素
+     *
+     * 例如，使用`KeepAlive`组件缓存当前视图元素：
+     * ```tsx
+     * protected build() {
+     *   // 不可省略，因为`KeepAlive`不能渲染非组件节点。
+     *   if (!this.currentElement) return <></> // 使用空片段节点占位
+     *
+     *   // 将当前显示的视图元素(VNode<WidgetType>对象)传递给`KeepAlive`插槽，使用缓存功能。
+     *   return <KeepAlive onlyKey={this.matchedRoute?.path}>{this.currentElement}</KeepAlive>
+     * }
+     * ```
+     * @protected
+     */
+    protected build(): Element_2;
+    /**
+     * 视图渲染完成通知路由器
+     *
+     * @private
+     */
+    private completeViewRender;
+}
+
+/**
+ * 路由目标
+ */
+export declare interface RouteTarget {
+    /**
+     * 索引，/开头为路径，否则为名称
+     */
+    index: RouteIndex;
+    /**
+     * hash
+     */
+    hash?: HashStr;
+    /**
+     * 路由query参数
+     */
+    query?: Record<string, string>;
+    /**
+     * 路由参数
+     */
+    params?: Record<string, any>;
+    /**
+     * 是否替换当前路由
+     */
+    isReplace?: boolean;
+}
+
+/**
+ * 路由视图小部件
+ */
+declare type RouteWidget = WidgetType | LazyLoad<WidgetType>;
+
+/**
+ * 滚动行为
+ *
+ * 1. auto: 默认值，浏览器会自动决定滚动行为
+ * 2. instant: 立即滚动到目标位置，不考虑动画效果
+ * 3. smooth: 平滑滚动到目标位置，考虑动画效果
+ */
+export declare type _ScrollBehavior = 'auto' | 'instant' | 'smooth';
+
+/**
+ * 滚动行为处理器
+ *
+ * 仅浏览器环境有效。
+ *
+ * @param {RouteLocation} to - 要跳转的目标路由
+ * @param {RouteLocation} from - 从哪个路由跳转过来
+ * @param {_ScrollToOptions|undefined} savedPosition - 保存滚动位置，仅`history`模式前进或后退时有效
+ * @returns {ScrollResult} - 返回滚动结果，由内部程序完成滚动
+ */
+export declare type ScrollBehaviorHandler = (to: RouteTarget, from: RouteTarget, savedPosition: _ScrollToOptions | undefined) => ScrollResult | Promise<ScrollResult>;
+
+/**
+ * 滚动到视图配置
+ *
+ * @see https://developer.mozilla.org/zh-CN/docs/Web/API/Element/scrollIntoView
+ */
+export declare interface _ScrollIntoViewOptions extends ScrollIntoViewOptions {
+    el: Element | `#${string}` | string;
+}
+
+/**
+ * 滚动结果
+ *
+ * false表示不滚动，否则内部会根据`ScrollTarget`滚动到指定的位置
+ */
+declare type ScrollResult = ScrollTarget | false;
+
+/**
+ * 滚动目标
+ */
+export declare type ScrollTarget = _ScrollToOptions | _ScrollIntoViewOptions;
+
+/**
+ * 滚动配置
+ *
+ * @see https://developer.mozilla.org/zh-CN/docs/Web/API/Window/scrollTo
+ */
+export declare interface _ScrollToOptions {
+    /**
+     * 滚动到目标位置的X坐标
+     */
+    left?: number;
+    /**
+     * 滚动到目标位置的Y坐标
+     */
+    top?: number;
+    /**
+     * 滚动行为
+     *
+     * @see _ScrollBehavior
+     */
+    behavior?: _ScrollBehavior;
+}
+
+/**
+ * 获取当前`RouteLocation`对象
+ *
+ * 它是`Router.instance.currentRouteLocation`属性的助手函数，优化函数式编程体验。
+ *
+ * 简单示例：
+ * ```jsx
+ * import { useRoute } from 'vitarx-router'
+ *
+ * // 监听路由参数变化示例
+ * export default function App() {
+ *  const route = useRoute()
+ *  watch(()=>route.params.id, (newId, oldId) => {
+ *   console.log(`监听到id参数变化, 旧值：${oldId}, 新值：${newId}`)
+ *  })
+ *  return <div>当前路由参数ID：{route.params.id}</div>
+ * }
+ * ```
+ *
+ * @return {Readonly<Reactive<RouteLocation>>} - 只读的`RouteLocation`对象
+ */
+export declare function useRoute(): Readonly<Reactive<RouteLocation>>;
+
+/**
+ * 获取路由器实例
+ *
+ * 与使用`Router.instance`静态属性获取是一致的效果。
+ *
+ * @return {Router} - 路由器实例
+ * @throws {Error} - 如果路由器实例未初始化，则抛出异常
+ */
+export declare function useRouter<T extends Router>(): T;
+
+/**
+ * 基于`window.history`实现的路由器
+ *
+ * 支持浏览器前进、后退、跳转等操作
+ */
+export declare class WebHistoryRouter extends Router {
+    constructor(options: RouterOptions<'path' | 'hash'>);
+    /**
+     * 当前路由目标
+     *
+     * @returns {RouteTarget} - 包含 index、hash 和 query 的对象
+     */
+    protected get currentRouteTarget(): MakeRequired<RouteTarget, 'query' | 'hash'>;
+    /**
+     * window.history
+     *
+     * @private
+     */
+    private get webHistory();
+    /**
+     * @inheritDoc
+     */
+    go(delta?: number): void;
+    /**
+     * @inheritDoc
+     */
+    protected initializeRouter(): void;
+    /**
+     * @inheritDoc
+     */
+    protected pushHistory(data: RouteLocation): void;
+    /**
+     * @inheritDoc
+     */
+    protected replaceHistory(data: RouteLocation): void;
+    /**
+     * 保存当前页面滚动位置
+     *
+     * @private
+     */
+    private saveCurrentScrollPosition;
+    /**
+     * 创建历史记录状态
+     *
+     * 用于在浏览器历史记录中存储路由信息，以支持前进、后退等操作。
+     *
+     * @param data - 路由数据
+     * @param hash - 要替换的哈希值
+     * @param query - 要替换的查询参数
+     * @private
+     */
+    private createState;
+    /**
+     * 处理浏览器历史记录的返回/前进事件
+     */
+    private onPopState;
+    /**
+     * 确保路径是 hash 格式
+     *
+     * @private
+     */
+    private ensureHash;
+}
+
+export { }
+
+
+declare global {
+    /**
+     * 此全局类型用于，扩展路由索引类型，完善路由索引提示，提升开发体验。
+     *
+     * @example
+     * ```ts
+     * // 在项目中的全局类型声明文件中写入如下类型即可在使用push,replace方法时提示路由索引
+     * type VitarxRouterRouteIndexTyped = 'home'|'page' // 添加自定义的路由
+     * ```
+     */
+    type VitarxRouterRouteIndexTyped = string;
+}