vitarx-router 1.0.0 → 1.0.2

package/dist/vitarx-router.d.ts

@@ -1 +1,1399 @@
+import { Computed } from 'vitarx';
+import { Element as Element_2 } from 'vitarx';
+import { HTMLClassProperties } from 'vitarx';
+import { HTMLProperties } from 'vitarx';
+import { HTMLStyleProperties } from 'vitarx';
+import { LazyLoader } from 'vitarx';
+import { RouteLocation as RouteLocation_2 } from '../index.js';
+import { VNode } from 'vitarx';
+import { Widget } from 'vitarx';
+import { WidgetType } from 'vitarx';
+
+/**
+ * 路由后置钩子
+ *
+ * 在导航确认后调用
+ *
+ * @param this - 路由器实例
+ * @param to - 即将要进入的目标路由对象
+ * @param from - 当前导航正要离开的路由对象
+ */
+export declare type AfterEnterCallback = (this: Router, to: ReadonlyRouteLocation, from: ReadonlyRouteLocation) => void;
+
+/**
+ * 允许的路由小部件联合类型
+ *
+ * 可以是单个视图组件或命名视图组件的记录
+ */
+export declare type AllowedRouteWidget = RouteWidget | NamedRouteWidget;
+
+/**
+ * 路由前置钩子返回值
+ *
+ * - boolean: true继续导航,false阻止导航
+ * - RouteTarget: 重定向到新的目标
+ * - void: 继续导航
+ * - Promise: 异步处理,resolve的值同上
+ */
+export declare type BeforeEachCallbackResult = boolean | RouteTarget | void | Promise<boolean | RouteTarget | void>;
+
+/**
+ * 路由前置钩子
+ *
+ * 在导航确认前调用,可以通过返回false来取消导航
+ *
+ * @param this - 路由器实例
+ * @param to - 即将要进入的目标路由对象
+ * @param from - 当前导航正要离开的路由对象
+ */
+export declare type BeforeEnterCallback = (this: Router, to: ReadonlyRouteLocation, from: ReadonlyRouteLocation) => BeforeEachCallbackResult;
+
+/**
+ * 创建内存路由器
+ *
+ * 不支持浏览器的前进后退等操作，只能通过实例中的方法来管理路由。
+ *
+ * 你必须调用一次`router.replace(target)`方法来跳转到目标路由。
+ *
+ * @param {RouterOptions} options - 配置
+ * @return {RouterMemory} - 内存路由器实例
+ */
+export declare function createRouter(options: RouterOptions & {
+    mode: 'memory';
+}): MemoryRouter;
+
+/**
+ * 创建History路由器
+ *
+ * 基于History API实现路由功能，支持浏览器前进后退、刷新等操作。
+ *
+ * 它与`MemoryRouter`路由不同的是，它不需要初始化过后调用`router.replace(target)`方法来替换默认路由，
+ * 内部会自动根据`window.location`去匹配路由。
+ *
+ * @param {RouterOptions} options - 路由配置
+ * @return {RouterHistory} - HistoryRouter实例
+ */
+export declare function createRouter(options: RouterOptions | (RouterOptions & {
+    mode: 'path' | 'hash';
+})): HistoryRouter;
+
+/**
+ * 定义路由
+ *
+ * 使用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}` | '';
+
+/**
+ * 路由模式
+ *
+ * - hash: 使用URL hash实现路由
+ * - path: 使用HTML5 History API实现路由
+ * - memory: 使用内存实现路由
+ */
+export declare type HistoryMode = 'hash' | 'path' | 'memory';
+
+/**
+ * 基于`window.history`实现的路由器
+ *
+ * 支持浏览器前进、后退、跳转等操作
+ */
+export declare class HistoryRouter 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;
+}
+
+declare type HttpUrl = `http://${string}`;
+
+/**
+ * 已初始化的路由配置
+ */
+export declare type InitializedRouterOptions = MakeRequired<RouterOptions, Exclude<keyof RouterOptions, 'beforeEach' | 'afterEach' | 'missing'>>;
+
+/**
+ * 命名的props
+ */
+export declare type InjectNamedProps<k extends string = string> = Record<k, InjectProps>;
+
+/**
+ * 路由参数注入
+ */
+export declare type InjectProps = boolean | Record<string, any> | InjectPropsHandler;
+
+/**
+ * 注入参数处理函数
+ *
+ * @param {ReadonlyRouteLocation} location 路由匹配的位置信息
+ * @return {Record<string, any>} 注入的参数
+ */
+export declare type InjectPropsHandler = (location: ReadonlyRouteLocation) => 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;
+    params: Record<string, string> | undefined;
+} | undefined;
+
+/**
+ * 基于内存实现的路由器
+ *
+ * 仅支持路由器操作前进、后退、跳转等操作
+ *
+ * > 注意：不要在浏览器端使用，因为浏览器端有原生的history对象，使用内存模式会和浏览器端的历史记录冲突，导致路由异常。
+ */
+export declare class MemoryRouter extends Router {
+    protected _history: ReadonlyRouteLocation[];
+    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;
+}
+
+/**
+ * 命名的路由视图小部件
+ *
+ * 用于多视图布局
+ */
+export declare type NamedRouteWidget<K extends string = string> = Record<K, RouteWidget>;
+
+/**
+ * 导航结果
+ *
+ * 包含导航的状态和相关信息
+ */
+export declare interface NavigateResult {
+    /**
+     * 导航状态
+     */
+    status: NavigateStatus;
+    /**
+     * 状态描述
+     */
+    message: string;
+    /**
+     * 最终的导航数据
+     */
+    to: ReadonlyRouteLocation;
+    /**
+     * 导航完成前的路由数据
+     */
+    from: ReadonlyRouteLocation;
+    /**
+     * 如果在守卫过程中被重定向，则为最初的路由目标
+     */
+    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
+}
+
+/**
+ * 只读路由位置对象
+ */
+export declare type ReadonlyRouteLocation = DeepReadonly<RouteLocation>;
+
+/**
+ * 只读规范化路由线路配置
+ */
+export declare type ReadonlyRouteNormalized = DeepReadonly<RouteNormalized>;
+
+/**
+ * 重定向处理器
+ */
+export declare type RedirectHandler = (this: Router, to: RouteLocation) => RouteTarget | undefined;
+
+/**
+ * 路由路线配置
+ *
+ * 该接口定义了应用程序中路由的配置对象的结构它描述了路由如何映射到组件，
+ * 以及路由的各种属性和行为
+ *
+ * @template T - 指定路由组件的类型，必须是 AllowedRouteWidget 的子类型
+ */
+export declare interface Route<T extends AllowedRouteWidget = AllowedRouteWidget> {
+    /**
+     * 路由的路径，用于URL匹配
+     *
+     * 支持动态路径匹配，如：/user/{id}，可选变量：/user/{id?}
+     */
+    path: RoutePath;
+    /**
+     * 动态路由匹配模式
+     *
+     * 默认会继承`RouterOptions.pattern`
+     */
+    pattern?: Record<string, RegExp>;
+    /**
+     * 路由的名称，用于识别和引用路由
+     */
+    name?: string;
+    /**
+     * 路由对应的视图组件
+     *
+     * 支持命名视图
+     *
+     * @example
+     * ```ts
+     * {
+     *   path: '/user/{id}',
+     *   name: 'user',
+     *   widget: {
+     *     default: User,
+     *     detail: UserDetail,
+     *   }
+     * }
+     * ```
+     */
+    widget?: T;
+    /**
+     * 路由重定向的目标地址或处理函数
+     */
+    redirect?: RouteTarget | RedirectHandler;
+    /**
+     * 子路由配置，用于嵌套路由
+     */
+    children?: Route[];
+    /**
+     * 路由的元数据，用于存储附加信息
+     */
+    meta?: RouteMetaData;
+    /**
+     * 路由的后缀配置，决定是否支持通配符或指定后缀
+     *
+     * 默认继承`RouterOptions.suffix`
+     */
+    suffix?: '*' | string | string[] | false;
+    /**
+     * 需要给路由`Widget`注入的参数
+     *
+     * 可选值：
+     * - `true`：表示仅注入匹配到的动态参数
+     * - `false`：表示不注入任何参数
+     * - `{key: value}`：表示注入指定参数，其中`key`为参数名，`any`为参数值
+     * - `(location: RouteLocation) => {key: value}`：自定义一个处理函数，返回一个对象用于注入参数
+     *
+     * > 注意：如果是命名视图，则需要以键值对形式传入：{视图名称:injectProps配置}
+     *
+     * @default true
+     */
+    injectProps?: (T extends NamedRouteWidget<infer k> ? InjectNamedProps<k> : InjectProps) | boolean;
+    /**
+     * 路由进入前的钩子函数，用于权限控制或数据预加载
+     *
+     * 默认继承`RouterOptions.beforeEach`
+     */
+    beforeEnter?: BeforeEnterCallback;
+    /**
+     * 路由进入后的钩子函数，用于处理进入路由后的逻辑
+     *
+     * 默认继承`RouterOptions.afterEach`
+     */
+    afterEnter?: AfterEnterCallback;
+}
+
+/**
+ * 路由索引
+ *
+ * 可以是路径或命名路由
+ */
+export declare type RouteIndex = RouterRouteIndexTyped;
+
+/**
+ * 路由匹配的详情数据
+ *
+ * 所有和url相关的数据都已`decodeURIComponent`解码
+ */
+export declare interface RouteLocation {
+    /**
+     * 路由索引，调用`push`|`replace`时传入的index
+     */
+    index: RouteIndex;
+    /**
+     * 完整的path，包含了query和hash
+     */
+    fullPath: string;
+    /**
+     * `index`所带的后缀
+     *
+     * 如果没有后缀则为空字符串
+     */
+    suffix: '' | `.${string}`;
+    /**
+     * 路由路径
+     *
+     * 如果匹配到路由则为路由的`path`属性
+     */
+    path: `/${string}`;
+    /**
+     * URL hash
+     */
+    hash: HashStr;
+    /**
+     * 路由参数
+     */
+    params: Record<string, any>;
+    /**
+     * URL 查询参数
+     */
+    query: Record<string, string>;
+    /**
+     * 路由元数据
+     */
+    meta: RouteMetaData;
+    /**
+     * 匹配的路由记录
+     *
+     * 从根路由开始，到当前路由结束
+     */
+    matched: RouteNormalized[];
+}
+
+/**
+ * 命名路由
+ *
+ * 用于标识路由的唯一名称
+ */
+export declare type RouteName = string;
+
+/**
+ * 规范化路由线路配置
+ */
+export declare interface RouteNormalized extends MakeRequired<Route, 'meta' | 'pattern' | 'suffix'> {
+    children: RouteNormalized[];
+    widget: undefined | Record<string, RouteWidget>;
+    injectProps: undefined | InjectNamedProps;
+}
+
+export declare interface RouteOptions {
+    /**
+     * 命名视图
+     *
+     * @default 'default'
+     */
+    name?: string;
+}
+
+/**
+ * 路由路径
+ *
+ * 必须以/开头的字符串
+ */
+export declare type RoutePath = `/${string}`;
+
+/**
+ * 路由器核心类
+ *
+ * 继承自 RouterRegistry，负责处理路由导航、历史记录管理、生命周期等核心功能。
+ * 采用单例模式，确保全局只有一个路由器实例。
+ */
+export declare abstract class Router extends RouterRegistry {
+    private _currentTaskId;
+    private _taskCounter;
+    /**
+     * 等待执行的 replace 操作数据
+     * 如果不为 null，表示当前有一个等待完成的 replace 导航
+     */
+    private _pendingReplace;
+    /**
+     * 等待执行的 push 操作数据
+     * 如果不为 null，表示当前有一个等待完成的 push 导航
+     */
+    private _pendingPush;
+    /**
+     * 滚动行为处理器
+     * 用于自定义路由切换时的滚动行为
+     */
+    private _scrollBehaviorHandler;
+    /**
+     * 当前路由数据
+     * 包含当前路由的完整信息，如路径、参数、查询字符串等
+     */
+    private readonly _currentRouteLocation;
+    /**
+     * 只读路由位置数据
+     *
+     * @private
+     */
+    private readonly _readonlyRouteLocation;
+    /**
+     * 路由器构造函数
+     * 初始化路由器并确保单例
+     *
+     * @param {RouterOptions} options - 路由器配置选项
+     * @throws {Error} 如果已存在路由器实例则抛出错误
+     */
+    protected constructor(options: RouterOptions);
+    /**
+     * 路由器单例实例
+     * 用于全局存储唯一的路由器实例
+     */
+    private static _instance;
+    /**
+     * 获取路由器单例实例
+     *
+     * @throws {Error} 如果路由器未初始化则抛出错误
+     * @return {RouterCore} 路由器实例
+     */
+    static get instance(): Router;
+    /**
+     * 判断路由器是否初始化完成
+     *
+     * 如果存在单例则代表初始化完成，没有单例则代表未初始化。
+     *
+     * @return {boolean} - 如果初始化完成，返回true，否则返回false
+     */
+    get initialized(): boolean;
+    /**
+     * 是否运行在浏览器环境
+     * 用于区分服务端渲染和客户端渲染
+     */
+    private _isBrowser;
+    /**
+     * 是否运行在浏览器端
+     */
+    get isBrowser(): boolean;
+    /**
+     * 滚动行为
+     * 定义路由切换时的滚动效果
+     */
+    private _scrollBehavior;
+    /**
+     * 滚动行为
+     *
+     * 如果options.scrollBehavior为函数，则scrollBehavior固定为auto'。
+     */
+    get scrollBehavior(): _ScrollBehavior;
+    /**
+     * 获取配置
+     *
+     * @return {Readonly<InitializedRouterOptions>} - 初始化配置
+     */
+    get options(): Readonly<InitializedRouterOptions>;
+    /**
+     * 路由器模式
+     */
+    get mode(): HistoryMode;
+    /**
+     * 当前路由数据
+     *
+     * 它是只读的，但它是响应式的，所以你可以在监听其变化。
+     *
+     * @return {ReadonlyRouteLocation} - 当前路由数据
+     */
+    get currentRouteLocation(): ReadonlyRouteLocation;
+    /**
+     * 是否处于等待状态
+     *
+     * @protected
+     */
+    protected get isPendingNavigation(): boolean;
+    /**
+     * 等待替换完成的数据
+     *
+     * @protected
+     */
+    protected get pendingReplaceData(): RouteLocation | null;
+    /**
+     * 等待跳转完成的数据
+     *
+     * @protected
+     */
+    protected get pendingPushData(): RouteLocation | null;
+    /* Excluded from this release type: routeViewElement */
+    /**
+     * 跳转指定的历史记录位置
+     *
+     * 如果未向该函数传参或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>;
+    /**
+     * 初始化路由器
+     *
+     * 只能初始化一次，多次初始化无效。
+     *
+     * 如果你使用的`createRouter(options)`助手函数创建的路由器实例则无需调用该方法。
+     *
+     * @return {this} - 返回当前路由器实例
+     */
+    initialize(): this;
+    /**
+     * 此方法用于浏览器端滚动到指定位置
+     *
+     * @param scrollTarget
+     */
+    scrollTo(scrollTarget: ScrollTarget | undefined): void;
+    /**
+     * 创建路由位置对象
+     * 根据导航目标创建标准化的路由位置信息
+     *
+     * @param {RouteTarget} target - 导航目标
+     * @return {RouteLocation} 路由位置对象
+     */
+    createRouteLocation(target: RouteTarget): RouteLocation;
+    /**
+     * 路由导航方法
+     *
+     * 处理所有的路由跳转请求，包括 push 和 replace
+     *
+     * @param {RouteTarget} target - 导航目标
+     * @return {Promise<NavigateResult>} 导航结果
+     */
+    navigate(target: RouteTarget): Promise<NavigateResult>;
+    /**
+     * 更新当前导航数据中的query参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {Record<string, string>} query - 新的query参数对象
+     * @public
+     */
+    updateQuery(query: Record<string, string>): void;
+    /**
+     * 更新当前导航数据中的hash参数
+     *
+     * 会同步更新`fullPath`
+     *
+     * @param {`#${string}` | ''} hash - 新的hash参数，如果为空则表示无hash
+     * @protected
+     */
+    updateHash(hash: `#${string}` | ''): void;
+    /**
+     * 创建路由元素
+     *
+     * @param route
+     * @param name
+     * @protected
+     */
+    protected createRouteViewElement(route: ReadonlyRouteNormalized, name: string): VNode<WidgetType> | undefined;
+    /* Excluded from this release type: _completeViewRender */
+    /**
+     * 完成导航过程
+     * 更新路由状态并触发相关的生命周期钩子
+     *
+     * @param {_ScrollToOptions} savedPosition - 保存的滚动位置
+     * @protected
+     */
+    protected completeNavigation(savedPosition?: _ScrollToOptions): void;
+    /**
+     * 初始化路由器
+     *
+     * 子类可重写此方法以完成路由器的初始化
+     *
+     * @private
+     */
+    protected abstract initializeRouter(): void;
+    /**
+     * 创建完整路径
+     *
+     * @protected
+     * @param path - 路径
+     * @param query - ?查询参数
+     * @param hash - #哈希值
+     * @param suffix - 路径后缀
+     * @return {string}
+     */
+    protected makeFullPath(path: string, query: `?${string}` | '' | Record<string, string>, hash: HashStr, suffix: string): `/${string}`;
+    /**
+     * 添加历史记录
+     *
+     * 子类必须实现该方法，且需要调用`this.completeNavigation(routeLocation)`方法标记完成导航！
+     *
+     * @param {RouteLocation} routeLocation - 新的路由位置对象
+     * @protected
+     */
+    protected abstract pushHistory(routeLocation: RouteLocation): void;
+    /**
+     * 替换历史记录
+     *
+     * 子类必须实现该方法，且需要调用`this.completeNavigation(routeLocation)`方法标记完成导航！
+     *
+     * @param {RouteLocation} routeLocation - 新的路由位置对象
+     * @protected
+     */
+    protected abstract replaceHistory(routeLocation: RouteLocation): void;
+    /**
+     * 触发路由前置守卫
+     *
+     * @param {RouteLocation} to - 路由目标对象
+     * @param {RouteLocation} from - 前路由对象
+     * @return {false | RouteTarget} - 返回false表示阻止导航，返回新的路由目标对象则表示导航到新的目标
+     */
+    protected onBeforeEach(to: RouteLocation, from: RouteLocation): BeforeEachCallbackResult;
+    /**
+     * 触发路由后置守卫
+     *
+     * @param {ReadonlyRouteLocation} to - 路由目标对象
+     * @param {ReadonlyRouteLocation} from - 前路由对象
+     */
+    protected onAfterEach(to: ReadonlyRouteLocation, from: ReadonlyRouteLocation): void;
+    /**
+     * 更新路由数据
+     * 使用补丁更新的方式更新路由状态
+     *
+     * @param {RouteLocation} newLocation - 新的路由数据
+     * @private
+     */
+    private updateRouteLocation;
+    /**
+     * 处理滚动行为
+     * 根据配置和保存的位置信息处理页面滚动
+     *
+     * @param {ReadonlyRouteLocation} to - 目标路由
+     * @param {ReadonlyRouteLocation} from - 当前路由
+     * @param {_ScrollToOptions} savedPosition - 保存的滚动位置
+     * @private
+     */
+    protected onScrollBehavior(to: ReadonlyRouteLocation, from: ReadonlyRouteLocation, savedPosition: _ScrollToOptions | undefined): Promise<void>;
+    /**
+     * @inheritDoc
+     */
+    removeRoute(index: RouteIndex): RouteNormalized | undefined;
+}
+
+/**
+ * # 路由跳转小部件
+ *
+ * 它只是简单的实现了一个a标签，点击后跳转到目标路由，
+ * 如果有更高级的定制需求，往往你可以项目中自行编写一个小部件来实现任何你想要的效果。
+ */
+export declare class RouterLink extends Widget<RouterLinkProps> {
+    /**
+     * 路由目标
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected target: Computed<RouteTarget | HttpUrl | undefined>;
+    /**
+     * 路由目标对应的`RouteLocation`对象
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected location: Computed<RouteLocation | undefined>;
+    /**
+     * 激活状态
+     *
+     * 计算属性
+     *
+     * @protected
+     */
+    protected active: Computed<boolean> | undefined;
+    protected htmlProps: Computed<HTMLProperties<HTMLAnchorElement>>;
+    private static isHttpOrHttpsUrl;
+    constructor(props: RouterLinkProps);
+    /**
+     * 当前是否处于激活状态
+     */
+    get isActive(): boolean | undefined;
+    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?: HTMLStyleProperties;
+    /**
+     * a 标签的class属性
+     */
+    class?: HTMLClassProperties;
+    /**
+     * a 标签的target属性
+     *
+     * 仅http或https外部连接支持此属性
+     */
+    target?: '_blank' | '_self' | '_parent' | '_top';
+    /**
+     * 是否禁用
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 激活状态计算
+     *
+     * 如果启用了激活状态计算，那么当路由匹配到当前路由时，a标签会添加`aria-current="page"`属性，
+     *
+     * 算法：
+     * - 如果路由索引以/开头，严格匹配`Router.instance.currentRouteLocation.path === to.index`，模糊匹配`Router.instance.currentRouteLocation.fullPath.startsWith(to.index)`
+     * - 如果路由索引不以/开头，则会匹配`Router.instance.currentRouteLocation.matched[i].name`，仅支持严格匹配
+     *
+     * 可选值：
+     * - none：不计算激活状态
+     * - obscure：模糊匹配，只要目标路由的路径以当前路由的路径开头，就认为当前路由处于激活状态
+     * - strict：严格匹配，只有目标路由的路径完全匹配当前路由的路径，才认为当前路由处于激活状态
+     *
+     * @default 'none'
+     */
+    active?: 'none' | 'obscure' | 'strict';
+    /**
+     * 导航回调函数
+     *
+     * @param {NavigateResult} result - 导航结果
+     */
+    callback?: (result: NavigateResult) => void;
+    /**
+     * 是否可拖拽
+     *
+     * @default false
+     */
+    draggable?: boolean;
+}
+
+/**
+ * 定义路由器配置选项接口
+ *
+ * 允许用户自定义路由的行为和属性
+ *
+ * @template T - 历史模式类型，支持：'hash' | 'path' | 'memory'
+ */
+export declare interface RouterOptions<T extends HistoryMode = HistoryMode> {
+    /**
+     * 指定路由的基础路径
+     *
+     * 通常用于在部署时指定子目录
+     */
+    base?: `/${string}`;
+    /**
+     * 指定路由的历史模式，可以是  'path' | 'hash' | 'memory'
+     *
+     * @default 'hash'
+     */
+    mode?: T;
+    /**
+     * 是否启用严格模式
+     *
+     * 在严格模式下，会区分大小写
+     *
+     * @default false
+     */
+    strict?: boolean;
+    /**
+     * 定义路由规则的数组
+     *
+     * 每个路由规则描述了路径和对应的组件或其他信息
+     *
+     * @example
+     * ```ts
+     * const routes: Route[] = [
+     *   { path: '/', widget: Home },
+     *   { path: '/about', widget: About },
+     *   { path: '/user/:id', widget: User },
+     * ]
+     * ```
+     */
+    routes: Route[];
+    /**
+     * 指定路由的后缀
+     *
+     * 可选值：
+     * - '*'：表示匹配任何后缀
+     * - 字符串：表示匹配指定后缀
+     * - 字符串数组：表示匹配多个后缀
+     * - false：表示完全匹配路径路由path
+     *
+     * @default '*'
+     */
+    suffix?: '*' | string | string[] | false;
+    /**
+     * 默认的后缀
+     *
+     * 如需使url地址看起来更符合静态网站特征，可以指定一个默认的后缀，例如'.html'。
+     *
+     * @default ''
+     */
+    defaultSuffix?: string;
+    /**
+     * 默认的动态路由匹配模式
+     *
+     * 允许用户定义复杂的路径匹配规则
+     *
+     * @default /[\w.]+/
+     */
+    pattern?: RegExp;
+    /**
+     * 定义滚动行为
+     *
+     * 可以是一个函数或行为标识符，决定了当路由变化时如何滚动页面
+     *
+     * @default 'smooth'
+     */
+    scrollBehavior?: _ScrollBehavior | ScrollBehaviorHandler;
+    /**
+     * 在每个路由进入之前调用的钩子函数
+     * 允许用户在路由激活之前执行逻辑检查或重定向
+     */
+    beforeEach?: BeforeEnterCallback;
+    /**
+     * 在每个路由进入之后调用的钩子函数
+     * 允许用户在路由激活之后执行逻辑，例如页面初始化
+     */
+    afterEach?: AfterEnterCallback;
+    /**
+     * 未匹配到路由时要渲染的组件（仅在根`RouterView`渲染）
+     *
+     * 如果你需要在未匹配到路由时重定向到指定的页面，你不应该使用`missing`选项，
+     * 而是应该在路由`beforeEach`钩子中判断`to.matched.length === 0`时返回重定向目标。
+     *
+     * > 注意：如果你设置了`missing`选项，新路由没有匹配时也会更新`URL`地址，然后渲染`missing`组件，
+     * 你可以通过`useRoute().matched.length`来判断是否真正匹配到了路由。
+     */
+    missing?: RouteWidget;
+}
+
+/**
+ * 路由注册基类
+ */
+declare abstract class RouterRegistry {
+    protected readonly _options: Readonly<InitializedRouterOptions>;
+    protected readonly _namedRoutes: Map<string, RouteNormalized>;
+    protected readonly _dynamicRoutes: Map<number, DynamicRouteRecord[]>;
+    protected readonly _pathRoutes: Map<string, RouteNormalized>;
+    protected readonly _parentRoute: WeakMap<RouteNormalized, RouteNormalized>;
+    protected constructor(options: RouterOptions);
+    /**
+     * 获取配置
+     */
+    get options(): Readonly<InitializedRouterOptions>;
+    /**
+     * 路由器模式
+     */
+    get mode(): HistoryMode;
+    /**
+     * 未匹配到路由时在根路由器视图中要渲染的组件
+     */
+    get missing(): RouteWidget | undefined;
+    /**
+     * 获取所有路由映射
+     */
+    get pathRoutes(): ReadonlyMap<string, RouteNormalized>;
+    /**
+     * 获取所有命名路由映射
+     */
+    get namedRoutes(): ReadonlyMap<string, RouteNormalized>;
+    /**
+     * 动态路由记录
+     */
+    get dynamicRoutes(): Map<number, DynamicRouteRecord[]>;
+    /**
+     * 获取已规范的路由表
+     */
+    get routes(): ReadonlyArray<RouteNormalized>;
+    /**
+     * 基本路径
+     */
+    get basePath(): `/${string}`;
+    /**
+     * 受支持的`path`后缀名
+     */
+    get suffix(): RouterOptions['suffix'];
+    /**
+     * 删除路由
+     *
+     * @param {string} index path或name
+     * @returns {RouteNormalized|undefined} - 删除成功返回被删除的路由对象，否则返回undefined
+     */
+    removeRoute(index: RouteIndex): RouteNormalized | undefined;
+    /**
+     * 添加路由
+     *
+     * @param {Object} route 路由对象
+     * @param {string} [parent] 父路由索引，可以是path|name
+     * @returns {void}
+     */
+    addRoute(route: Route, parent?: string): void;
+    /**
+     * 根据索引或路由目标查找路由
+     *
+     * @param {string|Object} target 路由索引或目标对象
+     * @returns {RouteNormalized|undefined} 匹配的路由对象，如果未找到则返回undefined
+     */
+    findRoute(target: RouteIndex | RouteTarget): RouteNormalized | undefined;
+    /**
+     * 根据path查找路由
+     *
+     * @param {string} path - 路由路径
+     * @returns {RouteNormalized|undefined} - 路由对象，如果未找到则返回undefined
+     */
+    findPathRoute(path: RoutePath): RouteNormalized | undefined;
+    /**
+     * 查找命名路由
+     *
+     * @param {string} name
+     * @returns {RouteNormalized|undefined} - 路由对象，如果未找到则返回undefined
+     */
+    findNamedRoute(name: RouteName): RouteNormalized | undefined;
+    /**
+     * 获取路由的父路由
+     */
+    findParentRoute(route: RouteNormalized): RouteNormalized | undefined;
+    /**
+     * 根据给定的路径匹配相应的路由
+     *
+     * 此方法首先格式化输入路径，然后根据路径匹配静态路由和动态路由
+     * 对于静态路由，直接比较路径是否相等；对于动态路由，使用正则表达式进行匹配
+     * 匹配成功后，验证路径的后缀是否符合要求，如果符合则返回匹配结果，包括路由和参数（如果有）
+     *
+     * @param path 要匹配的路径
+     * @returns {object|undefined} 如果找到匹配的路由，则返回匹配结果对象；否则返回undefined
+     */
+    matchRoute(path: RoutePath): MatchResult | undefined;
+    /**
+     * 初始化路由表
+     */
+    protected setupRoutes(routes: Route[]): void;
+    /**
+     * 从源路由表中删除路由
+     */
+    private removedFromRoutes;
+    /**
+     * 删除动态路由映射
+     */
+    private removeDynamicRoute;
+    /**
+     * 注册路由
+     *
+     * @param route 要注册的路由对象
+     * @param group 父路由对象
+     * @returns {RouteNormalized} 规范化的路由对象
+     */
+    private registerRoute;
+    /**
+     * 如果路径是严格匹配，则转换为小写
+     */
+    private strictPath;
+    /**
+     * 记录路由
+     */
+    private recordRoute;
+    /**
+     * 添加动态路由
+     */
+    private recordDynamicRoute;
+}
+
+/**
+ * # 路由器视图
+ *
+ * 用于渲染路由线路配置的`widget`，可以在子组件中嵌套`RouterView`，但应用内只能存在一个根视图。
+ *
+ * 如需实现页面缓存等功能，可以重写该类的{@link build}方法。
+ */
+export declare class RouterView extends Widget<RouteOptions> {
+    private readonly _$index;
+    private _$currentRoute?;
+    private _$currentElement;
+    constructor(props: RouteOptions);
+    /**
+     * 当前路由器视图所在层级索引
+     *
+     * `index`的值从0开始，它与`RouteLocation.matched`数组下标一一对应
+     */
+    get index(): number;
+    /**
+     * 是否为最后一个路由视图
+     */
+    get isLastView(): boolean;
+    /**
+     * 视图名称
+     *
+     * @default 'default'
+     */
+    get name(): string;
+    /**
+     * 获取当前匹配的路线配置
+     *
+     * 注意未匹配时会返回`undefined`，匹配成功时返回的是`ReadonlyRouteNormalized`
+     */
+    get matchedRoute(): ReadonlyRouteNormalized | undefined;
+    /**
+     * 当前路由器视图要显示的虚拟节点
+     *
+     * 注意未匹配时会返回`undefined`，匹配成功时返回的是`VNode<WidgetType>`
+     *
+     * @protected
+     */
+    protected get currentElement(): VNode<WidgetType> | undefined;
+    /**
+     * 当前路由器视图要显示的组件
+     *
+     * @protected
+     */
+    protected get currentWidget(): WidgetType | undefined;
+    /**
+     * 当前的路由位置对象
+     *
+     * @protected
+     */
+    protected get location(): DeepReadonly<RouteLocation_2>;
+    /**
+     * @inheritDoc
+     */
+    protected onMounted(): void;
+    /**
+     * @inheritDoc
+     */
+    protected onUpdated(): void;
+    /**
+     * ## 构建视图
+     *
+     * 可以重写该方法实现自定义的视图构建逻辑。
+     *
+     * 例如，使用`KeepAlive`小部件进行页面缓存：
+     * ```tsx
+     * protected build() {
+     *   // 使用空片段节点占位
+     *   if (!this.currentElement) return <></> // 不可省略，因为`KeepAlive`不能渲染非组件节点。
+     *
+     *   // 将当前要进行展示的小部件构造函数传递给`KeepAlive`插槽，会在切换页面时缓存当前页面状态。
+     *   return <KeepAlive>{this.currentElement}</KeepAlive>
+     * }
+     * ```
+     * @protected
+     */
+    protected build(): Element_2;
+    /**
+     * 视图渲染完成通知路由器
+     *
+     * @private
+     */
+    private completeViewRender;
+}
+
+/**
+ * 路由目标
+ *
+ * 用于描述导航的目标位置
+ */
+export declare interface RouteTarget {
+    /**
+     * 路由索引，/开头为路径，否则为名称
+     */
+    index: RouteIndex;
+    /**
+     * URL hash
+     */
+    hash?: HashStr;
+    /**
+     * URL 查询参数
+     */
+    query?: Record<string, string>;
+    /**
+     * 路由参数
+     */
+    params?: Record<string, any>;
+    /**
+     * 是否替换当前路由
+     */
+    isReplace?: boolean;
+}
+
+/**
+ * 路由视图小部件
+ *
+ * 可以是普通组件或懒加载组件
+ */
+export declare type RouteWidget = WidgetType | LazyLoad<WidgetType>;
+
+/**
+ * 滚动行为
+ */
+export declare type _ScrollBehavior = 'auto' | 'instant' | 'smooth';
+
+/**
+ * 滚动行为处理器
+ */
+export declare type ScrollBehaviorHandler = (to: ReadonlyRouteLocation, from: ReadonlyRouteLocation, savedPosition: _ScrollToOptions | undefined) => ScrollResult | Promise<ScrollResult>;
+
+/**
+ * 滚动到视图配置
+ */
+export declare interface _ScrollIntoViewOptions extends ScrollIntoViewOptions {
+    el: Element | `#${string}` | string;
+}
+
+/**
+ * 滚动结果
+ */
+export declare type ScrollResult = ScrollTarget | false;
+
+/**
+ * 滚动目标
+ */
+export declare type ScrollTarget = _ScrollToOptions | _ScrollIntoViewOptions;
+
+/**
+ * 滚动配置
+ */
+export declare interface _ScrollToOptions {
+    left?: number;
+    top?: number;
+    behavior?: _ScrollBehavior;
+}
+
+/**
+ * 获取当前`RouteLocation`对象
+ *
+ * 它是`Router.instance.currentRouteLocation`属性的助手函数，优化函数式编程体验。
+ *
+ * 简单示例：
+ * ```jsx
+ * import { useRoute,watch } 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 {ReadonlyRouteLocation} - 只读的`RouteLocation`对象
+ */
+export declare function useRoute(): ReadonlyRouteLocation;
+
+/**
+ * 获取路由器实例
+ *
+ * 与使用`Router.instance`静态属性获取是一致的效果。
+ *
+ * @return {RouterCore} - 路由器实例
+ * @throws {Error} - 如果路由器实例未初始化，则抛出异常
+ */
+export declare function useRouter<T extends Router>(): T;
+
 export { }