@meng-xi/uni-router/dist/index.d.ts

为 uni-app 提供类似 vue-router 风格的路由

/**
 * 路由后置钩子函数
 * @param to 已经进入的路由
 * @param from 上一个路由
 */
declare type AfterEachHook = (to: Route, from: Route | null) => void;

/**
 * 构建完整的 URL 字符串，根据传入的路径和查询参数生成最终的 URL
 * @param path 路径字符串
 * @param query 可选的查询参数对象，包含键值对，值的类型可以是字符串、数字或布尔值
 * @returns 构建好的完整 URL 字符串
 */
export declare function buildUrl(path: string, query?: Record<string, string | number | boolean>): string;

/** 当前页面实例 */
declare interface CurrentPage {
    /**
     * 页面的参数选项，通常包含从上个页面传递过来的查询参数。
     * 在小程序平台（如微信小程序、支付宝小程序等）中，该属性可直接获取页面参数。
     * 该属性为可选属性，可能不存在。
     */
    options?: Record<string, string>;
    /**
     * 页面的 Vue 实例，在 H5 和 App 平台可能会用到。
     * 该属性为可选属性，可能不存在。
     */
    $vm?: {
        /**
         * 在 H5 平台中，Vue 实例的路由信息对象。
         * 包含页面的查询参数等路由相关信息。
         * 该属性为可选属性，可能不存在。
         */
        $route?: {
            /**
             * H5 平台中，页面的查询参数对象。
             * 该属性为可选属性，可能不存在。
             */
            query?: Record<string, string>;
        };
        /**
         * 在 App 平台中，Vue 实例的小程序相关信息对象。
         * 包含页面的查询参数等信息。
         * 该属性为可选属性，可能不存在。
         */
        $mp?: {
            /**
             * App 平台中，页面的查询参数对象。
             * 该属性为可选属性，可能不存在。
             */
            query?: Record<string, string>;
        };
    };
    /**
     * 当前页面的路由路径。
     * 该属性为可选属性，可能不存在。
     */
    route?: string;
}

/**
 * 获取当前路由信息，根据传入的当前页面实例提取路由相关信息
 * @param currentPage 当前页面实例，可能为 null
 * @returns 当前路由对象，包含路径、完整路径和查询参数，若页面实例为 null 则返回 null
 */
export declare function getCurrentRoute(currentPage: CurrentPage | null): Route | null;

/** 路由链接组件的方法 */
declare interface MxRouterActionType {
    setProps: (mxRouterProps: MxRouterProps) => Promise<void>;
}

/** 路由链接组件 Props */
declare interface MxRouterProps {
    /** 路由地址 */
    to: RouteLocationRaw;
    /** 跳转方式 */
    method?: 'push' | 'replace' | 'tab' | 'launch' | 'back' | 'exit';
    /** 回退层数 */
    delta?: number;
    /** 窗口动画类型 */
    animationType?: UniApp.NavigateToOptions['animationType'] & UniApp.NavigateBackOptions['animationType'];
    /** 动画持续时间 */
    animationDuration?: number;
    /** 是否给 navigator 组件加一层 a 标签控制 ssr 渲染 */
    renderLink?: boolean;
    /** 指定点击时的样式类，当hover-class="none"时，没有点击态效果 */
    hoverClass?: string;
    /** 指定是否阻止本节点的祖先节点出现点击态 */
    hoverStopPropagation?: boolean;
    /** 按住后多久出现点击态，单位毫秒 */
    hoverStartTime?: number;
    /** 手指松开后点击态保留时间，单位毫秒 */
    hoverStayTime?: number;
    /** 在哪个小程序目标上发生跳转，默认当前小程序，值域self/miniProgram */
    target?: 'miniProgram' | 'self';
}

/**
 * 路由导航守卫函数
 * @param to 即将进入的路由
 * @param from 当前导航正要离开的路由
 * @param next 调用该方法来 resolve 这个钩子
 * @returns 可返回Promise或直接返回boolean/void
 */
declare type NavigationGuard = (to: Route, from: Route | null, next: NavigationGuardNextCallback) => Promise<boolean | void> | boolean | void;

/**
 * 路由导航守卫函数的回调参数
 * @param valid 导航是否有效，为false时取消导航，为字符串时重定向到指定路径，为RouteLocationRaw对象时进行路由跳转
 */
declare type NavigationGuardNextCallback = (valid?: boolean | string | RouteLocationRaw | void) => void;

/**
 * 解析路由位置，将传入的路由位置信息转换为统一的路径和查询参数格式
 * @param location 路由位置信息，可以是字符串类型的路径，也可以是包含路径和查询参数的对象
 * @returns 解析后的路径和可选的查询参数对象，查询参数对象的键值对均为字符串类型
 */
export declare function parseLocation(location: RouteLocationRaw): {
    path: string;
    query?: Record<string, string>;
};

/** 当前路由信息 */
declare interface Route {
    /** 路由路径 */
    path: string;
    /** 完整路径（包含查询参数） */
    fullPath: string;
    /** 解析后的查询参数对象 */
    query: Record<string, string>;
}

/** 路由配置项接口 */
declare interface RouteConfig {
    /** 路由路径 */
    path: string;
    /** 路由元信息，可存储任意自定义数据 */
    meta?: Record<string, unknown>;
    /** 子路由配置数组 */
    children?: RouteConfig[];
}

/** 路由位置描述对象 */
declare interface RouteLocation {
    /** 目标路径 */
    path: string;
    /** 查询参数对象 */
    query?: Record<string, string | number | boolean>;
}

/** 路由位置描述，可以是字符串路径或RouteLocation对象 */
declare type RouteLocationRaw = string | RouteLocation;

/**
 * uni-app 路由实现类，实现了 RouterInterface 接口，提供了一系列路由操作方法和守卫机制
 * 支持单例模式调用和实例调用两种方式
 */
export declare class Router implements RouterInterface {
    /**
     * 单例实例，用于单例模式调用
     * @private
     * @static
     * @type {Router | undefined}
     */
    private static instance;
    /**
     * 路由配置列表，存储所有的路由配置信息
     * @private
     * @type {RouteConfig[]}
     */
    private routes;
    /**
     * 全局前置守卫列表，在每次导航前依次执行
     * @private
     * @type {NavigationGuard[]}
     */
    private beforeEachHooks;
    /**
     * 全局后置钩子列表，在每次导航成功后依次执行
     * @private
     * @type {AfterEachHook[]}
     */
    private afterEachHooks;
    /**
     * 存储用户自定义的 getCurrentRoute 函数
     * @private
     * @type {(() => ReturnType<typeof getCurrentRouteUtil>) | undefined}
     */
    private customGetCurrentRoute;
    /**
     * 构造函数，初始化 Router 实例
     * 私有构造函数，防止外部直接实例化，保证单例模式的实现
     * @param {RouterOptions} [options={}] - 路由配置选项，包含路由配置列表等信息，默认为空对象
     */
    constructor(options?: RouterOptions);
    /**
     * 获取单例实例
     * 首次获取实例时需要传入路由配置选项，后续获取使用之前的配置
     * @static
     * @param {RouterOptions} [options] - 路由配置选项
     * @returns {Router} Router 实例
     */
    static getInstance(options?: RouterOptions): Router;
    /**
     * 以推入新页面的方式进行路由导航 - 静态方法
     * 通过单例实例调用实例方法实现路由导航
     * @static
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @param {RouterOpenAnimation} [animation] - 窗口显示动画配置
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    static push(location: RouteLocationRaw, animation?: RouterOpenAnimation): Promise<void>;
    /**
     * 以推入新页面的方式进行路由导航 - 实例方法
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @param {RouterOpenAnimation} [animation] - 窗口显示动画配置
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    push(location: RouteLocationRaw, animation?: RouterOpenAnimation): Promise<void>;
    /**
     * 以替换当前页面的方式进行路由导航 - 静态方法
     * 通过单例实例调用实例方法实现路由导航
     * @static
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    static replace(location: RouteLocationRaw): Promise<void>;
    /**
     * 以替换当前页面的方式进行路由导航 - 实例方法
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    replace(location: RouteLocationRaw): Promise<void>;
    /**
     * 以重新启动应用的方式进行路由导航 - 静态方法
     * 通过单例实例调用实例方法实现路由导航
     * @static
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    static launch(location: RouteLocationRaw): Promise<void>;
    /**
     * 以重新启动应用的方式进行路由导航 - 实例方法
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    launch(location: RouteLocationRaw): Promise<void>;
    /**
     * 切换到指定的 tab 页面 - 静态方法
     * 通过单例实例调用实例方法实现路由导航
     * @static
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    static tab(location: RouteLocationRaw): Promise<void>;
    /**
     * 切换到指定的 tab 页面 - 实例方法
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    tab(location: RouteLocationRaw): Promise<void>;
    /**
     * 返回到指定层数的上一个页面 - 静态方法
     * 通过单例实例调用实例方法实现页面返回
     * @static
     * @param {number} [delta=-1] - 要返回的页面层数，默认值为 -1，表示返回上一个页面
     * @param {RouterCloseAnimation} [animation] - 窗口关闭动画配置
     */
    static go(delta?: number, animation?: RouterCloseAnimation): void;
    /**
     * 返回到指定层数的上一个页面 - 实例方法
     * 调用 uni-app 的 navigateBack 方法实现页面返回
     * @param {number} [delta=-1] - 要返回的页面层数，默认值为 -1，表示返回上一个页面
     * @param {RouterCloseAnimation} [animation] - 窗口关闭动画配置
     */
    go(delta?: number, animation?: RouterCloseAnimation): void;
    /**
     * 返回到上一个页面，等同于调用 go(-1) - 静态方法
     * 通过单例实例调用实例方法实现页面返回
     * @static
     * @param {RouterCloseAnimation} [animation] - 窗口关闭动画配置
     */
    static back(animation?: RouterCloseAnimation): void;
    /**
     * 返回到上一个页面，等同于调用 go(-1) - 实例方法
     * 调用 go 方法实现页面返回
     * @param {RouterCloseAnimation} [animation] - 窗口关闭动画配置
     */
    back(animation?: RouterCloseAnimation): void;
    /**
     * 添加全局前置守卫到守卫列表中 - 静态方法
     * 通过单例实例调用实例方法添加全局前置守卫
     * 这些守卫会在每次导航前依次执行
     * @static
     * @param {NavigationGuard} guard - 全局前置守卫函数
     */
    static beforeEach(guard: NavigationGuard): void;
    /**
     * 添加全局前置守卫到守卫列表中 - 实例方法
     * 将全局前置守卫函数添加到前置守卫列表中
     * 这些守卫会在每次导航前依次执行
     * @param {NavigationGuard} guard - 全局前置守卫函数
     */
    beforeEach(guard: NavigationGuard): void;
    /**
     * 添加全局后置钩子到钩子列表中 - 静态方法
     * 通过单例实例调用实例方法添加全局后置钩子
     * 这些钩子会在每次导航成功后依次执行
     * @static
     * @param {AfterEachHook} hook - 全局后置钩子函数
     */
    static afterEach(hook: AfterEachHook): void;
    /**
     * 添加全局后置钩子到钩子列表中 - 实例方法
     * 将全局后置钩子函数添加到后置钩子列表中
     * 这些钩子会在每次导航成功后依次执行
     * @param {AfterEachHook} hook - 全局后置钩子函数
     */
    afterEach(hook: AfterEachHook): void;
    /**
     * 设置自定义的 getCurrentRoute 函数
     * @static
     * @param {() => ReturnType<typeof getCurrentRouteUtil>} customFunction - 自定义的 getCurrentRoute 函数
     */
    static setCustomGetCurrentRoute(customFunction: () => ReturnType<typeof getCurrentRoute>): void;
    /**
     * 设置自定义的 getCurrentRoute 函数
     * @param {() => ReturnType<typeof getCurrentRouteUtil>} customFunction - 自定义的 getCurrentRoute 函数
     */
    setCustomGetCurrentRoute(customFunction: () => ReturnType<typeof getCurrentRoute>): void;
    /**
     * 获取当前页面的路由信息 - 静态方法
     * 通过单例实例调用实例方法获取当前页面的路由信息
     * @static
     * @returns {ReturnType<typeof getCurrentRouteUtil> | null} 当前页面的路由信息对象，如果获取失败则返回 null
     */
    static getCurrentRoute(): ReturnType<typeof getCurrentRoute> | null;
    /**
     * 获取当前页面的路由信息 - 实例方法
     * 优先使用用户自定义的 getCurrentRoute 函数，若未定义则使用默认实现
     * @returns {ReturnType<typeof getCurrentRouteUtil> | null} 当前页面的路由信息对象，如果获取失败则返回 null
     */
    getCurrentRoute(): ReturnType<typeof getCurrentRoute> | null;
    /**
     * 执行路由导航操作，包含前置守卫和后置钩子的处理
     * @private
     * @param {RouteLocationRaw} location - 目标路由位置信息，可以是字符串路径或包含路径和查询参数的对象
     * @param {RouterMethod} method - 导航方法，如 'navigateTo'、'redirectTo' 等
     * @param {RouterOpenAnimation} [animation] - 窗口显示动画配置
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    private navigate;
    /**
     * 执行单个全局前置守卫函数
     * @private
     * @param {NavigationGuard} guard - 全局前置守卫函数
     * @param {any} to - 目标路由信息对象
     * @param {any} from - 当前路由信息对象
     * @returns {Promise<void>} 一个 Promise，守卫验证通过时 resolve，验证失败时 reject
     */
    private runGuard;
    /**
     * 调用 uni-app 的路由方法进行导航
     * @private
     * @param {RouterMethod} method - 导航方法，如 'navigateTo'、'redirectTo' 等
     * @param {string} url - 导航的目标 URL
     * @param {RouterOpenAnimation} [animation] - 窗口显示动画配置
     * @returns {Promise<void>} 一个 Promise，导航成功时 resolve，失败时 reject
     */
    private callMxMethod;
}

/** 窗口关闭动画配置 */
declare interface RouterCloseAnimation {
    /** 动画类型 */
    type?: UniApp.NavigateBackOptions['animationType'];
    /** 动画持续时间 */
    duration?: number;
}

/** uni-app路由类接口 */
declare interface RouterInterface {
    /** 跳转到指定页面（保留当前页面） */
    push(location: RouteLocationRaw): Promise<void>;
    /** 跳转到指定页面（关闭当前页面） */
    replace(location: RouteLocationRaw): Promise<void>;
    /** 跳转到指定页面（关闭所有页面） */
    launch(location: RouteLocationRaw): Promise<void>;
    /** 跳转到tabBar页面 */
    tab(location: RouteLocationRaw): Promise<void>;
    /** 返回指定页面数 */
    go(delta?: number): void;
    /** 返回上一页 */
    back(): void;
    /** 添加全局前置守卫 */
    beforeEach(guard: NavigationGuard): void;
    /** 添加全局后置钩子 */
    afterEach(hook: AfterEachHook): void;
    /** 获取当前路由信息 */
    getCurrentRoute(): Route | null;
}

/** 窗口显示动画配置 */
declare interface RouterOpenAnimation {
    /** 动画类型 */
    type?: UniApp.NavigateToOptions['animationType'];
    /** 动画持续时间 */
    duration?: number;
}

/** 路由构造器选项 */
declare interface RouterOptions {
    /** 路由配置数组 */
    routes?: RouteConfig[];
    /**
     * 自定义获取当前路由的函数
     * @returns 当前路由信息对象，如果获取失败则返回 null
     */
    customGetCurrentRoute?: () => Route | null;
}

/**
 * 使用 Router 组件的组合式函数，用于管理 Router 实例并提供操作方法
 *
 * @param routerProps - Router 组件的属性，用于配置路由跳转相关信息
 *
 * @returns 包含注册函数和操作方法的数组，第一个元素为注册函数，第二个元素为操作方法对象
 */
export declare function useMxRouter(routerProps: MxRouterProps): ({
    /**
     * 异步设置 Router 组件的属性
     *
     * @param routerProps - 要设置的 Router 组件属性
     */
    setProps: (routerProps: MxRouterProps) => Promise<void>;
} | ((instance: MxRouterActionType) => void))[];

export { }