路由

HeroUI 组件（如 Tabs、Listbox、Dropdown 等）拥有将其渲染为 HTML 链接 的灵活性。

简介

默认情况下，链接在被点击时会触发浏览器原生导航。然而，许多应用和框架使用客户端路由器，以避免在页面切换时进行完全页面重新加载。

HeroUIProvider 组件会将其内部的所有 HeroUI 组件配置为使用您提供的客户端路由器进行导航。

在应用根部仅需设置一次此配置，任何带有 href 属性的 HeroUI 组件都会自动使用您的路由器导航。

HeroUIProvider 设置

HeroUIProvider 组件接受 navigate 与 useHref 两个属性。navigate 是用于客户端导航的路由函数，而 useHref 可选地将路由 href 转换为原生 HTML href。下面给出一种常见的实现方式：

注意：以下示例展示了特定框架的实现方式。

Router Options

所有 HeroUI 链接组件都接受 routerOptions 属性，可将选项传递给路由器的 navigate 函数，以控制滚动和历史导航等行为。

在使用 TypeScript 时，您可以全局配置 RouterConfig 类型，使所有链接组件在使用路由器提供的类型时具备自动补全和类型安全。

Next.js

App Router

请前往 app/providers.tsx 或 app/providers.jsx（若不存在请创建），并添加来自 next/navigation 的 useRouter 钩子，该钩子返回一个路由对象，可用于进行导航。

请查看 Next.js 文档以获取更多信息。

添加 `useRouter`

添加 Provider 到根布局

现在，请前往 root 布局页面，并用 HeroUIProvider 包裹它：

注意：如果您已在应用中设置过 HeroUIProvider，请跳过此步骤。

下一步：Next.js 基础路径（可选）

如果您正在使用 Next.js 的 basePath 设置，需要配置一个环境变量以使用该路径。

然后，提供一个自定义 useHref 函数，以在所有链接的 href 前自动添加该 basePath。

Pages Router

请前往 pages/_app.js 或 pages/_app.tsx（如不存在请创建），并添加来自 next/router 的 useRouter 钩子，该钩子返回一个路由对象，可用于导航。

当使用 basePath 配置时，请为传递给 Provider 的路由器提供 useHref 选项，以便自动为链接添加前缀。

React Router

使用 react-router-dom 的 useNavigate 钩子获取路由器的 navigate 函数。useHref 钩子可与 React Router 的 basename 选项一起使用。

请确保使用这些钩子的组件位于 BrowserRouter 内部，同时将 <Routes> 放置在 HeroUIProvider 内。以下是在 App 组件中设置的示例：

请确保调用 useNavigate 并渲染 HeroUIProvider 的组件位于路由器组件内（例如 BrowserRouter），以便它能访问 React Router 的内部上下文。React Router 的 <Routes> 元素也应定义在 HeroUIProvider 内，以便渲染的路由内部链接能访问路由器。

路由

简介