@evjs/client

中文文档
0.3.31发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 2757

Evjs 框架的客户端运行时间

中文使用文档
文档目录13 节
  1. 特征
  2. 安装
  3. 快速启动
  4. 独立的公司社会责任
  5. 框架管理页面
  6. 让 evjs 构建应用程序
  7. 服务器函数
  8. API 密码
  9. 路线
  10. 查询
  11. 运输
  12. 运行时间
  13. 许可证

@evjs/客户端

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

特征

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

安装

npm install @evjs/client react react-dom

快速启动

独立的公司社会责任

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

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()数字 :

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或部署 文物.

框架管理页面

// 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 :

// 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数字 :

// 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 共发布 100 个版本,首次发布于 2026/03/24;过去 12 个月发布了 100 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.3.31latest2026/11/16今天
0.3.302026/11/141 天前
0.3.30-alpha.1alpha2026/11/123 天前
0.3.30-alpha.02026/11/114 天前
0.2.18legacy2026/11/0214 天前
0.3.292026/11/0115 天前

关于 @evjs/client 的常见问题

@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 和提交记录判断。