@xiao-ying/miniapp-router

该包提供 XiaoYing 小应小程序前端的 Hash Router 相关工具，统一处理路由 base、hash 解析与跳转 URL 生成，减少重复样板代码。

安装

在模板仓库内使用 workspace 依赖：

{
  "dependencies": {
    "@xiao-ying/miniapp-router": "workspace:*"
  }
}

在独立项目中使用本地路径依赖：

{
  "dependencies": {
    "@xiao-ying/miniapp-router": "file:../xiaoying-miniapp-sdk/router"
  }
}

快速使用

import { createHashRouterTools } from '@xiao-ying/miniapp-router'

const { routerBase, resolvePathWithHash, buildHashHref } = createHashRouterTools(import.meta.env)

createHashRouter 基础配置

import { createHashRouter } from 'react-router-dom'
import { createHashRouterTools } from '@xiao-ying/miniapp-router'

const { routerBase } = createHashRouterTools(import.meta.env)

export const router = createHashRouter(
  [
    { path: '/', element: <Home /> },
    { path: '*', element: <NotFound /> }
  ],
  routerBase === '/' ? undefined : { basename: routerBase }
)

解析 hash 路径并用于重定向

import { redirect } from 'react-router-dom'
import { createHashRouterTools } from '@xiao-ying/miniapp-router'

const { resolvePathWithHash } = createHashRouterTools(import.meta.env)

const authLoader = async ({ request }: { request: Request }) => {
  const redirectTarget = resolvePathWithHash(request.url)
  return redirect(`/login?redirect=${encodeURIComponent(redirectTarget)}`)
}

构造 Hash 跳转地址

import { createHashRouterTools } from '@xiao-ying/miniapp-router'

const { buildHashHref } = createHashRouterTools(import.meta.env)

const goHome = () => {
  window.location.href = buildHashHref('/')
}

API

type RouterEnv = {
  VITE_ROUTER_BASE?: string
  VITE_BASE_URL?: string
  BASE_URL?: string
}

const tools = createHashRouterTools(env)

createHashRouterTools(env) 返回：

• routerBase: 规范化后的路由 base，适用于 createHashRouter 的 basename。
• routerBasename: 仅用于 basename 场景的字符串（内部使用）。
• baseUrl: 规范化后的 BASE_URL（末尾含 /）。
• stripBasename(pathname): 去掉 basename（用于 pathname）。
• stripRouterBase(path): 去掉 routerBase（支持 ?query）。
• withRouterBase(path): 将 path 拼接到 routerBase 上。
• resolvePathWithHash(requestUrl): 解析 loader 请求 URL，优先从 hash 恢复真实路径。
• buildHashHref(path): 基于 BASE_URL 构造 /#/path 形式的 URL。

环境变量约定

• VITE_ROUTER_BASE: 路由 basename（推荐）。
• VITE_BASE_URL: 静态资源 base（用于 Vite）。
• BASE_URL: Vite 内置 base（import.meta.env.BASE_URL）。

工具会按优先级综合以上变量，确保在 hash router 下得到一致的解析行为。