vitarx-router 4.0.0-beta.24 → 4.0.0-beta.26

package/README.md

@@ -291,6 +291,7 @@ if (hasSuccess(result)) {
 | `cancelled`  | 4  | 导航被新导航取消 |
 | `duplicated` | 8  | 重复导航     |
 | `notfound`   | 16 | 路由未匹配    |
+| `external`   | 32 | 外部跳转     |
 
 ## 路由未匹配处理
 
@@ -536,20 +537,31 @@ declare module 'vitarx-router' {
 
 ### 助手函数
 
-| 函数                                             | 说明                     |
-|------------------------------------------------|------------------------|
-| `createRouter(options)`                        | 创建路由器实例                |
-| `createWebRouter(options)`                     | 创建 Web 模式路由器           |
-| `createMemoryRouter(options)`                  | 创建 Memory 模式路由器        |
-| `createRouteManager(routes, options?)`         | 创建路由管理器                |
-| `defineRoutes(...routes)`                      | 定义路由表                  |
-| `createMissingRoute(component, target, meta?)` | 创建未匹配路由的 RouteLocation |
-| `useRouter()`                                  | 获取路由器实例                |
-| `useRoute(global?)`                            | 获取当前路由信息               |
-| `useLink(options)`                             | 创建链接助手                 |
-| `onBeforeRouteLeave(guard)`                    | 注册离开守卫                 |
-| `onBeforeRouteUpdate(callback)`                | 注册更新钩子                 |
-| `removePathEndSlash(path)`                     | 删除路径末尾的斜杠              |
+| 函数                                             | 说明                        |
+|------------------------------------------------|---------------------------|
+| `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 实例方法
 

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

@@ -21,6 +21,7 @@ export function RouterView(props) {
     provide(__ROUTER_VIEW_DEPTH_KEY__, index); // 向子组件提供当前索引
     // 匹配的路由线路
     const viewName = computed(() => props.name || 'default');
+    // 匹配的路由记录
     const matchedRoute = computed(() => {
         return router.route.matched[index] ?? null;
     });

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

@@ -7,28 +7,15 @@
  * 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

@@ -7,29 +7,16 @@
  * 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,19 @@
 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 对象
  *
@@ -24,7 +31,7 @@ export declare function isRouteLocation(val: unknown): val is RouteLocation;
  * @returns {boolean} 返回一个布尔值，表示值是否为有效的路由索引
  * 同时使用类型谓词(val is RouteIndex)来缩小类型范围
  */
-export declare function hasValidRouteIndex(val: unknown): val is RouteIndex;
+export declare function isNavIndex(val: unknown): val is RouteIndex;
 /**
  * 判断两个路由位置对象是否只有 hash 不同
  *
@@ -38,7 +45,7 @@ export declare function hasOnlyChangeHash(route1: RouteLocation, route2: RouteLo
  * @param index - 要判断的索引
  * @returns {boolean} - 如果索引为路径索引则返回true，否则返回false
  */
-export declare function isValidPath(index: unknown): index is RoutePath;
+export declare function isRoutePath(index: unknown): index is RoutePath;
 /**
  * 移除路径字符串中的指定后缀
  * @param path - 原始路径字符串

package/dist/core/common/utils.js

@@ -1,13 +1,22 @@
 import { isDeepEqual, isPlainObject, isString } from 'vitarx';
 import { normalizePath, parseQuery } from '../shared/utils.js';
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export function isExternalLink(href) {
+    return href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//');
+}
 /**
  * 检查给定的值是否为一个合法的导航配置对象
  *
  * @param val 要检查的未知类型值
  * @returns {boolean} 如果值是一个导航目标对象则返回true，否则返回false
  */
-export function hasValidNavTarget(val) {
-    return isPlainObject(val) && 'index' in val && hasValidRouteIndex(val.index);
+export function isNavTarget(val) {
+    return isPlainObject(val) && 'index' in val && isNavIndex(val.index);
 }
 /**
  * 检查给定的值是否为 RouteLocation 对象
@@ -28,7 +37,7 @@ export function isRouteLocation(val) {
  * @returns {boolean} 返回一个布尔值，表示值是否为有效的路由索引
  * 同时使用类型谓词(val is RouteIndex)来缩小类型范围
  */
-export function hasValidRouteIndex(val) {
+export function isNavIndex(val) {
     // 检查值是否为字符串类型或者是否为symbol类型
     return isString(val) || typeof val === 'symbol';
 }
@@ -40,7 +49,7 @@ export function hasValidRouteIndex(val) {
  */
 export function hasOnlyChangeHash(route1, route2) {
     return (route1.hash !== route2.hash &&
-        route1.path === route2.path &&
+        route1.matched.at(-1) === route2.matched.at(-1) &&
         isDeepEqual(route1.query, route2.query));
 }
 /**
@@ -49,7 +58,7 @@ export function hasOnlyChangeHash(route1, route2) {
  * @param index - 要判断的索引
  * @returns {boolean} - 如果索引为路径索引则返回true，否则返回false
  */
-export function isValidPath(index) {
+export function isRoutePath(index) {
     return isString(index) && index.startsWith('/');
 }
 /**
@@ -98,7 +107,7 @@ export function processGuardResult(res) {
     if ((res && isString(res)) || typeof res === 'symbol') {
         return { index: res };
     }
-    if (hasValidNavTarget(res))
+    if (isNavTarget(res))
         return res;
     return true;
 }
@@ -111,7 +120,7 @@ export function resolveNavTarget(index) {
     if (isString(index) || typeof index === 'symbol') {
         return { index };
     }
-    if (hasValidNavTarget(index)) {
+    if (isNavTarget(index)) {
         return index;
     }
     if (isPlainObject(index) && index.path && index.matched) {

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export * from './common/constant.js';
+export { isNavTarget, isNavIndex, isRouteLocation, isRoutePath, isExternalLink } from './common/utils.js';
 export * from './router/index.js';
 export * from './shared/index.js';
 export type * from './types/index.js';

package/dist/core/index.js

@@ -1,3 +1,4 @@
 export * from './common/constant.js';
+export { isNavTarget, isNavIndex, isRouteLocation, isRoutePath, isExternalLink } from './common/utils.js';
 export * from './router/index.js';
 export * from './shared/index.js';

package/dist/core/router/manager.js

@@ -1,6 +1,6 @@
 import { isArray, isFunction, isString, logger, markRaw } from 'vitarx';
 import { resolveComponent, resolvePattern, resolveProps } from '../common/resolve.js';
-import { hasValidNavTarget, hasValidRouteIndex, isValidPath } from '../common/utils.js';
+import { isNavIndex, isNavTarget, isRoutePath } from '../common/utils.js';
 import { isVariablePath, mergePathVariable, mergePattern, optionalVariableCount, validateAliasVariables } from '../common/variable.js';
 import { normalizePath } from '../shared/utils.js';
 /**
@@ -288,7 +288,7 @@ export class RouteManager {
      * @returns 匹配结果对象，包含路由记录和解析后的参数；未匹配返回 null
      */
     match(index, params) {
-        if (isValidPath(index)) {
+        if (isRoutePath(index)) {
             return this.matchByPath(index);
         }
         return this.matchByName(index, params);
@@ -474,9 +474,7 @@ export class RouteManager {
             record.props = props;
         }
         if (route.redirect &&
-            (isFunction(route.redirect) ||
-                hasValidRouteIndex(route.redirect) ||
-                hasValidNavTarget(route.redirect))) {
+            (isFunction(route.redirect) || isNavIndex(route.redirect) || isNavTarget(route.redirect))) {
             record.redirect = route.redirect;
         }
         if (!component && !route.redirect && !isGroup) {

package/dist/core/router/router.d.ts

@@ -132,8 +132,8 @@ export declare abstract class Router {
     /**
      * 判断路由器是否已准备就绪
      *
-     * 返回一个 Promise，它会在路由器完成初始导航之后被解析，
-     * 如果初始导航已经完成，则该 Promise 会被立刻解析。
+     * 返回一个 Promise，它会在路由器完成首次导航之后被解析，
+     * 如果首次导航已经完成，则该 Promise 会被立刻解析。
      *
      * @returns {Promise<void>} - 导航结果
      */
@@ -425,6 +425,7 @@ export declare abstract class Router {
      * 导航到指定位置
      *
      * 作为导航流程的编排器，按顺序协调各场景处理方法的执行：
+     * 0. 处理外部链接
      * 1. 创建导航上下文（路由匹配、并发控制初始化）
      * 2. 处理 404 场景（路由未匹配）
      * 3. 处理重复路由场景

package/dist/core/router/router.js

@@ -1,7 +1,7 @@
 import { getLazyLoader, isArray, isFunction, isPlainObject, isPromise, isString, logger, nextTick, preloadComponent, readonly, shallowReactive } from 'vitarx';
 import { __ROUTER_KEY__, NavState } from '../common/constant.js';
 import { updateRouteLocation } from '../common/update.js';
-import { hasOnlyChangeHash, hasValidNavTarget, hasValidRouteIndex, isRouteLocation, isValidPath, processGuardResult, registerHookTool, removePathSuffix, resolveNavTarget } from '../common/utils.js';
+import { hasOnlyChangeHash, isExternalLink, isNavIndex, isNavTarget, isRouteLocation, isRoutePath, processGuardResult, registerHookTool, removePathSuffix, resolveNavTarget } from '../common/utils.js';
 import { cloneRouteLocation, normalizePath, stringifyQuery } from '../shared/utils.js';
 import { checkRouterOptions } from './checkOptions.js';
 import { RouteManager } from './manager.js';
@@ -186,8 +186,8 @@ export class Router {
     /**
      * 判断路由器是否已准备就绪
      *
-     * 返回一个 Promise，它会在路由器完成初始导航之后被解析，
-     * 如果初始导航已经完成，则该 Promise 会被立刻解析。
+     * 返回一个 Promise，它会在路由器完成首次导航之后被解析，
+     * 如果首次导航已经完成，则该 Promise 会被立刻解析。
      *
      * @returns {Promise<void>} - 导航结果
      */
@@ -446,7 +446,7 @@ export class Router {
         const to = this.matchRoute(target, redirectFrom);
         // name-based 导航匹配失败视为编程错误，直接抛出异常
         // 因为名称导航是编程式调用，name 不存在或参数校验失败属于代码 bug
-        if (!to && !isValidPath(target.index)) {
+        if (!to && !isRoutePath(target.index)) {
             const name = target.index;
             const route = this.manager.findByName(name);
             if (route) {
@@ -590,6 +590,8 @@ export class Router {
         if (!context.to)
             return null;
         if (hasOnlyChangeHash(context.to, context.from)) {
+            // 更新路由位置的 hash 值并触发 hashUpdate 回调
+            this._routeLocation.hash = context.to.hash;
             this._routeLocation.href = context.to.href;
             this.hashUpdate?.(context.to);
             context.result.state = NavState.success;
@@ -621,12 +623,12 @@ export class Router {
         if (!redirect)
             return null;
         // 重定向目标为路由索引（路径或名称）
-        if (hasValidRouteIndex(redirect)) {
+        if (isNavIndex(redirect)) {
             context.checkRedirectLoop(String(redirect));
             return this.navigate({ index: redirect }, context.from, context.redirectFrom ?? to);
         }
         // 重定向目标为完整的导航目标对象
-        if (hasValidNavTarget(redirect)) {
+        if (isNavTarget(redirect)) {
             context.checkRedirectLoop(String(redirect.index));
             return this.navigate(redirect, context.from, context.redirectFrom ?? to);
         }
@@ -696,7 +698,7 @@ export class Router {
             return context.result;
         }
         // 守卫重定向
-        if (hasValidNavTarget(guardResult)) {
+        if (isNavTarget(guardResult)) {
             context.checkRedirectLoop(String(guardResult.index));
             return this.navigate(guardResult, context.from, context.redirectFrom ?? context.to ?? undefined);
         }
@@ -724,6 +726,7 @@ export class Router {
      * 导航到指定位置
      *
      * 作为导航流程的编排器，按顺序协调各场景处理方法的执行：
+     * 0. 处理外部链接
      * 1. 创建导航上下文（路由匹配、并发控制初始化）
      * 2. 处理 404 场景（路由未匹配）
      * 3. 处理重复路由场景
@@ -738,6 +741,14 @@ export class Router {
      * @returns - 返回导航结果
      */
     async navigate(target, fromRoute, redirectFrom) {
+        if (isString(target.index) && isExternalLink(target.index)) {
+            return {
+                state: NavState.external,
+                message: `Navigate to the external link ${target.index}`,
+                to: null,
+                from: fromRoute ?? cloneRouteLocation(this._routeLocation)
+            };
+        }
         // 创建导航上下文
         const context = this.createNavigationContext(target, fromRoute, redirectFrom);
         // 路由未匹配 (404)
@@ -836,7 +847,7 @@ export class Router {
                 if (isRouteLocation(result))
                     return result;
                 // 判断 NavTarget（有 index 属性）
-                if (hasValidNavTarget(result))
+                if (isNavTarget(result))
                     return result;
                 // 字符串或 symbol 包装为 NavTarget
                 if (isString(result) || typeof result === 'symbol') {
@@ -1017,7 +1028,7 @@ export class Router {
      */
     matchRoute(target, redirectFrom) {
         let matchTarget = target.index;
-        const isPath = isValidPath(matchTarget);
+        const isPath = isRoutePath(matchTarget);
         // 如果配置了后缀且目标是路径，则去除后缀
         if (this.config.suffix && isPath) {
             // 去除路径后缀

package/dist/core/router/web.js

@@ -140,9 +140,14 @@ export class WebRouter extends Router {
             if ('el' in target && target.el) {
                 const { el, ...rest } = target;
                 if (isString(el)) {
-                    // 对选择器字符串进行转义
-                    const escapedSelector = el.replace(/([!"#$%&'()*+,.\/:;<=>?@[\\\]^`{|}~])/g, '\\$1');
-                    const element = document.querySelector(escapedSelector);
+                    let element = null;
+                    try {
+                        element = document.querySelector(el);
+                    }
+                    catch (e) {
+                        logger.warn(`[Router] Invalid selector "${el}", skipping scroll to element`, e);
+                        return;
+                    }
                     if (element) {
                         if (element.scrollIntoView) {
                             element.scrollIntoView(rest);

package/dist/core/shared/link.d.ts

@@ -1,7 +1,7 @@
 import { type Computed } from 'vitarx';
-import type { NavigateResult, NavTarget, RouteIndex, RouteLocation, RoutePath, URLHash } from '../types/index.js';
-export type HTTPUrl = `http://${string}` | `https://${string}`;
-type LinkToTarget<T extends RouteIndex = RouteIndex> = NavTarget<T> | T | `${RoutePath}?${string}` | URLHash | HTTPUrl;
+import type { NavigateResult, NavTarget, RouteIndex, RouteLocation } from '../types/index.js';
+type LinkToTarget<T extends RouteIndex = RouteIndex> = NavTarget<T> | T | string;
+export type LinkExactMatchMode = 'path' | 'href' | 'hash' | 'query';
 export interface UseLinkOptions<T extends RouteIndex = RouteIndex> {
     /**
      * 要跳转的目标
@@ -23,6 +23,17 @@ export interface UseLinkOptions<T extends RouteIndex = RouteIndex> {
      * @default false
      */
     viewTransition?: boolean;
+    /**
+     * 精确匹配模式
+     *
+     * - 'path'：精确匹配路径
+     * - 'href'：精确匹配完整链接
+     * - 'hash'：精确匹配路径和锚点
+     * - 'query'：精确匹配路径和查询参数
+     *
+     * @default 'path'
+     */
+    exactMatchMode?: LinkExactMatchMode;
 }
 export interface UseLinkReturn {
     /**
@@ -46,15 +57,40 @@ export interface UseLinkReturn {
      *
      * @param [e] 点击事件
      */
-    navigate: (e?: MouseEvent) => Promise<NavigateResult | void>;
+    navigate: (e?: MouseEvent) => Promise<NavigateResult>;
 }
 /**
- * 判断是否为外部链接
+ * 判断当前路径是否以目标路径为前缀（路径段级别匹配）
+ *
+ * 去除尾部斜杠后，判断 currentPath 是否等于 targetPath 或以 targetPath/ 开头，
+ * 避免如 `/users-admin` 错误匹配 `/users` 的问题。
+ *
+ * @example
+ * isPathPrefixMatch('/users/123', '/users') // true
+ * isPathPrefixMatch('/users', '/users') // true
+ * isPathPrefixMatch('/users-admin', '/users') // false
+ * isPathPrefixMatch('/', '/') // true
+ *
+ * @param currentPath - 当前路由路径
+ * @param targetPath - 目标路由路径
+ * @returns 是否为前缀匹配
+ */
+export declare function isPathPrefixMatch(currentPath: string, targetPath: string): boolean;
+/**
+ * 判断当前路径是否与目标路径完全匹配
+ *
+ * 去除尾部斜杠后进行严格相等比较。
+ *
+ * @example
+ * isPathExactMatch('/users', '/users') // true
+ * isPathExactMatch('/users/', '/users') // true
+ * isPathExactMatch('/users/123', '/users') // false
  *
- * @param href - 链接地址
- * @returns 是否为外部链接
+ * @param currentPath - 当前路由路径
+ * @param targetPath - 目标路由路径
+ * @returns 是否为精确匹配
  */
-export declare function isExternalLink(href: string): boolean;
+export declare function isPathExactMatch(currentPath: string, targetPath: string): boolean;
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
  *
@@ -63,6 +99,7 @@ export declare function isExternalLink(href: string): boolean;
  * @param props.to - 要跳转的目标，可以是路由目标对象、路由索引、带查询参数的路径字符串、哈希值或 HTTP/HTTPS 链接。
  * @param [props.replace] - 是否使用 `router.replace()` 而不是 `router.push()`。优先级低于 `to.replace`。默认为 `false`。
  * @param [props.viewTransition] - 如果支持则使用 `document.startViewTransition()` 进行视图过渡。默认为 `false`。
+ * @param [props.exactMatchMode] - 精确匹配模式。可选值有：'path'、'href'、'hash'、'query'。默认为 'path'。
  * @returns 返回一个包含链接属性和导航方法的对象。
  * @returns {Computed<string>} returns.href - 链接的 `href` 属性值。
  * @returns {Computed<RouteLocation | null>} returns.route - 匹配的路由信息，如果未匹配则返回 `null`。

package/dist/core/shared/link.js

@@ -1,27 +1,59 @@
-import { computed, isPlainObject, isString, logger } from 'vitarx';
-import { hasValidNavTarget, isValidPath } from '../common/utils.js';
+import { computed, isPlainObject, isString } from 'vitarx';
+import { NavState } from '../common/constant.js';
+import { isExternalLink, isNavTarget, isRoutePath } from '../common/utils.js';
 import { useRouter } from './inject.js';
-import { cloneRouteLocation, parseQuery } from './utils.js';
+import { cloneRouteLocation, parseQuery, removeTrailingSlash, stringifyQuery } from './utils.js';
 /**
  * 处理视图转换
  * @param callback
  */
-const handleTransition = async (callback) => {
+async function handleTransition(callback) {
     if (typeof document === 'undefined' || typeof document.startViewTransition !== 'function') {
         await callback();
         return;
     }
     const transition = document.startViewTransition(callback);
     await transition.finished;
-};
+}
+/**
+ * 判断当前路径是否以目标路径为前缀（路径段级别匹配）
+ *
+ * 去除尾部斜杠后，判断 currentPath 是否等于 targetPath 或以 targetPath/ 开头，
+ * 避免如 `/users-admin` 错误匹配 `/users` 的问题。
+ *
+ * @example
+ * isPathPrefixMatch('/users/123', '/users') // true
+ * isPathPrefixMatch('/users', '/users') // true
+ * isPathPrefixMatch('/users-admin', '/users') // false
+ * isPathPrefixMatch('/', '/') // true
+ *
+ * @param currentPath - 当前路由路径
+ * @param targetPath - 目标路由路径
+ * @returns 是否为前缀匹配
+ */
+export function isPathPrefixMatch(currentPath, targetPath) {
+    const current = removeTrailingSlash(currentPath);
+    const target = removeTrailingSlash(targetPath);
+    if (target === '/')
+        return current.startsWith('/');
+    return current === target || current.startsWith(target + '/');
+}
 /**
- * 判断是否为外部链接
+ * 判断当前路径是否与目标路径完全匹配
+ *
+ * 去除尾部斜杠后进行严格相等比较。
  *
- * @param href - 链接地址
- * @returns 是否为外部链接
+ * @example
+ * isPathExactMatch('/users', '/users') // true
+ * isPathExactMatch('/users/', '/users') // true
+ * isPathExactMatch('/users/123', '/users') // false
+ *
+ * @param currentPath - 当前路由路径
+ * @param targetPath - 目标路由路径
+ * @returns 是否为精确匹配
  */
-export function isExternalLink(href) {
-    return href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//');
+export function isPathExactMatch(currentPath, targetPath) {
+    return removeTrailingSlash(currentPath) === removeTrailingSlash(targetPath);
 }
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
@@ -31,6 +63,7 @@ export function isExternalLink(href) {
  * @param props.to - 要跳转的目标，可以是路由目标对象、路由索引、带查询参数的路径字符串、哈希值或 HTTP/HTTPS 链接。
  * @param [props.replace] - 是否使用 `router.replace()` 而不是 `router.push()`。优先级低于 `to.replace`。默认为 `false`。
  * @param [props.viewTransition] - 如果支持则使用 `document.startViewTransition()` 进行视图过渡。默认为 `false`。
+ * @param [props.exactMatchMode] - 精确匹配模式。可选值有：'path'、'href'、'hash'、'query'。默认为 'path'。
  * @returns 返回一个包含链接属性和导航方法的对象。
  * @returns {Computed<string>} returns.href - 链接的 `href` 属性值。
  * @returns {Computed<RouteLocation | null>} returns.route - 匹配的路由信息，如果未匹配则返回 `null`。
@@ -48,7 +81,7 @@ export function useLink(props) {
         const to = props.to;
         let target = null;
         // 验证目标类型
-        if (hasValidNavTarget(to)) {
+        if (isNavTarget(to)) {
             target = to;
         }
         else if (isString(to)) {
@@ -61,12 +94,9 @@ export function useLink(props) {
             target = { index: to };
         }
         else {
-            if (__VITARX_DEV__) {
-                logger.warn(`[RouterLink] Invalid "to" prop: ${isPlainObject(to) ? JSON.stringify(to) : String(to)}`);
-            }
             return null;
         }
-        // 处理字符串目标
+        // 处理路由路径
         if (isString(target.index)) {
             // 兼容纯锚点连接跳转
             if (target.index.startsWith('#')) {
@@ -88,28 +118,19 @@ export function useLink(props) {
                 target.query = parseQuery(queryString);
             }
         }
-        const route = router.matchRoute(target);
-        if (route)
-            return route;
-        if (__VITARX_DEV__) {
-            logger.warn(`[RouterLink] No match found for to ${isPlainObject(to) ? JSON.stringify(to) : String(to)}`);
-        }
-        return null;
+        return router.matchRoute(target);
     });
     /**
      * 计算属性：生成链接的 href 属性
      * @returns 返回路由的 href 或原始字符串，默认返回 'javascript:void(0)'
      */
     const href = computed(() => {
-        if (route.value?.href) {
+        if (route.value?.href)
             return route.value.href;
-        }
-        if (isPlainObject(props.to) && isValidPath(props.to.index)) {
+        if (isPlainObject(props.to) && isRoutePath(props.to.index))
             return props.to.index;
-        }
-        if (isString(props.to)) {
+        if (isString(props.to))
             return props.to;
-        }
         return 'javascript:void(0)';
     });
     /**
@@ -120,7 +141,7 @@ export function useLink(props) {
         const matchedRoute = route.value;
         if (!matchedRoute)
             return false;
-        return router.route.href.startsWith(matchedRoute.path);
+        return isPathPrefixMatch(router.route.path, matchedRoute.path);
     });
     /**
      * 计算属性：判断当前路由是否是精确激活状态
@@ -130,39 +151,60 @@ export function useLink(props) {
         const matchedRoute = route.value;
         if (!matchedRoute)
             return false;
-        return router.route.path === matchedRoute.path;
+        const isMatched = isPathExactMatch(router.route.path, matchedRoute.path);
+        if (!isMatched)
+            return false;
+        const mode = props.exactMatchMode || 'path';
+        switch (mode) {
+            case 'href':
+                return router.route.href === matchedRoute.href;
+            case 'hash':
+                return router.route.hash === matchedRoute.hash;
+            case 'query':
+                return stringifyQuery(router.route.query) === stringifyQuery(matchedRoute.query);
+            default:
+                return true;
+        }
     });
     /**
      * 导航处理函数
      * @param e - 可选的鼠标事件对象
-     * @returns 返回导航结果，如果没有匹配路由则返回 undefined
+     * @returns {Promise<NavigateResult | void>} 如果
      */
     const navigate = async (e) => {
-        const matchedRoute = route.value;
-        // 如果没有匹配的路由，则返回 void 0
-        if (!matchedRoute) {
-            if (href.value === 'javascript:void(0)') {
-                logger.warn(`[RouterLink] No match found for to ${isPlainObject(props.to) ? JSON.stringify(props.to) : String(props.to)}`);
-                e?.preventDefault();
-            }
-            return void 0;
+        const routeHref = href.value;
+        // 如果是无效的链接或外部链接都返回模拟的未匹配路由结果
+        if (routeHref === 'javascript:void(0)') {
+            return {
+                state: NavState.notfound,
+                message: `No match found for target: ${isPlainObject(props.to) ? JSON.stringify(props.to) : String(props.to)}`,
+                to: null,
+                from: cloneRouteLocation(router.route)
+            };
+        }
+        if (isExternalLink(routeHref)) {
+            return {
+                state: NavState.external,
+                message: `Open External link ${routeHref}`,
+                to: null,
+                from: cloneRouteLocation(router.route)
+            };
         }
         // 阻止默认行为
         e?.preventDefault();
         const defaultReplace = props.replace ?? false;
-        const isReplace = hasValidNavTarget(props.to)
-            ? (props.to.replace ?? defaultReplace)
-            : defaultReplace;
+        const isReplace = isNavTarget(props.to) ? (props.to.replace ?? defaultReplace) : defaultReplace;
         let result;
+        const routeTarget = route.value || routeHref;
         // 处理视图过渡
         if (!__VITARX_SSR__ && props.viewTransition) {
             await handleTransition(async () => {
-                result = isReplace ? await router.replace(matchedRoute) : await router.push(matchedRoute);
+                result = isReplace ? await router.replace(routeTarget) : await router.push(routeTarget);
                 await router.waitViewRender();
             });
         }
         else {
-            result = isReplace ? await router.replace(matchedRoute) : await router.push(matchedRoute);
+            result = isReplace ? await router.replace(routeTarget) : await router.push(routeTarget);
         }
         return result;
     };

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

@@ -24,7 +24,7 @@ export declare function stringifyQuery(obj: Record<string, string>): `?${string}
  * @param {string} str - 路径字符串
  * @return {string} - 去除末尾斜杠后的路径字符串
  */
-export declare function removePathEndSlash<T extends string>(str: T): T;
+export declare function removeTrailingSlash<T extends string>(str: T): T;
 /**
  * 归一化path
  *

package/dist/core/shared/utils.js

@@ -35,7 +35,7 @@ export function stringifyQuery(obj) {
  * @param {string} str - 路径字符串
  * @return {string} - 去除末尾斜杠后的路径字符串
  */
-export function removePathEndSlash(str) {
+export function removeTrailingSlash(str) {
     if (str === '/')
         return str;
     return str.endsWith('/') ? str.slice(0, -1) : str;
@@ -60,7 +60,7 @@ export function normalizePath(path, removeEndSlash = false) {
     // 去除所有空格 处理重复//
     let normalizedPath = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
     if (removeEndSlash) {
-        normalizedPath = removePathEndSlash(normalizedPath);
+        normalizedPath = removeTrailingSlash(normalizedPath);
     }
     // 去除尾随斜杠
     return normalizedPath;

package/dist/core/types/navigation.d.ts

@@ -120,7 +120,7 @@ export interface NavigateResult {
     /**
      * 目标路由位置
      *
-     * `state !== NavState.notfound` 时存在
+     * `state !== NavState.notfound` 和 `state !== NavState.external` 时存在
      */
     to: RouteLocation | null;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.24",
+  "version": "4.0.0-beta.26",
   "description": "Official routing solution for Vitarx framework with declarative routing, navigation guards, dynamic routes, file-based routing with HMR, and full TypeScript support.",
   "author": "ZhuChonglin <8210856@qq.com>",
   "license": "MIT",
@@ -55,6 +55,9 @@
   "peerDependenciesMeta": {
     "vite": {
       "optional": true
+    },
+    "vitarx": {
+      "optional": true
     }
   },
   "dependencies": {