Refine v5 遷移指南從 refinedev/react-router-v6 平滑升級到 React Router v7【免費(fèi)下載鏈接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/refine本指南基于 documentation/docs/routing/integrations/react-router/migration-guide-v6-to-v7.md系統(tǒng)講解如何將基于refinedev/react-router-v6React Router v6的 Refine 項(xiàng)目遷移到refinedev/react-routerReact Router v7。你將掌握包替換、依賴更新、import 改寫的完整步驟以及如何借助官方refine-codemod一鍵完成自動遷移并深入了解新包在倉庫源碼層面的導(dǎo)出結(jié)構(gòu)與工作原理。遷移概覽這次升級到底改了什么對于使用 React Router 的 Refine 項(xiàng)目來說v6 → v7 的升級核心是一次包層面的重新組織而不是 API 的大規(guī)模重寫包名變更refinedev/react-router-v6更名為refinedev/react-router目的是與其他 Refine 集成包的命名保持一致避免混淆底層依賴變更React Router 官方在 v7 中將react-router-dom合并進(jìn)react-router因此項(xiàng)目中不再需要安裝react-router-dom所有組件統(tǒng)一從react-router導(dǎo)入Refine 自身無破壞性變更遷移指南明確指出除包名變化外Refine 并未引入其他 breaking changes因此遷移工作的重心是依賴替換與 import 更新。至于 React Router v7 自身的破壞性變化如 Data APIs、未來標(biāo)志等官方建議閱讀 React Router v7 的遷移文檔進(jìn)一步確認(rèn)。從當(dāng)前倉庫的實(shí)際狀態(tài)看新包 packages/react-router/package.json 的依賴為react-router: ^7.0.2peerDependencies 同樣要求react-router: ^7.0.2并且refinedev/core的 peer 版本為^5.0.0即新包面向 Refine v5 生態(tài)。第一步卸載舊包遷移的第一步是移除舊版相關(guān)的三個(gè)包。由于 v7 中react-router已合并了原react-router-dom的能力三者都需要從項(xiàng)目中卸載npm uninstall refinedev/react-router-v6 react-router-dom react-router若項(xiàng)目使用 pnpm 或 yarn將npm uninstall替換為對應(yīng)的pnpm remove或yarn remove即可原理一致。第二步安裝新包卸載完成后安裝新的集成包與 React Router v7。注意這里不再需要安裝react-router-dom所有 v7 組件RouterProvider、BrowserRouter、Routes、Route、Outlet、Link等均從react-router包導(dǎo)入npm install refinedev/react-router react-router安裝完成后package.json中的依賴變化對應(yīng)如下- refinedev/react-router-v6: ^4.6.0 refinedev/react-router: ^1.0.1 - react-router-dom: ^6.8.1 - react-router: ^6.8.1 react-router: ^7.0.2完成以上兩步后基礎(chǔ)遷移即告完成可以開始使用refinedev/react-router搭配react-routerv7 編寫路由。第三步更新 import 語句包替換后所有相關(guān) import 需要同步更新主要涉及兩類來源import routerProvider, { NavigateToResource, UnsavedChangesNotifier, DocumentTitleHandler } - from refinedev/react-router-v6; from refinedev/react-router; -import { RouterProvider } from react-router-dom; import { RouterProvider } from react-router;RouterProvider是典型的受影響示例v6 時(shí)代它從react-router-dom導(dǎo)出v7 中改從react-router導(dǎo)出。除此之外BrowserRouter、Routes、Route、Outlet、Link、Navigate、useNavigate、useLocation、useParams等組件與 hooks 的導(dǎo)入來源也都應(yīng)改為react-router。推薦方案用 refine-codemod 自動改寫 import手動逐個(gè)文件更新 import 容易遺漏官方推薦使用refine-codemod自動完成替換。該工具基于 jscodeshift 實(shí)現(xiàn)源碼級 AST 轉(zhuǎn)換可以精準(zhǔn)改寫所有命中的 import 聲明。使用前請確保 git 工作區(qū)干凈以便遷移不符合預(yù)期時(shí)可以回退。針對本次遷移需要依次執(zhí)行兩條 codemod# 將 refinedev/react-router-v6 改寫為 refinedev/react-router npx refinedev/codemodlatest refine-react-router-v6-to-refine-react-router # 將 react-router-dom 改寫為 react-router npx refinedev/codemodlatest react-router-dom-to-react-router從倉庫源碼可以確認(rèn)這兩條 codemod 的實(shí)際行為在 packages/codemod/src/index.ts 中注冊了對應(yīng)名稱其轉(zhuǎn)換邏輯分別位于 refine-react-router-v6-to-refine-react-router.ts 與 react-router-dom-to-react-router.tsrefine-react-router-v6-to-refine-react-router查找source為refinedev/react-router-v6的ImportDeclaration原樣保留 import specifiers僅將模塊名替換為refinedev/react-routerreact-router-dom-to-react-router查找source為react-router-dom的ImportDeclaration將模塊名替換為react-router?？梢妰蓷l codemod 都只做模塊來源的精準(zhǔn)替換不會改動你導(dǎo)入的具名符號遷移后代碼語義保持不變。遷移后的源碼級認(rèn)知refinedev/react-router 導(dǎo)出了什么遷移完成后新包在倉庫中的核心實(shí)現(xiàn)位于 packages/react-router/src/index.ts從中可以看到包的公開導(dǎo)出面這也是遷移后你在項(xiàng)目中可以繼續(xù)使用的全部能力export { routerProvider as default, stringifyConfig } from ./bindings.js; export { NavigateToResource } from ./navigate-to-resource.js; export { UnsavedChangesNotifier } from ./unsaved-changes-notifier.js; export { CatchAllNavigate } from ./catch-all-navigate.js; export { DocumentTitleHandler } from ./document-title-handler.js; export { useDocumentTitle } from ./use-document-title.js;routerProvider默認(rèn)導(dǎo)出傳給Refine routerProvider{routerProvider}的路由橋接層實(shí)現(xiàn)go、back、parse、Link四個(gè)核心能力。其實(shí)現(xiàn)位于 bindings.tsxgo基于useNavigate構(gòu)造目標(biāo) URL支持query、hash、keepQuery、keepHash等配置parse結(jié)合matchResourceFromRoute與qs解析出當(dāng)前resource、action、id與分頁參數(shù)Link直接轉(zhuǎn)發(fā)react-router的LinkNavigateToResource跳轉(zhuǎn)到指定資源的 list 頁面常用于應(yīng)用根路由UnsavedChangesNotifier配合options.warnWhenUnsavedChanges: true實(shí)現(xiàn)未保存更改的離開提醒含beforeunload場景CatchAllNavigate重定向到指定路徑并將當(dāng)前 location 以to查詢參數(shù)保留以便回跳實(shí)現(xiàn)見 catch-all-navigate.tsxDocumentTitleHandler與useDocumentTitle按資源與動作自動生成頁面標(biāo)題也支持自定義handler與 i18n 鍵。這些組件的具體用法含認(rèn)證路由、布局、Access Control、錯誤頁、根路由等場景可繼續(xù)參考 documentation/docs/routing/integrations/react-router/index.md。遷移后的基本用法驗(yàn)證完成遷移后一個(gè)最小可用形態(tài)如下演示BrowserRouter風(fēng)格均從react-router導(dǎo)入import { Refine } from refinedev/core; import dataProvider from refinedev/simple-rest; import routerProvider from refinedev/react-router; import { BrowserRouter, Routes, Route } from react-router; import { PostList, PostCreate } from pages/posts; const App () { return ( BrowserRouter Refine dataProvider{dataProvider} routerProvider{routerProvider} resources{[ { name: posts, list: /posts, create: /posts/create, }, ]} Routes Route pathposts Route index element{PostList /} / Route pathcreate element{PostCreate /} / /Route /Routes /Refine /BrowserRouter ); };若項(xiàng)目使用 React Router v7 的 Data APIscreateBrowserRouterRouterProvider同樣全部從react-router導(dǎo)入即可routerProvider的傳參方式不變。注意事項(xiàng)與后續(xù)動作React Router v7 自身的破壞性變更refinedev/react-router只負(fù)責(zé) Refine 與 React Router 的橋接不屏蔽 React Router v7 本身的變更如未來標(biāo)志、Data APIs 行為等遷移后建議按 React Router v7 遷移文檔核對項(xiàng)目中直接使用的路由 API版本對齊從倉庫的 package.json 可見新包要求 Node20、react ^18 || ^19、refinedev/core ^5.0.0請確保項(xiàng)目環(huán)境滿足這些約束codemod 的可回退性自動改寫是批量源碼修改執(zhí)行前務(wù)必確認(rèn) git 工作區(qū)干凈改完后先跑一遍類型檢查tsc --noEmit與構(gòu)建再提交組件與 hooks 不受影響NavigateToResource、UnsavedChangesNotifier、CatchAllNavigate、DocumentTitleHandler、useDocumentTitle的 API 均保持不變業(yè)務(wù)代碼中除 import 來源外無需額外改動。至此你的 Refine 項(xiàng)目已平滑完成從 React Router v6 到 v7 的遷移包名統(tǒng)一、依賴精簡、import 規(guī)整并且可以繼續(xù)享受 Refine 路由橋接層提供的全部能力?！久赓M(fèi)下載鏈接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/refine創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考