前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载本篇指南围绕 Relay Classic 时代的核心概念Routes路由展开Relay 的路由负责声明一个应用的查询入口query roots是连接 GraphQL 根查询与可复用片段fragments的桥梁。读完本文你将掌握查询与片段的本质区别、如何用对象字面量与Relay.Route定义可复用的路由、如何通过Relay.RootContainer将路由与容器组合成完整数据请求以及这一机制在现代 Relay 中如何演化为 EntryPoint 体系。为什么需要 Routes先理解 Queries 与 Fragments 的本质区别要理解 Relay 为什么需要路由必须先厘清 GraphQL 中**查询queries与片段fragments**这两种声明方式的差异——这是 Classic-Guides-Routes.md 全篇的逻辑起点。Queries声明根查询类型上的字段在 GraphQL 中query声明的是存在于根查询类型root query type上的字段。例如下面的查询会获取id为123的用户名称query UserQuery { user(id: 123) { name, }, }查询锚定在根类型上天然带有入口属性一条查询就是一次从应用顶部发起的完整数据请求。Fragments声明任意类型上的字段与之相对GraphQLfragment声明的是任意类型上的一组字段。例如下面的片段为某个User获取头像 URIfragment UserProfilePhoto on User { profilePhoto(size: $size) { uri, }, }片段不关心自己被用在哪棵数据树上因此它可以被嵌入到其他片段或查询之中。上面的片段既可用于获取用户123的头像query UserQuery { user(id: 123) { ...UserProfilePhoto, }, }也可以用于批量获取用户123所有好友的头像query UserQuery { user(id: 123) { friends(first: 10) { edges { node { ...UserProfilePhoto, }, }, }, }, }为什么容器要声明片段而非查询Relay 容器Container声明的是片段而非查询这使它们可以被轻易嵌入到多个上下文中。正如 Classic-Guides-Containers.md 所述容器是描述数据需求规格的高阶组件——Relay.createContainer(Component, { fragments: {...} })接收一个 React 组件并返回一个能够自动获取数据的新组件。因为片段与具体入口解耦同一个容器可以出现在列表页、详情页、弹窗等不同位置这与 React 组件天然可复用、可组合的特性完全一致。维度QueryFragment锚定位置根查询类型任意类型是否可嵌入可作为片段宿主可嵌入其他片段/查询复用粒度一次请求一个入口跨上下文任意复用在 Relay 中的角色由 Route 声明由 Container 声明定义路由对象字面量与 Relay.Route 子类路由Route是定义了根查询集合与输入参数的对象。Relay 需要知道从哪个根查询出发才能把容器声明的片段组装成一次完整的 GraphQL 请求路由正是承担这一职责的入口声明。对象字面量最简单的路由这里是一个用于渲染用户123个人资料页的简单路由var profileRoute { queries: { // Routes declare queries using functions that return a query root. Relay // will automatically compose the user fragment from the Relay container // paired with this route on a Relay.RootContainer user: () Relay.QL # In Relay, the GraphQL query name can be optionally omitted. query { user(id: $userID) } , }, params: { // This userID parameter will populate the $userID variable above. userID: 123, }, // Routes must also define a string name. name: ProfileRoute, };三个关键点queries以函数返回Relay.QL查询根的形式声明。函数形式是刻意的——它允许变量在实例化时才被注入而不是在模块加载时固定。params提供查询所需的变量值这里的userID: 123会填充查询模板里的$userID变量。name路由必须定义一个字符串名称用于调试与标识。子类化 Relay.Route参数化复用对象字面量只能服务固定参数。要为任意用户创建路由实例可以子类化Relay.Route抽象类它使定义一组查询与必需参数并可多次复用变得容易class ProfileRoute extends Relay.Route { static queries { user: () Relay.QL query { user(id: $userID) } , }; static paramDefinitions { // By setting required to true, ProfileRoute will throw if a userID // is not supplied when instantiated. userID: {required: true}, }; static routeName ProfileRoute; }现在可以实例化一个获取用户123数据的ProfileRoute// Equivalent to the object literal we created above. var profileRoute new ProfileRoute({userID: 123});并且可以针对任意用户 ID 创建路由。例如在监听popstate事件、从 URI 读取userID查询参数后构造路由并渲染window.addEventListener(popstate, () { var userID getQueryParamFromURI(userID, document.location.href); var profileRoute new ProfileRoute({userID: userID}); ReactDOM.render( Relay.RootContainer Component{UserProfile} route{profileRoute} /, document.getElementById(app) ); });这段代码也体现了原文档的一个重要澄清Relay 路由并不实现任何 URL 路由逻辑也不与 History API 协作。作者在文档中直言未来可能将RelayRoute改名为类似RelayQueryRoots或RelayQueryConfig的名字。URL 的解析、监听与切换应交给专门的 router 库完成Relay 路由只关心这次渲染需要从哪些查询根取数。这里Component{UserProfile}与route{profileRoute}的配对即是在Relay.RootContainer上进行的详见下文。Relay.Route 完整 API 参考Classic-APIReference-Route.md 对Relay.Route给出了完整定义。路由类共包含 4 个静态属性与 1 个构造方法。static paramDefinitionsstatic paramDefinitions: {[param: string]: {required: boolean}}路由可以声明一组必须在构造时提供的参数名同时这也是记录合法参数集合的好地方。若在实例化时缺少标为required: true的参数会直接抛错class ProfileRoute extends Relay.Route { static paramDefinitions { userID: {required: true}, }; // ... }static prepareParamsstatic prepareParams: ?(prevParams: {[prevParam: string]: mixed}) {[param: string]: mixed};prepareParams用于提供默认参数或对传入参数进行透传、转换与抑制。它是路由可复用性的进阶手段——例如把业务 ID 转换为全局 IDtoGlobalId、或为查询注入默认的limit变量class ProfileRoute extends Relay.Route { static queries { viewer: () Relay.QLquery { viewer } }; static prepareParams (prevParams) { return { // Pass base set of supplied params through: ...prevParams, // Transform a param to meet internal requirements: id: toGlobalId(Profile, prevParams.id), // Provide a starting limit variable: limit: 10, } } // ... }static queriesstatic queries: { [queryName: string]: () Relay.QLquery { ... } };路由必须用Relay.QL声明一组查询根。这些查询会在Relay.RootContainer上自动组合同名容器片段即路由queries.user会自动与容器的user片段合并成完整请求class ProfileRoute extends Relay.Route { static queries { user: () Relay.QLquery { user(id: $userID) }, }; // ... }在这个例子中路由需要用userID初始化该值会被传入查询。$userID变量会自动下传给顶层容器并在需要时被使用同时顶层 Relay 容器应有一个包含所需字段的user片段。static routeNamestatic routeName: string路由必须定义一个字符串名称。该名称用于标识请求、调试与日志是路由的身份。constructor(initialParams)使用new关键字创建路由实例可传入初始参数var profileRoute new ProfileRoute({userID: 123});若paramDefinitions中声明了必填参数而构造时未提供构造过程会抛错prepareParams会在参数进入查询之前被应用。用 Relay.RootContainer 组装查询并渲染路由解决了声明查询根的问题容器解决了组件声明片段的问题。要把二者组合成一条可发送给服务器的完整 GraphQL 查询需要 Classic-Guides-RootContainer.md 中的Relay.RootContainer。组件与路由的配对Relay.RootContainer是一个 React 组件给定Component与route它会尽力满足渲染该组件实例所需的数据ReactDOM.render( Relay.RootContainer Component{ProfilePicture} route{profileRoute} /, container );渲染时Relay 会构造查询并发送给 GraphQL 服务器当所有必需数据获取完成后ProfilePicture才会被渲染其携带片段的 props 中包含来自服务器的数据。若Component或route任一发生变化Relay.RootContainer会立即开始满足新的数据需求——这正是路由作为入口在运行时层面的体现切换路由即切换入口与数据需求。渲染回调renderLoading / renderFetched / renderFailureRelay.RootContainer接受三个可选回调 props用于精细控制渲染行为。renderLoading每当无法立即满足渲染所需数据时通常发生在首次渲染或Component/route变化时触发。默认情况下首次加载时什么都不渲染若此前已渲染过一组Component/route默认行为是继续渲染旧视图。提供renderLoading可覆盖Relay.RootContainer Component{ProfilePicture} route{profileRoute} renderLoading{function() { return divLoading.../div; }} /注意语义细节renderLoading返回undefined等价于默认行为继续展示旧视图返回null则无论是否有旧视图都渲染空。renderFetched当渲染所需数据全部可用时触发。回调总是带一个data参数它是从propName到查询数据的映射通常配合 JSX 展开属性使用Relay.RootContainer Component{ProfilePicture} route{profileRoute} renderFetched{function(data) { return ( ScrollView ProfilePicture {...data} / /ScrollView ); }} /文档特别提醒尽管可以访问data对象但它刻意保持不透明防止renderFetched对Component声明的片段产生隐式依赖。renderFailure当发生阻止数据获取的错误时触发默认不渲染任何内容。回调接收errorError 对象与retry重试函数两个参数若错误来自服务器响应响应负载可通过error.source检查Relay.RootContainer Component{ProfilePicture} route{profileRoute} renderFailure{function(error, retry) { return ( div p{error.message}/p pbutton onClick{retry}Retry?/button/p /div ); }} /强制取数forceFetch与 Relay 大多数 API 一致Relay.RootContainer会先尝试从客户端 store 解析数据失败才发服务器请求。若希望即使客户端已有数据也强制请求服务器可使用forceFetch布尔 propRelay.RootContainer Component{ProfilePicture} route{profileRoute} forceFetch{true} /forceFetch为 true 时只要渲染所需数据在客户端可用renderFetched仍可能在服务器请求完成前被调用此时回调会收到第二个参数readyState其stale属性为 true 表示数据来自客户端缓存、服务器刷新尚未完成Relay.RootContainer Component{ProfilePicture} route{profileRoute} forceFetch{true} renderFetched{function(data, readyState) { var isRefreshing readyState.stale; return ( ScrollView Spinner style{{display: isRefreshing ? block : none }} ProfilePicture {...data} / /ScrollView ); }} /这为后台刷新 即时展示缓存的交互提供了标准范式。就绪状态onReadyStateChangeRelay.RootContainer还支持onReadyStateChangeprop用于在满足数据需求的过程中接收细粒度事件。该回调会被调用一次或多次每次传入描述当前就绪状态的对象属性包括ready: boolean—— 渲染所需的数据子集是否就绪done: boolean—— 所有数据需求是否全部就绪error: ?Error—— 失败时为Error实例否则为nullevents: ArrayReadyStateEvent—— 截至目前收到的事件数组stale: boolean—— 强制取数时若ready因客户端缓存数据为 true 而服务器请求未完成则为 trueaborted: boolean—— 请求是否被中止ReadyStateEvent枚举包括ABORT、CACHE_RESTORED_REQUIRED、CACHE_RESTORE_FAILED、CACHE_RESTORE_START、NETWORK_QUERY_ERROR、NETWORK_QUERY_RECEIVED_ALL、NETWORK_QUERY_RECEIVED_REQUIRED、NETWORK_QUERY_START、STORE_FOUND_ALL、STORE_FOUND_REQUIRED。结合 Classic-Guides-ReadyState.md可以推演典型调用序列服务器取数客户端数据不足触发请求时先调用一次ready: false再调用一次ready与done均为 true。客户端命中客户端数据充足、无需请求时只调用一次ready与done均为 true。服务器错误先调用一次ready: false再调用一次带error的回调且ready/done持续为 false。强制取数且客户端可渲染先调用一次ready、done、stale均为 true再调用一次ready、done为 true 而stale为 false。这些时序契约让开发者可以精确记录数据就绪耗时、上报错误或实现加载态切换。Relay.QL路由查询的语法基础路由中的查询根都以Relay.QL标签模板声明因此理解其编译机制是掌握路由的底层前提。Classic-APIReference-QL.md 指出Relay 的片段、变更与查询必须使用以Relay.QL标记的 ES6 模板字符串指定例如var fragment Relay.QL fragment on User { name } ;由于 GraphQL schema 体积过大、不宜打包进应用这些Relay.QL模板表达式需要被转译为 JavaScript 描述——这一工作由babel-plugin-relay在编译期完成当前仓库中的实现见 packages/babel-plugin-relay/BabelPluginRelay.js。转译后的 schema 信息让 Relay 能理解字段参数类型、哪些字段是连接connection或列表、以及如何高效地重新获取refetch服务器记录。Relay.QL对象被四类 API 使用构成完整的数据声明体系API形态用途Relay.Container() Relay.QL\fragment on ...声明容器数据依赖片段Relay.Route() Relay.QL\query ...声明路由查询根Relay.MutationRelay.QL\mutation { fieldName }声明变更字段可复用片段var fragment Relay.QL\fragment on ...;在上述场景中组合复用路由查询中的$userID变量正是通过params/构造参数与prepareParams注入的变量会在编译期由 babel-plugin 校验与登记运行期由 Relay 组合进最终请求。从 Classic Routes 到现代 Relay同一思想的演进需要说明的是当前仓库的packages目录下已不再包含 Classic 时代的Relay.Route运行时实现——本指南所述的 API 以 website/versioned_docs/version-classic 下的版本化文档为准。但这套入口root与片段fragment分离、由运行时组合请求的设计思想一直延续至今只是入口的载体发生了演化Classic 时代入口 Relay.RouteRelay.RootContainer通过new ProfileRoute({userID})与Componentprop 配对完成数据满足。现代 Relay入口演化为EntryPoint 体系见 website/versioned_docs/version-v21.0.1/api-reference/entrypoint-apis/entrypoint-container.mdx配合QueryRenderer及 hooks 形态的useLazyLoadQuery源码见 packages/react-relay/relay-hooks/useLazyLoadQuery.js、loadQuerypackages/react-relay/relay-hooks/loadQuery.js与useEntryPointLoader等 API。现代查询同样以声明 root query 变量为入口只是换成了graphql标签与预加载preload模型。编译管线Classic 依赖 Babel 插件转译Relay.QL现代版本则可在编译期借助仓库中的 Rust 编译器compiler/crates/relay-compiler与babel-plugin-relaypackages/babel-plugin-relay生成持久化的请求元数据。理解 Classic 的 Routes等于理解了 Relay 数据声明的最小完备单元查询根负责入口、片段负责复用、参数负责实例化、RootContainer 负责组装与满足。这套心智模型在阅读现代 EntryPoint 与useLazyLoadQuery文档时依然直接适用。小结查询 vs 片段查询锚定根类型、一次一入口片段锚定任意类型、可任意嵌入复用容器因此获得与 React 组件一致的可组合性。路由的定义可用对象字面量queriesparamsname快速声明也可子类化Relay.RoutequeriesparamDefinitionsprepareParamsrouteName 构造器获得参数化复用与必填校验。路由的使用与容器配对交给Relay.RootContainer由它组装查询、满足数据并通过renderLoading/renderFetched/renderFailure/forceFetch/onReadyStateChange控制渲染与生命周期。底层机制所有查询与片段经Relay.QL声明、由 babel-plugin-relay 在编译期转译prepareParams与变量注入是参数从 URL/实例到 GraphQL 变量的完整通道。进一步阅读路由 API 细节见 Classic-APIReference-Route.md容器与片段组合见 Classic-Guides-Containers.mdRootContainer 渲染控制与就绪状态见 Classic-Guides-RootContainer.md 与 Classic-Guides-ReadyState.md。赞分享前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载相关推荐Vue Router 命名路由Named Routes完全指南定义、链接与底层实现Vue Router 命名路由Named Routes完全指南定义、链接与底层实现 命名路由Named Routes是 Vue Router 为每条路前端路由gpt-oss-20b-WFP8-AFP8-KVFP8量化参数详解权重、激活和KV缓存配置gpt oss 20b WFP8 AFP8 KVFP8量化参数详解权重、激活和KV缓存配置 gpt oss 20b WFP8 AFP8 KVFP8是一个经过全前端路由Angular 路由定义完全指南从 Routes 数组到嵌套视图的配置详解Angular 路由定义完全指南从 Routes 数组到嵌套视图的配置详解 导读 本文以 Angular 官方仓库中的 Define Routes 开发技能文前端Web框架上一篇Manta发票应用终极部署指南三大平台打包发布完整流程下一篇GHelper免费开源的华硕笔记本硬件控制完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考