vitarx-router 4.0.0-beta.9 → 4.0.1

package/README.md

@@ -112,6 +112,25 @@ import { createMemoryRouter } from 'vitarx-router'
 createMemoryRouter({ routes })
 ```
 
+### 手动初始化
+
+默认情况下，`createRouter` / `createWebRouter` 会在创建实例后自动初始化路由器（执行初始导航并注册浏览器事件监听）。如果需要延迟初始化，可以使用 `createWebRouter` 并将第二个参数 `autoInit` 设为 `false`，然后手动调用 `init()` 方法。
+
+```typescript
+const router = createWebRouter({ routes }, false)
+
+// 在合适的时机手动初始化
+router.init()
+```
+
+**适用场景：**
+
+- 需要在初始化前注册导航守卫
+- 需要在初始化前完成异步配置加载
+- 需要精确控制初始化时机
+
+> **注意：** `autoInit` 仅对 Web 路由器有效。
+
 ## 路由配置
 
 ### 基本路由
@@ -272,6 +291,71 @@ if (hasSuccess(result)) {
 | `cancelled`  | 4  | 导航被新导航取消 |
 | `duplicated` | 8  | 重复导航     |
 | `notfound`   | 16 | 路由未匹配    |
+| `external`   | 32 | 外部跳转     |
+
+## 路由未匹配处理
+
+当路由匹配失败（404）时，可以通过 `onNotFound` 钩子进行自定义处理。
+
+### onNotFound 钩子
+
+```typescript
+import { createRouter } from 'vitarx-router'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    // target.index 为用户尝试访问的目标
+    console.log('路由未匹配:', target.index)
+  }
+})
+```
+
+**返回值说明：**
+
+| 返回值                        | 说明                   |
+|----------------------------|----------------------|
+| `NavTarget` / `RouteIndex` | 重定向到新目标              |
+| `RouteLocation`            | 作为未匹配路由的位置对象（渲染指定组件） |
+| `void`                     | 不处理，返回 `notfound` 状态 |
+
+### 重定向到 404 页面
+
+```typescript
+import { createRouter } from 'vitarx-router'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    return { index: '/404' }
+  }
+})
+```
+
+### 渲染 404 组件（使用 createMissingRoute）
+
+```typescript
+import { createRouter, createMissingRoute } from 'vitarx-router'
+import NotFoundPage from './pages/NotFound.jsx'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    return createMissingRoute(NotFoundPage, target, {
+      title: '页面未找到'
+    })
+  }
+})
+```
+
+### 名称导航不匹配
+
+名称导航（name-based）匹配失败时，路由器会直接抛出错误，因为名称导航是编程式调用，name 不存在属于代码 bug：
+
+```typescript
+// 如果 'userDetail' 路由不存在，将抛出错误
+router.push({ index: 'userDetail', params: { id: '123' } })
+```
 
 ## 导航守卫
 
@@ -423,20 +507,7 @@ export const router = createRouter({ routes })
 
 ### 文件路由配置选项
 
-| 选项               | 类型                                         | 默认值           | 说明       |
-|------------------|--------------------------------------------|---------------|----------|
-| `pages`          | `PageSource \| readonly PageSource[]`      | `'src/pages'` | 页面来源配置   |
-| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`          | `'kebab'`     | 路径格式化策略  |
-| `importMode`     | `'lazy' \| 'sync' \| ImportModeFunction`   | `'lazy'`      | 组件导入模式   |
-| `injectImports`  | `readonly string[]`                        | -             | 自定义导入语句  |
-| `dts`            | `boolean \| string`                        | `false`       | 类型声明文件配置 |
-| `layoutFileName` | `string`                                   | `'_layout'`   | 布局文件名    |
-| `configFileName` | `string`                                   | `'_config'`   | 分组配置文件名  |
-| `transform`      | `CodeTransformHook`                        | -             | 代码转换钩子   |
-| `extendRoute`    | `ExtendRouteHook`                          | -             | 路由扩展钩子   |
-| `pathParser`     | `PathParser`                               | -             | 自定义路径解析器 |
-
-详细配置请参考 [File Router 文档](src/file-router/README.md)。
+请参考 [File Router 文档](src/file-router/README.md)。
 
 ## TypeScript 支持
 
@@ -466,35 +537,49 @@ declare module 'vitarx-router' {
 
 ### 助手函数
 
-| 函数                                     | 说明              |
-|----------------------------------------|-----------------|
-| `createRouter(options)`                | 创建路由器实例         |
-| `createWebRouter(options)`             | 创建 Web 模式路由器    |
-| `createMemoryRouter(options)`          | 创建 Memory 模式路由器 |
-| `createRouteManager(routes, options?)` | 创建路由管理器         |
-| `defineRoutes(...routes)`              | 定义路由表           |
-| `useRouter()`                          | 获取路由器实例         |
-| `useRoute(global?)`                    | 获取当前路由信息        |
-| `useLink(options)`                     | 创建链接助手          |
-| `onBeforeRouteLeave(guard)`            | 注册离开守卫          |
-| `onBeforeRouteUpdate(callback)`        | 注册更新钩子          |
+| 函数                                             | 说明                        |
+|------------------------------------------------|---------------------------|
+| `createRouter(options)`                        | 创建路由器实例                   |
+| `createWebRouter(options)`                     | 创建 Web 模式路由器              |
+| `createMemoryRouter(options)`                  | 创建 Memory 模式路由器           |
+| `createRouteManager(routes, options?)`         | 创建路由管理器                   |
+| `defineRoutes(...routes)`                      | 定义路由表                     |
+| `createMissingRoute(component, target, meta?)` | 创建未匹配路由的 RouteLocation    |
+| `cloneRouteLocation(location)`                 | 克隆 RouteLocation          |
+| `useRouter()`                                  | 获取路由器实例                   |
+| `useRoute(global?)`                            | 获取当前路由信息                  |
+| `useLink(options)`                             | 创建链接助手                    |
+| `onBeforeRouteLeave(guard)`                    | 注册离开守卫                    |
+| `onBeforeRouteUpdate(callback)`                | 注册更新钩子                    |
+| `removeTrailingSlash(path)`                    | 删除路径末尾的斜杠                 |
+| `normalizePath(path, removeTrailingSlash?)`    | 规范化路径                     |
+| `parseQuery(queryString)`                      | 解析查询字符串                   |
+| `stringifyQuery(query)`                        | 序列化查询对象                   |
+| `isNavTarget(value)`                           | 检查一个值是否为导航目标对象            |
+| `isNavIndex(value)`                            | 检查一个值是否为有效的导航索引           |
+| `isRouteLocation(value)`                       | 检查一个值是否为 RouteLocation 对象 |
+| `isRoutePath(index)`                           | 检查一个值是否为有效的路由路径           |
+| `isExternalLink(href)`                         | 检查一个值是否为外部链接              |
+| `isPathExactMatch(currentPath, targetPath)`    | 判断路径是否完全匹配                |
+| `isPathPrefixMatch(currentPath, targetPath)`   | 判断路径是否前缀匹配                |
 
 ### Router 实例方法
 
-| 方法                         | 说明        |
-|----------------------------|-----------|
-| `push(target)`             | 跳转到新路由    |
-| `replace(target)`          | 替换当前路由    |
-| `go(delta)`                | 前进/后退指定步数 |
-| `back()`                   | 后退一步      |
-| `forward()`                | 前进一步      |
-| `addRoute(route, parent?)` | 添加路由      |
-| `removeRoute(index)`       | 移除路由      |
-| `hasRoute(index)`          | 检查路由是否存在  |
-| `matchRoute(target)`       | 匹配路由      |
-| `beforeEach(guard)`        | 添加前置守卫    |
-| `afterEach(callback)`      | 添加后置回调    |
-| `destroy()`                | 销毁路由器     |
+| 方法                         | 说明                    |
+|----------------------------|-----------------------|
+| `init()`                   | 手动初始化路由器（仅 WebRouter） |
+| `push(target)`             | 跳转到新路由                |
+| `replace(target)`          | 替换当前路由                |
+| `go(delta)`                | 前进/后退指定步数             |
+| `back()`                   | 后退一步                  |
+| `forward()`                | 前进一步                  |
+| `addRoute(route, parent?)` | 添加路由                  |
+| `removeRoute(index)`       | 移除路由                  |
+| `hasRoute(index)`          | 检查路由是否存在              |
+| `matchRoute(target)`       | 匹配路由                  |
+| `beforeEach(guard)`        | 添加前置守卫                |
+| `afterEach(callback)`      | 添加后置回调                |
+| `destroy()`                | 销毁路由器                 |
 
 ### Router 实例属性
 

package/dist/auto-routes/index.d.ts

@@ -1,19 +1,38 @@
+import type { Route, Router } from '../core/index.js';
 /**
- * @fileoverview 自动路由模块
+ * 自动生成的路线配置
+ */
+export declare const routes: Route[];
+/**
+ * 处理路由热更新函数
+ *
+ * 当路由配置发生变化时，动态更新路由表。
+ * 支持传入回调函数，在路由更新后执行自定义逻辑（如添加重定向）。
  *
- * 该模块重新导出虚拟模块生成的路由配置。
- * 开发者应该从 `vitarx-router/auto-routes` 导入 routes。
+ * @param router - Vitarx Router 实例
+ * @param onRoutesUpdated - 路由更新后的回调函数，接收新路由数组作为参数
  *
  * @example
- * ```typescript
+ * ```TypeScript
+ * import { createRouter } from 'vitarx'
  * import { routes, handleHotUpdate } from 'vitarx-router/auto-routes'
  *
  * const router = createRouter({ routes })
  *
+ * function addRedirects() {
+ *   router.addRoute({
+ *     path: '/new-about',
+ *     redirect: '/about',
+ *   })
+ * }
+ *
  * if (import.meta.hot) {
- *   handleHotUpdate(router)
+ *   handleHotUpdate(router, (newRoutes) => {
+ *     addRedirects()
+ *   })
+ * } else {
+ *   addRedirects()
  * }
  * ```
  */
-export { default as routes } from 'virtual:vitarx-router:routes';
-export { handleHotUpdate } from './handleHotUpdate.js';
+export declare function handleHotUpdate(router: Router, onRoutesUpdated?: (newRoutes: Route[]) => void): void;

package/dist/auto-routes/index.js

@@ -15,5 +15,81 @@
  * }
  * ```
  */
-export { default as routes } from 'virtual:vitarx-router:routes';
-export { handleHotUpdate } from './handleHotUpdate.js';
+import virtualRoutes from 'virtual:vitarx-router:routes';
+/**
+ * 自动生成的路线配置
+ */
+export const routes = virtualRoutes;
+/**
+ * 处理路由热更新函数
+ *
+ * 当路由配置发生变化时，动态更新路由表。
+ * 支持传入回调函数，在路由更新后执行自定义逻辑（如添加重定向）。
+ *
+ * @param router - Vitarx Router 实例
+ * @param onRoutesUpdated - 路由更新后的回调函数，接收新路由数组作为参数
+ *
+ * @example
+ * ```TypeScript
+ * import { createRouter } from 'vitarx'
+ * import { routes, handleHotUpdate } from 'vitarx-router/auto-routes'
+ *
+ * const router = createRouter({ routes })
+ *
+ * function addRedirects() {
+ *   router.addRoute({
+ *     path: '/new-about',
+ *     redirect: '/about',
+ *   })
+ * }
+ *
+ * if (import.meta.hot) {
+ *   handleHotUpdate(router, (newRoutes) => {
+ *     addRedirects()
+ *   })
+ * } else {
+ *   addRedirects()
+ * }
+ * ```
+ */
+export function handleHotUpdate(router, onRoutesUpdated) {
+    if (import.meta.hot) {
+        import.meta.hot.accept('virtual:vitarx-router:routes', newModule => {
+            if (!newModule)
+                return;
+            const routes = newModule.default;
+            if (routes && typeof routes === 'object') {
+                router.manager.clearRoutes();
+                for (const route of routes) {
+                    router.manager.addRoute(route);
+                }
+                // 路由更新完成后调用回调函数
+                if (onRoutesUpdated) {
+                    onRoutesUpdated(routes);
+                }
+                if (typeof window === 'undefined')
+                    return;
+                const matchedRoute = router.matchRoute({
+                    index: router.route.matched.at(-1)?.name || router.route.path,
+                    params: { ...router.route.params },
+                    query: { ...router.route.query },
+                    hash: router.route.hash
+                });
+                // 如果没有匹配到路由，则重新加载页面
+                if (!matchedRoute) {
+                    return window.location.reload();
+                }
+                // 热更新meta信息
+                const meta = router['_routeLocation'].meta;
+                for (const key in meta) {
+                    if (!(key in matchedRoute.meta)) {
+                        delete meta[key];
+                    }
+                }
+                for (const key in matchedRoute.meta) {
+                    meta[key] = matchedRoute.meta[key];
+                }
+            }
+        });
+    }
+}

package/dist/components/RouterLink.d.ts

@@ -1,11 +1,11 @@
-import { ElementView, type ValidChildren, type WithProps } from 'vitarx';
+import { type CodeLocation, ElementView, type RenderChildren, type WithProps } from 'vitarx';
 import { type NavigateResult } from '../core/index.js';
 import { type UseLinkOptions } from '../core/shared/index.js';
 export interface RouterLinkProps extends UseLinkOptions, WithProps<'a'> {
     /**
      * 子节点插槽
      */
-    children?: ValidChildren;
+    children?: RenderChildren;
     /**
      * 是否禁用
      *
@@ -26,10 +26,12 @@ export interface RouterLinkProps extends UseLinkOptions, WithProps<'a'> {
      * 当链接完全匹配时应用的类名
      */
     exactActiveClass?: string;
+    /**
+     * 当链接禁用时应用的类名
+     */
+    disabledClass?: string;
     /**
      * Value passed to the attribute `aria-current` when the link is exact active.
-     *
-     * @defaultValue `'page'`
      */
     ariaCurrentValue?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false';
 }
@@ -40,6 +42,7 @@ export interface RouterLinkProps extends UseLinkOptions, WithProps<'a'> {
  * 动态设置激活状态类名、`href` 属性以及 `aria-current` 无障碍属性。
  *
  * @param {RouterLinkProps} props - 组件属性
+ * @param {CodeLocation} [location] - 代码位置信息
  * @returns {ElementView<'a'>} 返回一个锚点元素视图
  *
  * @example
@@ -54,6 +57,8 @@ export interface RouterLinkProps extends UseLinkOptions, WithProps<'a'> {
  * <RouterLink to="/about" disabled>关于我们</RouterLink>
  * // 透传属性
  * <RouterLink to="/about" class="nav-link">关于我们</RouterLink>
+ * // 带参数的导航
+ * <RouterLink to={{ index: '/user', query: { id: 123 } }}>用户信息</RouterLink>
  * ```
  */
-export declare function RouterLink(props: RouterLinkProps): ElementView<'a'>;
+export declare function RouterLink(props: RouterLinkProps, location?: CodeLocation): ElementView<'a'>;

package/dist/components/RouterLink.js

@@ -1,5 +1,19 @@
-import { createView, isFunction } from 'vitarx';
+import { createView, isFunction, isPlainObject, logger } from 'vitarx';
+import { isExternalLink } from '../core/index.js';
 import { useLink } from '../core/shared/index.js';
+const EXTRA_PROPS = [
+    'to',
+    'replace',
+    'viewTransition',
+    'exactMatchMode',
+    'disabled',
+    'callback',
+    'onclick',
+    'activeClass',
+    'exactActiveClass',
+    'disabledClass',
+    'ariaCurrentValue'
+];
 /**
  * 路由链接组件，渲染为一个 `<a>` 标签，用于在应用内进行声明式导航。
  *
@@ -7,6 +21,7 @@ import { useLink } from '../core/shared/index.js';
  * 动态设置激活状态类名、`href` 属性以及 `aria-current` 无障碍属性。
  *
  * @param {RouterLinkProps} props - 组件属性
+ * @param {CodeLocation} [location] - 代码位置信息
  * @returns {ElementView<'a'>} 返回一个锚点元素视图
  *
  * @example
@@ -21,10 +36,17 @@ import { useLink } from '../core/shared/index.js';
  * <RouterLink to="/about" disabled>关于我们</RouterLink>
  * // 透传属性
  * <RouterLink to="/about" class="nav-link">关于我们</RouterLink>
+ * // 带参数的导航
+ * <RouterLink to={{ index: '/user', query: { id: 123 } }}>用户信息</RouterLink>
  * ```
  */
-export function RouterLink(props) {
+export function RouterLink(props, location) {
     const link = useLink(props);
+    if (__VITARX_DEV__) {
+        if (!link.route.value && !isExternalLink(link.href.value)) {
+            logger.warn(`[RouterLink] No match found for to: ${isPlainObject(props.to) ? JSON.stringify(props.to) : String(props.to)}`, location);
+        }
+    }
     const isDisabled = () => props.disabled ?? false;
     const navigate = async (e) => {
         if (isDisabled())
@@ -36,28 +58,26 @@ export function RouterLink(props) {
     const aProps = {
         onClick: navigate,
         children: props.children,
-        'v-bind': [
-            props,
-            ['to', 'children', 'href', 'disabled', 'callback', 'onClick', 'onclick', 'aria-current']
-        ],
+        'v-bind': [props, EXTRA_PROPS],
         get class() {
             return [
-                !isDisabled() && link.isActive.value ? props.activeClass : undefined,
-                !isDisabled() && link.isExactActive.value ? props.exactActiveClass : undefined
+                props.activeClass && link.isActive.value ? props.activeClass : undefined,
+                props.exactActiveClass && link.isExactActive.value ? props.exactActiveClass : undefined,
+                props.disabledClass && isDisabled() ? props.disabledClass : undefined
             ].filter(Boolean);
         },
         get href() {
             return link.href.value;
-        },
-        get draggable() {
-            return props.draggable ?? false;
-        },
-        get 'aria-current'() {
-            return link.isActive.value && !isDisabled() ? props.ariaCurrentValue || 'page' : undefined;
-        },
-        get disabled() {
-            return isDisabled() ? '' : undefined;
         }
     };
+    if ('ariaCurrentValue' in props) {
+        Object.defineProperty(aProps, 'aria-current', {
+            enumerable: true,
+            configurable: true,
+            get() {
+                return link.isExactActive.value ? props.ariaCurrentValue : undefined;
+            }
+        });
+    }
     return createView('a', aProps);
 }

package/dist/components/RouterView.d.ts

@@ -8,17 +8,18 @@ export interface RouterViewOptions {
      */
     name?: string;
     /**
-     * 渲染页面组件
+     * 自定义渲染当前路由匹配到的组件
      *
-     * 接收两个参数：
+     * 接收三个参数：
      *  - `component: Computed<Component | null>`：当前要渲染的组件，
      *  - `props: Computed<AnyProps | null>`：要注入给组件的属性对象
+     *  - `route: Computed<RouteRecord | null>`：当前匹配的路由记录
      *
      *  @example
      *  ```jsx
      *  // 搭配 Freeze 使用
      *  <RouterView>
-     *    {(component, props, path) => <Freeze is={component} props={props}/>}
+     *    {(component, props) => <Freeze is={component} props={props}/>}
      *  </RouterView>
      *  ```
      *

package/dist/components/RouterView.js

@@ -12,7 +12,7 @@ import { __ROUTER_VIEW_DEPTH_KEY__, useRouter } from '../core/index.js';
  * @returns {View} 返回渲染的视图
  */
 export function RouterView(props) {
-    const { children, name = 'default' } = props;
+    const { children } = props;
     // 获取路由实例
     const router = useRouter();
     // 获取父级 index
@@ -20,6 +20,8 @@ export function RouterView(props) {
     const index = parentIndex + 1; // 计算当前视图的索引
     provide(__ROUTER_VIEW_DEPTH_KEY__, index); // 向子组件提供当前索引
     // 匹配的路由线路
+    const viewName = computed(() => props.name || 'default');
+    // 匹配的路由记录
     const matchedRoute = computed(() => {
         return router.route.matched[index] ?? null;
     });
@@ -28,8 +30,7 @@ export function RouterView(props) {
         const currentRoute = matchedRoute.value;
         if (!currentRoute)
             return null;
-        const name = props.name || 'default'; // 获取视图名称，默认为 'default'
-        let injectProps = currentRoute.props?.[name] ?? router.config.props ?? false;
+        let injectProps = currentRoute.props?.[viewName.value] ?? router.config.props ?? true;
         if (injectProps === false)
             return null; // 如果属性为 false，返回null
         if (injectProps === true && currentRoute.pattern) {
@@ -52,7 +53,7 @@ export function RouterView(props) {
         const route = matchedRoute.value; // 获取匹配的路由记录
         if (!route)
             return null;
-        return route.component?.[name] ?? null;
+        return route.component?.[viewName.value] ?? null;
     });
     // 如果传入了 children 函数，则调用并返回其结果
     if (isFunction(children)) {
@@ -61,6 +62,7 @@ export function RouterView(props) {
         }
         catch (e) {
             logger.error('[RouterView] Error occurred while executing children function', e);
+            return createCommentView(`router-view:error`);
         }
     }
     let lastView = null;

package/dist/core/common/constant.d.ts

@@ -2,34 +2,20 @@
  * 导航状态
  *
  * 枚举值：
- * 0. success: 导航成功
- * 1. aborted: 导航被阻止
- * 2. cancelled: 导航被取消
- * 3. duplicated: 重复导航
- * 4. notfound: 路由未匹配
- * 5. exception: 捕获到异常
+ * 1. success: 导航成功
+ * 2. aborted: 导航被阻止
+ * 4. cancelled: 导航被取消
+ * 8. duplicated: 重复导航
+ * 16. notfound: 路由未匹配
+ * 32. external: 外部链接（不由路由器处理，useLink navigate 内使用）
  */
 export declare enum NavState {
-    /**
-     * 导航成功 (二进制: 0001)
-     */
-    success = 1,// 1
-    /**
-     * 导航被阻止 (二进制: 0010)
-     */
-    aborted = 2,// 2
-    /**
-     * 导航被取消 (二进制: 0100)
-     */
-    cancelled = 4,// 4
-    /**
-     * 重复导航 (二进制: 1000)
-     */
-    duplicated = 8,// 8
-    /**
-     * 路由未匹配 (二进制: 10000)
-     */
-    notfound = 16
+    success = 1,// 1  - 导航成功
+    aborted = 2,// 2  - 导航被阻止
+    cancelled = 4,// 4  - 导航被取消
+    duplicated = 8,// 8  - 重复导航
+    notfound = 16,// 16 - 路由未匹配
+    external = 32
 }
 /**
  * 路由器注入键

package/dist/core/common/constant.js

@@ -2,35 +2,21 @@
  * 导航状态
  *
  * 枚举值：
- * 0. success: 导航成功
- * 1. aborted: 导航被阻止
- * 2. cancelled: 导航被取消
- * 3. duplicated: 重复导航
- * 4. notfound: 路由未匹配
- * 5. exception: 捕获到异常
+ * 1. success: 导航成功
+ * 2. aborted: 导航被阻止
+ * 4. cancelled: 导航被取消
+ * 8. duplicated: 重复导航
+ * 16. notfound: 路由未匹配
+ * 32. external: 外部链接（不由路由器处理，useLink navigate 内使用）
  */
 export var NavState;
 (function (NavState) {
-    /**
-     * 导航成功 (二进制: 0001)
-     */
     NavState[NavState["success"] = 1] = "success";
-    /**
-     * 导航被阻止 (二进制: 0010)
-     */
     NavState[NavState["aborted"] = 2] = "aborted";
-    /**
-     * 导航被取消 (二进制: 0100)
-     */
     NavState[NavState["cancelled"] = 4] = "cancelled";
-    /**
-     * 重复导航 (二进制: 1000)
-     */
     NavState[NavState["duplicated"] = 8] = "duplicated";
-    /**
-     * 路由未匹配 (二进制: 10000)
-     */
-    NavState[NavState["notfound"] = 16] = "notfound"; // 16
+    NavState[NavState["notfound"] = 16] = "notfound";
+    NavState[NavState["external"] = 32] = "external"; // 32 - 外部链接（不由路由器处理）
 })(NavState || (NavState = {}));
 /**
  * 路由器注入键

package/dist/core/common/utils.d.ts

@@ -1,12 +1,29 @@
 import { type AnyCallback } from 'vitarx';
 import type { GuardResult, NavTarget, RouteIndex, RouteLocation, RoutePath, URLHash, URLQuery } from '../types/index.js';
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export declare function isExternalLink(href: string): boolean;
 /**
  * 检查给定的值是否为一个合法的导航配置对象
  *
  * @param val 要检查的未知类型值
  * @returns {boolean} 如果值是一个导航目标对象则返回true，否则返回false
  */
-export declare function hasValidNavTarget(val: unknown): val is NavTarget;
+export declare function isNavTarget(val: unknown): val is NavTarget;
+/**
+ * 检查给定的值是否为 RouteLocation 对象
+ *
+ * 通过检测 `matched` 和 `path` 属性来区分 RouteLocation 与 NavTarget，
+ * 因为 NavTarget 不包含这两个字段，而 RouteLocation 必定包含。
+ *
+ * @param val - 需要检查的值
+ * @returns {val is RouteLocation} 如果是 RouteLocation 对象则返回 true
+ */
+export declare function isRouteLocation(val: unknown): val is RouteLocation;
 /**
  * 检查给定的值是否为有效的路由索引
  *
@@ -14,7 +31,7 @@ export declare function hasValidNavTarget(val: unknown): val is NavTarget;
  * @returns {boolean} 返回一个布尔值，表示值是否为有效的路由索引
  * 同时使用类型谓词(val is RouteIndex)来缩小类型范围
  */
-export declare function hasValidRouteIndex(val: unknown): val is RouteIndex;
+export declare function isNavIndex(val: unknown): val is RouteIndex;
 /**
  * 判断两个路由位置对象是否只有 hash 不同
  *
@@ -28,7 +45,7 @@ export declare function hasOnlyChangeHash(route1: RouteLocation, route2: RouteLo
  * @param index - 要判断的索引
  * @returns {boolean} - 如果索引为路径索引则返回true，否则返回false
  */
-export declare function hasValidPath(index: any): index is RoutePath;
+export declare function isRoutePath(index: unknown): index is RoutePath;
 /**
  * 移除路径字符串中的指定后缀
  * @param path - 原始路径字符串