# @btst/yar 中文文档

规范地址：https://npmcn.com/package/%40btst/yar/

版本：1\.3\.2
npm 元数据更新时间：2026-08-22T18:46:23.181Z
中文译文更新时间：2026-11-08T18:39:31.051Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40btst/yar
原文对照：https://npmcn.com/package/%40btst/yar/?lang=original
项目主页：https://github.com/better-stack-ai/yar#readme
源码仓库：https://github.com/better-stack-ai/yar

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：92.2 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@types/react ^18\.0\.0 \|\| ^19\.0\.0，@types/react-dom ^18\.0\.0 \|\| ^19\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-10-13T20:27:39.245Z
- 最新版本发布：2026-08-22T18:46:22.842Z
- 近 30 天下载量：4537（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 3 个）

## 中文简介

用于现代反应框架的可插路由器

## 安装

```sh
npm install @btst/yar
```

也可以使用：`pnpm add @btst/yar`、`yarn add @btst/yar`、`bun add @btst/yar`

## README

# @btst/yar(Yet Another 路由器)

一个简单的,类型安全的路由器,用于React,它与任何框架一起工作.

## 为什么用这个?

-   ✨ **超级简单** - 一个小小的API: `createRoute` 财务报告和审定财务报表 `createRouter` (加上可选) `defineRoute`编号 :`defineRoutes` 糖类)
-   🔒 **类型安全** - TypeScript 自动知道您的路径参数
-   🎯 **弹性** - 使用任何反应框架
-   ✅ **已验证** - 内建查询参数验证

## 安装

```bash
npm install @btst/yar
# or
pnpm add @btst/yar
```

## 快速启动

以下是一个完整的例子,显示了所有特征:

```tsx
import { createRoute, createRouter } from "@btst/yar";
import { z } from "zod"; // or any Standard Schema library
import HomePage from "./pages/home";
import BlogPostPage from "./pages/blog-post";

// 1️⃣ Simple route - just a page
const homeRoute = createRoute(
  "/",
  () => ({
    PageComponent: HomePage,
    meta: () => [{ name: "title", content: "Home" }],
  }),
  undefined,
  { isStatic: true } // 🏷️ Optional: tag routes for filtering for SSG environments
);

// 2️⃣ Dynamic route - with params, validation, and data loading
const blogRoute = createRoute(
  "/blog/:slug", // :slug becomes available as params.slug
  ({ params, query }) => ({
    PageComponent: BlogPostPage,
    
    // 📦 Load data (can use AbortSignal, options, etc.)
    loader: async (signal?: AbortSignal) => {
      const res = await fetch(`/api/posts/${params.slug}`, { signal });
      return res.json();
    },
    
    // 📄 Generate meta tags (can use loader data)
    meta: (post) => [
      { name: "title", content: post.title },
      { name: "description", content: post.excerpt },
    ],
    
    // 🎨 Extra data for anything (breadcrumbs, layout, etc.)
    extra: () => ({
      breadcrumbs: ["Home", "Blog", params.slug],
      layout: "blog",
    }),
  }),
  {
    // ✅ Validate query parameters
    query: z.object({
      preview: z.boolean().optional(),
    }),
  },
  { isStatic: false, requiresAuth: false } // 🏷️ Route tags
);

// 3️⃣ Create router
const router = createRouter({
  home: homeRoute,
  blog: blogRoute,
});

// 4️⃣ Use the router in your app
async function handleRequest(url: string) {
  const route = router.getRoute(url);
  
  if (!route) {
    return <NotFoundPage />;
  }

  // Everything is typed! TypeScript knows the types of all params
  const data = route.loader ? await route.loader() : null;
  const metaTags = route.meta ? route.meta(data) : [];
  const extras = route.extra ? route.extra() : null;

  return (
    <route.PageComponent 
      params={route.params} 
      data={data} 
    />
  );
}

// 5️⃣ Filter routes without running handlers (great for SSG!)
const staticRoutes = Object.values(router.routes)
  .filter(route => route.meta?.isStatic);
```

## 申报路线(小锅炉板)

如果你不需要每条路线的定制关闭, `defineRoute` 财务报告和审定财务报表 `defineRoutes` 完全删除处理器接线 。 组件接收路由上下文( Q)`params`, (中文(简体) ), `query`作为道具,和 `loader`编号 :`meta`编号 :`extra` 这是他们的第一个论点:

```tsx
import { defineRoute, defineRoutes, createRouter } from "@btst/yar";

// Single route
const postRoute = defineRoute("/blog/:slug", {
  page: BlogPostPage, // rendered with { params, query } as props
  loading: Spinner,
  error: ErrorPage,
  loader: (ctx, signal?: AbortSignal) =>
    fetch(`/api/posts/${ctx.params.slug}`, { signal }).then((r) => r.json()),
  meta: (ctx, post) => [{ name: "title", content: post?.title ?? ctx.params.slug }],
  extra: (ctx) => ({ breadcrumbs: ["Home", "Blog", ctx.params.slug] }),
});

// Many routes at once, with optional page overrides
const routes = defineRoutes(
  {
    home: defineRoute("/", { page: HomePage }, undefined, { isStatic: true }),
    post: defineRoute("/blog/:slug", {
      page: BlogPostPage,
      loader: (ctx) => fetchPost(ctx.params.slug),
      meta: (ctx) => [{ name: "title", content: ctx.params.slug }],
    }),
  },
  { pages: { post: CustomPostPage } } // swap a page component per key
);

const router = createRouter(routes);
```

被覆盖的页面仍然收到路由上下文(`params`, (中文(简体) ), `query`作为道具. `defineRoutes` 也接受平面 `createRoute` 路径; 在这些互换中 `PageComponent` 现为.

`defineRoute` 返回正则路径,因此它可以自由编曲 `createRoute` 相同路径 `createRouter` 电话 使用 `createRoute` 当需要完全控制处理器关闭时; 使用 `defineRoute`编号 :`defineRoutes` 通常的申报案件.

## 你需要知道的东西

### `createRoute(path, handler, options?, routeMeta?)`

创建路径。 处理器返回 :

-   **`PageComponent`** - 您的反应组件
-   **`loader()`** - 装入数据(可以接受像 `AbortSignal`(中文(简体) )
-   **`meta()`** - 生成 SEO 标记(可以接受任何参数)
-   **`extra()`** - 你需要的任何额外数据(可接受任何参数)

4 参数 `routeMeta` 允许您标记过滤的路由( 例如 ), `{ isStatic: true }`) (中文(简体) ).

### `createRouter(routes)`

结合你的路线。 回返情况:

-   **`routes`** - 所有路线
-   **`getRoute(path, query?)`** - 匹配一个URL并获得路径

### 关键特性

**QQ 路径参数**

```tsx
"/blog/:slug" → params.slug is automatically typed
```

**QQ 查询验证**

```tsx
query: z.object({ sort: z.string() })
```

**XQ 路由标记**

```tsx
{ isStatic: true, requiresAuth: false }
// Filter without running handlers - perfect for finding static routes in SSG environments, or for filtering routes that require authentication.
```

**\* 弹性函数**

```tsx
loader: (signal) => fetch(url, { signal })
meta: (data) => [{ name: "title", content: data.title }]
extra: (userId) => ({ breadcrumbs: [...], userId })
```

在 SSR 环境中用于预选数据并生成元标记, 或者用于在您的路径中添加额外数据 .

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 许可证

麻省理工学院

## 常见问题

### @btst/yar 是什么？

用于现代反应框架的可插路由器

### 如何安装 @btst/yar？

在项目目录运行 npm install @btst/yar，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@types/react（^18\.0\.0 \|\| ^19\.0\.0）、@types/react-dom（^18\.0\.0 \|\| ^19\.0\.0）、react（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @btst/yar 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @btst/yar 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @btst/yar 可以商用吗？

@btst/yar 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @btst/yar 的下载量有多少？

根据 npm 官方下载统计，@btst/yar 在 2026/10/09 – 2026/11/07 这 30 天内被下载 4,537 次，日均约 151 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @btst/yar 还在维护吗？

最新版本 1\.3\.2 发布于 2026/08/23（2 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。