前端UI組件【免費下載鏈接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design項目地址https://gitcode.com/gh_mirrors/re/react-admin點擊查看免費下載本指南系統(tǒng)講解 react-admin 生態(tài)中ra-realtime包對dataProvider的實時化擴展要求從subscribe/unsubscribe/publish與鎖相關(guān)方法的簽名約定到 Supabase、API Platform、Mercure 三種開箱即用的內(nèi)置適配器再到手寫自定義適配器的完整示例與 Topic / Event / Lock 數(shù)據(jù)格式規(guī)范。讀完本文你將能夠為任意實時后端WebSocket、長輪詢、GraphQL Subscription 等編寫自己的實時適配器并讓ListLiveUpdate、EditLive、ShowLive等實時組件正常工作。ra-realtime是 react-admin 實時協(xié)作能力的核心運行時庫它采用與 CRUD 方法完全一致的adapter適配器思路實時能力并非硬編碼進(jìn) UI而是通過擴展dataProvider的方法實現(xiàn)來接入任意實時基礎(chǔ)設(shè)施。本文對應(yīng)的完整概念與配套組件概覽見 Realtime 總覽文檔其中涉及的ListLiveUpdate、EditLive、ShowLive組件及useGetListLive、useGetOneLive等 Hook 的用法可參閱對應(yīng)文檔頁。一、實時方法及其簽名約定要讓 react-admin 的實時組件正常工作你的dataProvider必須額外實現(xiàn)三個新方法subscribe(topic, callback)—— 訂閱指定 topic當(dāng)該 topic 上有事件發(fā)布時回調(diào)callbackunsubscribe(topic, callback)—— 取消訂閱參數(shù)必須與subscribe時完全一致同一函數(shù)引用publish(topic, event)—— 向指定 topic 發(fā)布事件可選因為在多數(shù)架構(gòu)中發(fā)布動作發(fā)生在服務(wù)端。這三個方法應(yīng)當(dāng)返回一個已 resolve 的空 Promise表示該動作已被實時總線確認(rèn)接收。此外若要支持 react-admin 的記錄鎖lock功能防止多人并發(fā)編輯同一記錄dataProvider還需額外實現(xiàn) 4 個方法lock(resource, { id, identity, meta })unlock(resource, { id, identity, meta })getLock(resource, { id, meta })getLocks(resource, { meta })從源碼層面看這一擴展機制是完全開放的在 packages/ra-core/src/types.ts 中react-admin 的DataProvider類型是一個對象類型除getList、getOne、getMany、update、create、delete等標(biāo)準(zhǔn) CRUD 方法外還聲明了[key: string]: any索引簽名。這意味著subscribe、publish、lock等任意自定義方法都可以合法地掛載在dataProvider上并被 react-admin 的應(yīng)用層正常調(diào)用。而 useDataProvider 會從DataProviderContext中取出你傳入Admin dataProvider{...}的實例因此只要把增強后的實時dataProvider傳給Admin任何組件都能通過useDataProvider()訪問這些實時方法。二、內(nèi)置適配器Supabasera-realtime內(nèi)置了基于 Supabase Realtime 能力的增強函數(shù)addRealTimeMethodsBasedOnSupabase。該適配器訂閱 Supabase 的Postgres Changes事件并將其轉(zhuǎn)換為ra-realtime期望的事件格式。你只需把原有的supabaseDataProvider來自ra-supabase和supabaseClient來自supabase/supabase-js傳入即可import { createClient } from supabase/supabase-js; import { supabaseDataProvider } from ra-supabase; import { addRealTimeMethodsBasedOnSupabase, ListLiveUpdate } from react-admin/ra-realtime; import { Admin, Resource, DataTable, List, EmailField } from react-admin; const supabaseClient createClient( process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY ); const dataProvider supabaseDataProvider({ instanceUrl: process.env.SUPABASE_URL, apiKey: process.env.SUPABASE_ANON_KEY, supabaseClient }); const realTimeDataProvider addRealTimeMethodsBasedOnSupabase({ dataProvider, supabaseClient, }); export const App () ( Admin dataProvider{realTimeDataProvider} Resource namesales list{SaleList} / /Admin ); const SaleList () ( List DataTable DataTable.Col sourceid / DataTable.Col sourcefirst_name / DataTable.Col sourcelast_name / DataTable.Col sourceemail field{EmailField} / /DataTable ListLiveUpdate / /List );示例中的ListLiveUpdate是實時列表刷新組件當(dāng)其他用戶新增、更新或刪除記錄時當(dāng)前列表會自動刷新。注意Supabase 默認(rèn)不啟用實時功能需要手動開啟。有兩種方式在 Supabase Dashboard 的Replication復(fù)制頁面勾選需要同步的表用SQL Editor執(zhí)行如下 SQL創(chuàng)建并維護(hù)supabase_realtimepublicationbegin; -- remove the supabase_realtime publication drop publication if exists supabase_realtime; -- re-create the supabase_realtime publication with no tables create publication supabase_realtime; commit; -- add a table to the publication alter publication supabase_realtime add table sales; alter publication supabase_realtime add table contacts; alter publication supabase_realtime add table contactNotes;addRealTimeMethodsBasedOnSupabase接受以下參數(shù)PropRequiredTypeDefaultDescriptiondataProviderRequiredDataProvider-要被增強為實時方法的基礎(chǔ) dataProvidersupabaseClientRequiredSupabaseClient-Supabase JS 客戶端實例自定義 JWT Token 的提示如果你希望自行簽發(fā) token 以在 RLS 策略中校驗自定義 claim那么使用addRealTimeMethodsBasedOnSupabase時必須在創(chuàng)建supabaseClient時同時為 Realtime 的headers和params傳入apikey字段。具體做法請參考 Supabase 官方文檔中關(guān)于自定義 tokencustom tokens的說明。三、內(nèi)置適配器API PlatformAPI Platform 場景下ra-realtime提供addRealTimeMethodsBasedOnApiPlatform函數(shù)它基于 API Platform 的Mercure Hub實現(xiàn)實時能力。該函數(shù)需要三個附加參數(shù)Mercure Hub 的 URL、用于向 Hub 鑒權(quán)的 JWT token、以及 API Platform 使用的 topic 基礎(chǔ) URL末尾不要帶斜杠import { DataTable, EditButton, List, ListProps } from react-admin; import { HydraAdmin, ResourceGuesser, FieldGuesser, hydraDataProvider, } from api-platform/admin; import { ListLiveUpdate, addRealTimeMethodsBasedOnApiPlatform, } from react-admin/ra-realtime; const dataProvider hydraDataProvider(https://localhost:8443); const dataProviderWithRealtime addRealTimeMethodsBasedOnApiPlatform( // 原始 dataProvider由 API Platform 提供的 hydra data provider dataProvider, // API Platform 的 Mercure Hub URL https://localhost:1337/.well-known/mercure, // 用于向 API Platform Mercure Hub 鑒權(quán)的 JWT token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM, // API Platform 使用的 topic URL末尾不帶斜杠 https://localhost:8443 ); const App () ( HydraAdmin entrypointhttps://localhost:8443 dataProvider{dataProviderWithRealtime} ResourceGuesser namegreetings list{GreetingsList} / /HydraAdmin ); // 連接 greetings 列表的示例 const GreetingsList () ( List DataTable DataTable.Col sourcename field{FieldGuesser} / DataTable.Col EditButton / /DataTable.Col /DataTable ListLiveUpdate / /List );注意示例中的 JWT 是一個演示用 token實際項目中應(yīng)通過后端簽發(fā)并動態(tài)獲取切勿硬編碼在客戶端代碼中。四、內(nèi)置適配器Mercure如果你的后端走的是通用 Mercure hub不依賴 API Platform可以使用addRealTimeMethodsBasedOnMercure。它接受原始dataProvider、Mercure hub 的 URL、以及 JWT token 三個參數(shù)import { addRealTimeMethodsBasedOnMercure } from react-admin/ra-realtime; const dataProviderWithRealtime addRealTimeMethodsBasedOnMercure( // 原始 dataProvider dataProvider, // Mercure hub URL http://path.to.my.api/.well-known/mercure, // 用于向 Mercure Hub 鑒權(quán)的 JWT token eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiKiJdfX0.SWKHNF9wneXTSjBg81YN5iH8Xb2iTf_JwhfUY5Iyhsw ); const App () ( Admin dataProvider{dataProviderWithRealtime}{/* ... */}/Admin );示例 JWT 的mercureclaim 中聲明了publish: [*]和subscribe: [*]即允許發(fā)布與訂閱所有 topic。生產(chǎn)環(huán)境中應(yīng)遵循最小權(quán)限原則按實際業(yè)務(wù)限定 topic 范圍。五、編寫自定義適配器當(dāng)實時傳輸走的是 WebSocket、長輪詢long polling、GraphQL Subscription 等其他協(xié)議時你需要自己在dataProvider上實現(xiàn)subscribe、unsubscribe與publish。下面是一個基于局部變量的內(nèi)存實現(xiàn)——這也是ra-realtime在自身測試中使用的示例let subscriptions []; const dataProvider { // 常規(guī) dataProvider 方法getList、getOne 等 // ... subscribe: async (topic, subscriptionCallback) { subscriptions.push({ topic, subscriptionCallback }); return Promise.resolve({ data: null }); }, unsubscribe: async (topic, subscriptionCallback) { subscriptions subscriptions.filter( subscription subscription.topic ! topic || subscription.subscriptionCallback ! subscriptionCallback ); return Promise.resolve({ data: null }); }, publish: (topic, event) { if (!topic) { return Promise.reject(new Error(missing topic)); } if (!event.type) { return Promise.reject(new Error(missing event type)); } subscriptions.map( subscription topic subscription.topic subscription.subscriptionCallback(event) ); return Promise.resolve({ data: null }); }, };這個示例清晰地展示了三個關(guān)鍵點subscribe/unsubscribe必須配對使用且參數(shù)一致unsubscribe依賴 topic 與回調(diào)函數(shù)引用雙重匹配來移除訂閱因此組件卸載時必須傳入與訂閱時相同的函數(shù)引用否則無法成功退訂這正是 react-admin 文檔中useEffect清理函數(shù)里要保存原callback引用的原因。publish應(yīng)做參數(shù)校驗缺少topic或缺少event.type時應(yīng)當(dāng)返回 rejected 的 Promise盡早暴露錯誤。返回結(jié)構(gòu)統(tǒng)一所有方法最終返回Promise.resolve({ data: null })符合 react-admin 對 dataProvider 返回結(jié)構(gòu)的期待。調(diào)試階段你還可以利用addRealTimeMethodsInLocalBrowser提供的默認(rèn) console 日志輸出直接在瀏覽器控制臺觀察實時組件的事件行為驗證訂閱、發(fā)布鏈路是否正確。六、Topic 與事件Event格式你或許已經(jīng)注意到所有 dataProvider 實時方法的第一個參數(shù)都是topic。topic 就是標(biāo)識某個實時通道的字符串在聊天應(yīng)用里它可以用來區(qū)分不同房間在 CRUD 場景里它可以用來標(biāo)識與某條記錄相關(guān)的變更。ra-realtime的大多數(shù)組件圍繞 CRUD 邏輯展開因此它會訂閱兩個特殊命名的 topicresource/[name]—— 整個資源的變更通道resource/[name]/[id]—— 單條記錄的變更通道。對于你自己的業(yè)務(wù)事件可以隨意選用任何 topic 字符串。event是從發(fā)布者發(fā)給訂閱者的消息它是一個 JavaScript 對象必須包含type和payload兩個字段。最小示例如下{ type: created, payload: New message, }對于 CRUD 操作ra-realtime期望事件的type取值為created、updated、deleted三者之一詳下一節(jié)。七、CRUD 事件規(guī)范ra-realtime與 react-admin 深度集成其核心邏輯圍繞記錄的創(chuàng)建、更新、刪除展開。為了讓列表實時刷新、讓EditLive/ShowLive感知變更你的實時后端必須按下述規(guī)范發(fā)布事件創(chuàng)建記錄時廣播到資源級 topic攜帶created事件{ topic: resource/${resource}, event: { type: created, payload: { ids: [id]}, }, }更新記錄時需要同時向記錄級 topic 與資源級 topic 發(fā)布updated事件因為列表視圖訂閱的是資源級 topic而編輯/詳情視圖訂閱的是記錄級 topic{ topic: resource/${resource}/id, event: { type: updated, payload: { ids: [id]}, }, } { topic: resource/${resource}, event: { type: updated, payload: { ids: [id]}, }, }刪除記錄時與更新類似同樣需要記錄級與資源級兩個 topic 各發(fā)一次deleted事件{ topic: resource/${resource}/id, event: { type: deleted, payload: { ids: [id]}, }, } { topic: resource/${resource}, event: { type: deleted, payload: { ids: [id]}, }, }注意上述resource與id均為模板變量實際發(fā)布時應(yīng)替換為真實值payload.ids統(tǒng)一使用數(shù)組即使只涉及一條記錄。這些事件會觸發(fā)ListLiveUpdate刷新對應(yīng)列表、EditLive/ShowLive更新正在查看的頁面詳見 ListLiveUpdate、EditLive、ShowLive。八、鎖Lock格式與鎖相關(guān)方法鎖用于防止多位用戶并發(fā)編輯同一條記錄。一個鎖對象保存了被鎖的記錄、鎖定者身份以及加鎖時間典型結(jié)構(gòu)如下{ resource: posts, recordId: 123, identity: julien, createdAt: 2023-01-02T21:36:35.133Z, }dataProvider.getLock()與dataProvider.getLocks()應(yīng)當(dāng)返回上述結(jié)構(gòu)的鎖對象單個或數(shù)組。而兩個變更類方法dataProvider.lock()與dataProvider.unlock()則期望以下參數(shù)resource資源名如postsparams一個對象包含id記錄 id如123identity鎖定者的身份標(biāo)識字符串或數(shù)字均可如julien實際項目中可以是認(rèn)證 tokenmeta會原樣轉(zhuǎn)發(fā)給 dataProvider 的附加對象可選。在 react-admin 應(yīng)用中配合useLock、useUnlock、useGetLock、useGetLocks、useLockOnCall、useLockOnMount等 Hook 使用即可實現(xiàn)「進(jìn)入編輯頁自動加鎖 / 離開時解鎖 / 他人編輯時表單禁用」的完整協(xié)作編輯體驗相關(guān)用法見 useLock、useLockOnMount、useLockCallbacks、useGetLock、useGetLocks。九、基于 lock 資源的鎖實現(xiàn)如果你不想為鎖單獨對接一套存儲ra-realtime還提供addLocksMethodsBasedOnALockResource函數(shù)它把鎖的讀寫翻譯為對一個普通locks資源的 CRUD 操作dataProvider.getLocks()調(diào)用會被翻譯成dataProvider.getList(locks)dataProvider.lock()調(diào)用會被翻譯成dataProvider.create(locks)。這個lock資源上的每條記錄應(yīng)包含如下字段{ id: 123, identity: Toad, resource: people, recordId: 18, createdAt: 2020-09-29 10:20 }需要說明的是identity與createdAt的具體格式取決于你的后端 API以上只是約定俗成的示例。在 react-admin 應(yīng)用中使用它的方式與實時適配器完全一致——只需增強原始 dataProvider 后傳入Adminimport { Admin } from react-admin; import { addLocksMethodsBasedOnALockResource } from react-admin/ra-realtime; const dataProviderWithLocks addLocksMethodsBasedOnALockResource( dataProvider // 原始 dataProvider ); const App () ( Admin dataProvider{dataProviderWithLocks}{/* ... */}/Admin );十、在組件中直接調(diào)用 dataProvider 實時方法將增強后的實時dataProvider傳給Admin之后你可以在任意 React 組件中通過useDataProvider()Hook 直接調(diào)用這些實時方法。react-admin 的useDataProvider實現(xiàn)見 packages/ra-core/src/dataProvider/useDataProvider.ts從DataProviderContext取出實例并對調(diào)用做統(tǒng)一的響應(yīng)格式校驗因此實時方法同樣會經(jīng)由這一代理被調(diào)用。下面是一個實時展示messagestopic 消息的組件掛載時訂閱卸載時退訂收到事件后追加到列表import React, { useState } from react; import { useDataProvider, useNotify } from react-admin; const MessageList () { const notify useNotify(); const [messages, setMessages] useState([]); const dataProvider useDataProvider(); useEffect(() { const callback event { // event 形如 // { // topic: messages, // type: created, // payload: New message, // } setMessages(messages [...messages, event.payload]); notify(New message); }; // 掛載時訂閱 messages topic dataProvider.subscribe(messages, callback); // 卸載時退訂 return () dataProvider.unsubscribe(messages, callback); }, [setMessages, notify, dataProvider]); return ( ul {messages.map((message, index) ( li key{index}{message}/li ))} /ul ); };再來看一個向messagestopic 發(fā)布事件的按鈕——該 topic 上的所有訂閱者都會執(zhí)行各自的回調(diào)import React from react; import { useDataProvider, useNotify } from react-admin; const SendMessageButton () { const dataProvider useDataProvider(); const notify useNotify(); const handleClick () { dataProvider .publish(messages, { type: created, payload: New message }) .then(() notify(Message sent)); }; return Button onClick{handleClick}Send new message/Button; };實踐建議你通常不需要直接調(diào)用publish()。大多數(shù)實時后端會在數(shù)據(jù)發(fā)生變化時自動發(fā)布事件所以上面這個按鈕示例是虛構(gòu)的教學(xué)場景?，F(xiàn)實中一個典型的SendMessageButton只需調(diào)用dataProvider.create(messages)由 API 完成「創(chuàng)建消息」與「向?qū)崟r總線發(fā)布created事件」兩件事。這也再次印證了前文的原則實時發(fā)布是服務(wù)端職責(zé)客戶端適配器主要負(fù)責(zé)訂閱與消費。十一、更進(jìn)一步了解實時功能的整體架構(gòu)、Publish/Subscribe 機制、實時通知、菜單徽標(biāo)與安裝方式見 Realtime 總覽文檔學(xué)習(xí)如何從零編寫一個支持實時方法的 dataProvider見 編寫自定義 dataProvider查閱 react-admin 支持的 dataProvider 列表見 DataProvider 列表深入理解數(shù)據(jù)獲取流程中實時鉤子的定位見 數(shù)據(jù)獲取指南 與 DataProvider 實時能力。接入實時能力后多個用戶可以在同一張列表、同一個編輯頁面上協(xié)同工作且不會丟失彼此的修改——這正是ra-realtime與本文所述實時 dataProvider 規(guī)范共同提供的價值。贊分享前端UI組件【免費下載鏈接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design項目地址https://gitcode.com/gh_mirrors/re/react-admin點擊查看免費下載相關(guān)推薦深入React-Admin數(shù)據(jù)提供者(Data Provider)機制解析深入React Admin數(shù)據(jù)提供者 Data Provider 機制解析 React Admin的數(shù)據(jù)提供者Data Provider是其架構(gòu)設(shè)計的核心前端UI組件react-admin 自定義 Data Provider 編寫指南方法契約、參數(shù)協(xié)議與完整 REST/GraphQL 實現(xiàn)react admin 自定義 Data Provider 編寫指南方法契約、參數(shù)協(xié)議與完整 REST/GraphQL 實現(xiàn) 導(dǎo)讀 本指南基于 react前端UI組件為 react-admin 編寫自定義 Data Provider方法契約、錯誤規(guī)范與 REST / GraphQL 完整實現(xiàn)為 react admin 編寫自定義 Data Provider方法契約、錯誤規(guī)范與 REST / GraphQL 完整實現(xiàn) react admin 的 A前端UI組件上一篇【親測免費】讓你的任務(wù)欄萌起來RunCat_for_windows新手入門指南及常見問題解決下一篇Celestia核心功能解析從太陽系到深空天體的完整教程創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考