# @evjs/client 中文文档

规范地址：https://npmcn.com/package/%40evjs/client/

版本：0\.3\.31
npm 元数据更新时间：2026-11-16T08:10:08.928Z
中文译文更新时间：2026-11-16T08:15:43.840Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40evjs/client
原文对照：https://npmcn.com/package/%40evjs/client/?lang=original
项目主页：https://github.com/afx-team/evjs#readme
源码仓库：https://github.com/afx-team/evjs

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

- 包体积（解压后）：505 kB，162 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，react-server-dom-webpack ^19\.2\.5
- 首次发布：2026-03-23T19:21:40.877Z
- 最新版本发布：2026-11-16T08:10:08.480Z
- 近 30 天下载量：2757（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：100（近 12 个月 100 个）

## 中文简介

Evjs 框架的客户端运行时间

## 安装

```sh
npm install @evjs/client
```

也可以使用：`pnpm add @evjs/client`、`yarn add @evjs/client`、`bun add @evjs/client`

## README

# @evjs/客户端

> 浏览器运行时间核心,用于独立 CSR 应用程序和 **页:1** 框架.

## 特征

-   **页钩** —— 说 `usePageParams()`, (中文(简体) ), `usePageSearch()`,以及 `usePageLoaderData()` 披露框架管理的路由数据,而evjs拥有路由可实现性.
-   **独立的公司社会责任** —— 说 `createApp()`, (中文(简体) ), `createAppRootRoute()`,而 TanStack 路由器则支持手动浏览器专用应用程序 `@evjs/ev`。 。 。 .
-   **SPA 导航** ——SPA Pages使用evjs页钩和导航帮助器,而框架则拥有路由树和app靴子.
-   **路由器自由页面** ——MPA和框架管理页面使用页面运行时间而不添加客户端路由器.
-   **数据获取** - 包装 [TanStack 查询](https://tanstack.com/query) 有内置服务器功能代理.
-   **服务器函数支持** —— 说 `useQuery(fn)` 财务报告和审定财务报表 `useMutation(fn)` 用于输入服务器边界的呼叫.
-   **焦点客户端 API** ——独立/手动客户端代码从中导入运输,页钩,导航助手,和RSC助手 `@evjs/client`; 文件惯例应用程序源通过 `@evjs/ev/route`, (中文(简体) ), `@evjs/ev/navigation`, (中文(简体) ), `@evjs/ev/query`,以及 `@evjs/ev/transport`; 生成的框架拖网用途 `@evjs/client/internal`。 。 。 .

## 安装

```bash
npm install @evjs/client react react-dom
```

## 快速启动

### 独立的公司社会责任

使用 `@evjs/client` 当一个仅浏览器的应用程序拥有其路由和构建时 管道:

```tsx
import {
  createApp,
  createAppRootRoute,
  createRoute,
  Link,
  Outlet,
} from "@evjs/client";

const rootRoute = createAppRootRoute({
  component: () => (
    <main>
      <Link to="/">Home</Link>
      <Outlet />
    </main>
  ),
});

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/",
  component: () => <h1>Home</h1>,
});

const app = createApp({
  routeTree: rootRoute.addChildren([indexRoute]),
});

declare module "@evjs/client" {
  interface Register {
    router: typeof app.router;
  }
}

app.render("#app");
```

外部反应主机可以拥有根而无需创建隐藏或嵌入 DOM 树根。 组件模式返回相同的路由器、查询客户端和应用程序 使用的包装 `render()`数字 :

```tsx
const application = app.createComponent({ signal: mountController.signal });

hostRoot.render(application.element);

// Stop rendering application.element first, then release the ownership token.
application.dispose();
```

可能只有一个渲染所有者在活动 。 打电话 `app.unmount()` 切换前 从 DOM 根模式到组件模式,或 `dispose()` 切换到 `app.render()`。 。 。 .

使用 `@evjs/ev` 仅在应用程序需要诸如 Page 等框架构成时 路由、服务器功能转换、清单、SRS、PR、RSC或部署 文物.

### 框架管理页面

```tsx
// src/pages/users/$userId/page.tsx
import { usePageParams } from "@evjs/ev/route";

export default function UserPage() {
  const { userId } = usePageParams();
  return <h1>User {userId}</h1>;
}
```

`usePageParams()` 具有Page-scoped并跨越SPA、MPA和RSC渲染. 在 SPA 中, root 和路由布局 `useRouteParams()` 读取合并 活动路由分支的参数。 本地主机和浏览器 API 可以解析 应用路径,包括 `routing.basepath`,与 `useHref()` 或者说 `useHrefResolver()` 从 `@evjs/ev/navigation`。 。 。 .

在SPA和MPA输出中都使用页面钩来获取路由数据. 他们就是 页面代码零注释路径; `params`, (中文(简体) ), `search`,以及 `loaderData` 为: 未作为页面组件道具通过.

### 让 evjs 构建应用程序

框架管理的应用程序使用一个Page-and-Route公约。 A 类 `page.*` 模块是正 Page/ Route 锁定;其包含的目录拥有私有 源并确定 URL :

```ts
// ev.config.ts
import { defineConfig } from "@evjs/ev";

export default defineConfig({
  routing: {
    mode: "spa",
  },
});
```

Page 目录可能包含组件、钩子、模型和服务,而不包含 私人文件名前缀; 这些文件永远不会成为路径 。 仅更改 `routing.mode` 实现与MPA相同的语义page/Route树. SPA和MPA应用程序构成相同的文件-公约布局. MPA 拒绝 仅限路由器的生命周期和边界面.

明确 `application.routes` 财务报告和审定财务报表 `component`编号 :`routes` 配置只为 SPA 路由树输入 `@evjs/ev`;它们的转换器将变为相同的 页面合同,拒绝实现精神创伤和痛苦,不定义 额外 `@evjs/client` APIs (英语). 文件公约应用程序的使用 `page.tsx` 页面配置 `page.config.ts`选择 仅限 `routing.mode`。 。 。 .

## 服务器函数

使用 `"use server"` 在可达到模块中的指示; `.server.ts` 这是 建议的命名惯例,而不是发现规则。 在档案公约应用, 导入路由数据钩 `@evjs/ev/route` 和查询钩 `@evjs/ev/query`数字 :

```tsx
// src/pages/posts/page.tsx
import { useQuery } from "@evjs/ev/query";
import { getPosts } from "../../apis/posts.server";

function Posts() {
  const { data } = useQuery(getPosts);
  return <ul>{data?.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}
```

独立/手工客户端可直接从中导入相同的查询钩 `@evjs/client` 当他们拥有运行时间整合.

## API 密码

### 路线

-   `usePageParams`: 从页面组件读取框架管理的参数.
-   `useRouteParams`:在root和路由布局中从活跃的SPA路由分支读取合并的参数.
-   `usePageSearch` 财务报告和审定财务报表 `usePageLoaderData`: 从页面组件读取框架管理的路由数据.
-   `Link`, (中文(简体) ), `Navigate`, (中文(简体) ), `useNavigate`,以及 `redirect`: 页面组件和路由生命周期导出的导航帮助器.
-   `useHref` 财务报告和审定财务报表 `useHrefResolver`: 为本地主播和浏览器API解决与公共浏览器hrefs的应用程序相适应的路径.

### 查询

-   `useQuery(fn, ...args)` 财务报告和审定财务报表 `useSuspenseQuery(fn, ...args)`: 调用编译器生成的服务器函数有推断的参数和结果类型.
-   `useMutation(fn, options?)`: 通过编译器生成的服务器函数 stub 进行突变;通过 `mutationFn` 仅当使用标准的 TanStack 对象形式时.
-   `getFnQueryKey(fn, ...args)`: 为服务器函数生成稳定的查询密钥.
-   `getFnQueryOptions(fn, ...args)`: 生成手动选项 `queryClient` 用途.
-   Plain async 函数不是服务器函数根. 使用 `useQuery({ queryKey, queryFn })` 或者说 `useMutation({ mutationFn })` 非服务器函数.

### 运输

-   `initTransport({ baseUrl, credentials, headers, functions })`:配置默认的HTTP适配器. `functions.endpoint` 可以为独立的运行时间覆盖服务器功能路径.
-   `credentials` 编号 : `headers`: 支持的 HTTP 默认值; 获取 `mode` 故意无法配置.
-   主机运行时间可以设置 `window.__EVJS_TRANSPORT__` 在框架服务器之前 请求运行。 该值只接受数据 `RuntimeTransportOptions`数字 : `baseUrl`, (中文(简体) ), `credentials`,以及 `headers`。终点路径继续来自 框架运行时间元数据; 应用程序 `initTransport()` 电话还接 服务器功能的优先级 .
-   运行时传输是针对 evjs 服务器的架构管理浏览器请求 结束点。 它被服务器功能和RSC飞行所消耗. 它不控制运行时间元数据加载,静态资产,动态导入, 或申请授权 `fetch()` 打电话.
-   `@evjs/client/transport`: 低等运输API的公共子路径,例如 `createServerReference`, (中文(简体) ), `getFnId`, (中文(简体) ), `getFnName`,以及 `initTransport`。 。 。 .
-   默认的 HTTP 适配器期望服务器功能响应成功使用 `Content-Type: application/json`非 JSON 错误反应使用其修剪 文本正文为 `ServerFunctionError`后退为 `statusText` 当 身体为空或只有白空间.
-   `initTransport({ adapter })`: 以自定义适配器取代运输行为.
-   生成服务器函数根 `@evjs/client/internal/server-functions`· ; 应用代码应当持续使用上方的公共交通API.

### 运行时间

-   页面运行时拖带为框架所有并导入 `@evjs/client/internal`。 。 。 .
-   页面运行时间加载嵌入 `__EVJS_CLIENT_RUNTIME__` 先说 独立 运行时间可以明确使用 `runtimeUrl` 或者说 `data-evjs-runtime`;没有 默认运行时间元数据 URL. 外部反应必须是成功的 JSON 与 `Content-Type: application/json`,允许可选的内容类型 参数.
-   `fetchRscFlight()`, (中文(简体) ), `createReactRscModel()`, (中文(简体) ), `mountReactRscPage()`, (中文(简体) ), `unmountReactRscPage()`,以及 `startReactRscPageRuntime()`: RSC 页面运行时间 协助框架拥有的飞行和流动.
-   RSC 页面模型需要成功的飞行响应才能使用 `Content-Type: text/x-component` 带有可选参数.
-   运行时外壳原始物, 如 `createShell()`, (中文(简体) ), `createPageDriver()`,以及 `createHistoryDriver()` 由框架拥有并通过 `@evjs/client/internal`。 。 。 .
-   Shell 激活请求 URL 必须是 HTTP( S) URL 或路径名, 以 `/`。 。 。 .
-   生成的组件页靴陷阱 API 也属于框架所有并通过 `@evjs/client/internal`。 。 。 .

应用程序客户端运行时间 API 导出自 `@evjs/client`。 。 。 . 普通 TanStack 查询不与 evjs 服务器功能对齐的 API 应该来自 `@tanstack/react-query`使用独立/手工客户 `@evjs/client` 用于 evjs 页面、导航、服务器功能和RSC API; 普通 file-convention app source 导入公共作者表面 `@evjs/ev/route`, (中文(简体) ), `@evjs/ev/navigation`, (中文(简体) ), `@evjs/ev/query`,以及 `@evjs/ev/transport`。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @evjs/client 是什么？

Evjs 框架的客户端运行时间

### 如何安装 @evjs/client？

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

### @evjs/client 支持 TypeScript 吗？

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

### @evjs/client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @evjs/client 可以商用吗？

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

### @evjs/client 的下载量有多少？

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

### @evjs/client 还在维护吗？

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

