my-uniapp-tools/dist/navigation/index.d.ts

一个简洁稳定的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息等常用功能

/**
 * 导航工具函数
 *
 * 设计原则：
 * - 消除重复：通用包装器统一处理
 * - 明确语义：超时是等回调，不是等API
 * - 避免竞态：保存初始状态，不重复查询
 */
export interface NavigateOptions {
    url: string;
    params?: Record<string, any>;
    animationType?: 'auto' | 'none' | 'slide-in-right' | 'slide-in-left' | 'slide-in-top' | 'slide-in-bottom' | 'fade-in' | 'zoom-out' | 'zoom-fade-out' | 'pop-in';
    animationDuration?: number;
    events?: Record<string, Function>;
}
export interface BackOptions {
    delta?: number;
    timeout?: number;
}
export interface BackOrHomeOptions extends BackOptions {
    homePage?: string;
    homeParams?: Record<string, any>;
}
export interface PageInfo {
    route: string;
    options: any;
}
export interface NavigationConfig {
    defaultHomePage: string;
}
/**
 * 配置导航模块
 * @example
 * configureNavigation({ defaultHomePage: '/pages/home/home' });
 */
export declare function configureNavigation(config: Partial<NavigationConfig>): void;
export declare function useBuildUrl(url: string, params?: Record<string, any>): string;
/**
 * @deprecated 请使用 useBuildUrl 替代（符合 Vue composable 命名约定）
 */
export declare const buildUrl: typeof useBuildUrl;
/**
 * 返回上一页
 *
 * @param params 返回上一页时传入的参数（会调用目标页面的 init 方法）
 * @param options 导航选项
 * @param options.delta 返回的页面数，默认1
 * @param options.timeout 回调执行超时时间（毫秒），默认5000（注意：这不是导航API本身的超时）
 * @returns Promise<boolean> 返回 true 表示导航成功，false 表示失败（页面栈不足或回调超时）
 *
 * @description
 * 注意：timeout 参数并非导航API本身的超时（navigateBack是同步的），而是等待"页面切换完成 + init回调执行"的超时。
 *
 * @example
 * // 基础返回
 * await useBack();
 *
 * // 返回并传递刷新参数
 * await useBack({ refresh: true, updatedData: {...} });
 *
 * // 返回两层页面
 * await useBack('', { delta: 2 });
 *
 * // 设置回调执行超时时间
 * await useBack('', { timeout: 3000 });
 */
export declare function useBack(params?: any, options?: BackOptions): Promise<boolean>;
/**
 * 返回上一页，若页面栈不足则重定向到首页
 *
 * @param params 返回上一页时传入的参数
 * @param options 导航选项
 * @param options.delta 返回的页面数，默认1
 * @param options.timeout 超时时间（毫秒），默认5000
 * @param options.homePage 首页路径，默认使用全局配置（可通过 configureNavigation 设置）
 * @param options.homeParams 首页参数
 * @returns Promise<boolean> 返回 true 表示操作成功，false 表示失败
 *
 * @description
 * 智能返回函数：
 * - 如果页面栈深度足够，执行正常返回
 * - 如果页面栈深度不足（如只有1个页面），则重定向到首页
 * - 首页路径优先级：传入的 homePage > 全局配置 > 默认值 '/pages/index/index'
 *
 * @example
 * // 基础使用（页面栈不足时跳转到全局配置的首页）
 * await useBackOrHome();
 *
 * // 自定义首页路径（临时覆盖全局配置）
 * await useBackOrHome('', {
 *   homePage: '/pages/home/home',
 *   homeParams: { from: 'auto' }
 * });
 *
 * // 返回两层，不足则跳首页
 * await useBackOrHome('', { delta: 2 });
 */
export declare function useBackOrHome(params?: any, options?: BackOrHomeOptions): Promise<boolean>;
/**
 * 防抖版本的返回上一页
 *
 * @description
 * 300毫秒内的多次调用会被合并为一次，防止用户快速点击导致的重复返回
 *
 * @example
 * // 在按钮点击事件中使用
 * <button @click="useBackDebounced()">返回</button>
 */
export declare const useBackDebounced: typeof useBack & {
    cancel: () => void;
};
/**
 * 获取当前页面信息
 *
 * @returns 当前页面信息对象，包含路由路径和参数；如果获取失败返回 null
 * @returns {string} route 当前页面的路由路径
 * @returns {any} options 当前页面的参数对象
 *
 * @example
 * const pageInfo = useCurrentPageInfo();
 * if (pageInfo) {
 *   console.log('当前页面路由:', pageInfo.route);
 *   console.log('当前页面参数:', pageInfo.options);
 * }
 *
 * // 示例返回值
 * // {
 * //   route: 'pages/detail/detail',
 * //   options: { id: '123', type: 'product' }
 * // }
 */
export declare function useCurrentPageInfo(): PageInfo | null;
/**
 * @deprecated 请使用 useCurrentPageInfo 替代（符合 Vue composable 命名约定）
 */
export declare const getCurrentPageInfo: typeof useCurrentPageInfo;
/**
 * 获取页面栈信息
 *
 * @returns 页面栈数组，包含所有页面的路由和参数；如果获取失败返回空数组
 *
 * @description
 * 返回完整的页面栈信息，从第一个页面到当前页面。
 * 数组索引0是最底层的页面，最后一个元素是当前页面。
 *
 * @example
 * const stack = usePageStack();
 * console.log('页面栈深度:', stack.length);
 * console.log('第一个页面:', stack[0]);
 * console.log('当前页面:', stack[stack.length - 1]);
 *
 * // 示例返回值
 * // [
 * //   { route: 'pages/index/index', options: {} },
 * //   { route: 'pages/list/list', options: { category: 'tech' } },
 * //   { route: 'pages/detail/detail', options: { id: '123' } }
 * // ]
 */
export declare function usePageStack(): PageInfo[];
/**
 * @deprecated 请使用 usePageStack 替代（符合 Vue composable 命名约定）
 */
export declare const getPageStack: typeof usePageStack;