Refine v5 集成 Airtable 數(shù)據(jù)提供者refinedev/airtable完整實戰(zhàn)指南【免費(fèi)下載鏈接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.項目地址: https://gitcode.com/GitHub_Trending/re/refineAirtable 是一款電子表格與數(shù)據(jù)庫混合體spreadsheet-database hybrid服務(wù)它同時具備表格的易用性與數(shù)據(jù)庫的結(jié)構(gòu)化查詢能力非常適合快速搭建內(nèi)容管理、輕量業(yè)務(wù)后臺等場景。本文基于 Refine 官方文檔 Airtable 集成指南 以及倉庫中 packages/airtable 包的源碼與測試系統(tǒng)講解如何在 Refine v5 應(yīng)用中使用refinedev/airtable數(shù)據(jù)提供者完成 CRUD、排序、篩選、分頁與認(rèn)證配置。讀完本文你將能夠從零接入 Airtable并理解該數(shù)據(jù)提供者底層如何把 Refine 的查詢參數(shù)翻譯成 Airtable Formula 與 REST 調(diào)用從而在實際項目中游刃有余地排查問題、定制行為。為什么需要 Airtable 數(shù)據(jù)提供者Refine 通過數(shù)據(jù)提供者Data Provider與各類后端通信。數(shù)據(jù)提供者是一個實現(xiàn)了DataProvider接口的函數(shù)負(fù)責(zé)把 Refine 的useList、useOne、useUpdate等數(shù)據(jù) Hook 的參數(shù)資源名resource、記錄id、分頁pagination、排序sorters、篩選filters翻譯成對目標(biāo) API 的真實請求并把響應(yīng)規(guī)范化為{ data, total }等 Refine 約定結(jié)構(gòu)。Airtable 的 REST API 與常規(guī) REST 服務(wù)差異較大其記錄以id fields的形式返回查詢依賴filterByFormulaAirtable Formula 語法、排序依賴sort數(shù)組、單次讀取條數(shù)上限為 100 條。refinedev/airtable正是為了抹平這些差異而存在讓開發(fā)者可以像使用其他數(shù)據(jù)提供者一樣用統(tǒng)一的 Hook 語法操作 Airtable 表格。關(guān)于 Refine 數(shù)據(jù)獲取機(jī)制的通用介紹可參考官方指南 Data Fetching。安裝在你的 Refine 項目中安裝數(shù)據(jù)提供者包npm install refinedev/airtable # 或 pnpm add refinedev/airtable從倉庫中 packages/airtable/package.json 可以看到該包當(dāng)前版本為5.0.1以refinedev/core^5.0.0作為 peer dependency內(nèi)部依賴airtableAirtable 官方 JavaScript 客戶端、qualifyze/airtable-formulator用于把篩選條件編譯為 Airtable Formula等庫并聲明運(yùn)行環(huán)境要求 Node.js 20。也就是說該數(shù)據(jù)提供者專為 Refine v5 設(shè)計與refinedev/corev4 不兼容。快速開始接入你的第一個 Airtable 數(shù)據(jù)源1. 獲取憑證使用該集成前需要先準(zhǔn)備兩個值A(chǔ)PI_TOKENAirtable 賬號的 API Token。需要注意官方文檔明確說明該集成目前不支持 Airtable 的個人訪問令牌Personal Access Token請使用傳統(tǒng) API Key 格式的 TokenBASE_ID目標(biāo) Base工作區(qū)/數(shù)據(jù)庫實例的 ID可以在 Airtable 的 API 文檔頁面或 Base URL 中獲取形如appXXXXXXXXXXXXXX。2. 在Refine組件中掛載數(shù)據(jù)提供者refinedev/airtable默認(rèn)導(dǎo)出一個工廠函數(shù)dataProvider接受API_TOKEN與BASE_ID兩個必填參數(shù)返回一個完整的數(shù)據(jù)提供者對象import Refine from refinedev/core; import dataProvider from refinedev/airtable; const App () ( Refine dataProvider{dataProvider(API_TOKEN, BASE_ID)} {/* 應(yīng)用路由、資源定義等 */} /Refine ); export default App;掛載之后資源名resource即對應(yīng) Airtable 中的表名Table 名。倉庫中的完整可運(yùn)行示例位于 examples/data-provider-airtable/src/App.tsx該示例定義了兩個資源blog_posts與categories并演示了與 Ant DesignThemedLayout、RefineThemes.Blue和 React Router 的組合使用方式適合作為接入時的參照模板。數(shù)據(jù)提供者工廠函數(shù)簽名與返回值深入 packages/airtable/src/dataProvider.ts 源碼可以看到工廠函數(shù)的完整簽名export const dataProvider ( apiKey: string, baseId: string, airtableClient?: AirtableBase, ): RequiredDataProvider { const base airtableClient || new Airtable({ apiKey: apiKey }).base(baseId); // ... };三個參數(shù)的作用分別是參數(shù)類型說明apiKeystringAirtable API Token用于創(chuàng)建官方客戶端實例baseIdstring目標(biāo) Base 的 IDairtableClientAirtableBase可選自定義 Airtable 客戶端實例傳入后優(yōu)先使用可用于注入自定義認(rèn)證或 Mock 客戶端返回值類型為RequiredDataProvider即完整實現(xiàn)了DataProvider接口的 12 個方法getList、getOne、getMany、create、createMany、update、updateMany、deleteOne、deleteMany、getApiUrl、custom。這里有兩個值得一提的例外getApiUrl與custom在源碼中直接throw Error(Not implemented on refine-airtable data provider.)即當(dāng)前版本未實現(xiàn)。這意味著依賴custom方法做自由請求、或依賴getApiUrl讀取 API 地址的用法在該數(shù)據(jù)提供者上不可用所有讀寫方法返回的記錄都遵循 Airtable 的數(shù)據(jù)模型被規(guī)范化為{ id, ...fields }結(jié)構(gòu)即記錄 ID 放在id字段其余列值平鋪為頂層字段見下文的 CRUD 逐方法講解。CRUD 方法的底層實現(xiàn)與調(diào)用約定以下內(nèi)容均以 dataProvider.ts 源碼為準(zhǔn)并輔以 packages/airtable/test 下的測試用例佐證。getList列表查詢、排序與分頁getList: async ({ resource, pagination, sorters, filters }) { const { currentPage 1, pageSize 10, mode server } pagination ?? {}; const generatedSort generateSort(sorters) || []; const queryFilters generateFilter(filters); const { all } base(resource).select({ pageSize: 100, sort: generatedSort, ...(queryFilters ? { filterByFormula: queryFilters } : {}), }); const data await all(); const isServerPaginationEnabled mode server; return { data: data .slice( isServerPaginationEnabled ? (currentPage - 1) * pageSize : undefined, isServerPaginationEnabled ? currentPage * pageSize : undefined, ) .map((p) ({ id: p.id, ...p.fields })), total: data.length, }; }從源碼可以確認(rèn)以下行為排序通過sorters傳入由generateSort轉(zhuǎn)換為 Airtable 的{ field, direction }數(shù)組詳見下文排序章節(jié)篩選通過filters傳入由generateFilter編譯為filterByFormula詳見下文篩選章節(jié)分頁每次向 Airtable 請求時固定使用pageSize: 100拉取這是 Airtable API 單次返回的最大條數(shù)隨后在內(nèi)存中執(zhí)行切片。分頁參數(shù)默認(rèn)值為currentPage 1、pageSize 10、mode server當(dāng)mode server默認(rèn)時按(currentPage - 1) * pageSize到currentPage * pageSize切片當(dāng)mode為client等非 server 值時不做切片返回全量數(shù)據(jù)由前端側(cè)如useTable的 client 模式自行分頁total返回的是all()拉取到的全部記錄數(shù)即未分頁前滿足篩選條件的記錄總數(shù)而不是當(dāng)前頁條數(shù)這保證了分頁組件的總頁數(shù)計算是準(zhǔn)確的。需要留意的是由于 Airtable 單次最多返回 100 條getList實際可觸及的數(shù)據(jù)規(guī)模受此限制若表數(shù)據(jù)量超過 100 條當(dāng)前實現(xiàn)并不會自動翻頁拉取全部數(shù)據(jù)。這一點在 test/getList/index.spec.ts 的用例中也能看到測試用posts表僅返回 2 條記錄total為2。getOne / getMany單條與批量讀取getOne: async ({ resource, id }) { const { fields } await base(resource).find(id.toString()); return { data: { id, ...fields } }; }, getMany: async ({ resource, ids }) { const { all } base(resource).select({ pageSize: 100 }); const data await all(); return { data: data.filter((p) ids.includes(p.id)).map((p) ({ id: p.id, ...p.fields })), }; },getOne直接調(diào)用 Airtable 客戶端的find(id)按記錄 ID 精確讀取效率最高getMany由于 Airtable 沒有原生的按 ID 批量讀取接口實現(xiàn)上是拉取整張表每頁 100 條后在內(nèi)存中按ids過濾。因此當(dāng)表數(shù)據(jù)量很大且頻繁調(diào)用getMany時會帶來額外的請求開銷這是該實現(xiàn)的取舍值得在業(yè)務(wù)設(shè)計時留意。create / createMany新增記錄create: async ({ resource, variables }) { const { id, fields } await base(resource).create(variables); return { data: { id, ...fields } }; }, createMany: async ({ resource, variables }) { const data await base(resource).create(variables); return { data: data.map((p) ({ id: p.id, ...p.fields })) }; },create一次創(chuàng)建一條記錄variables中的鍵值對即 Airtable 表格的字段名與值createMany一次批量創(chuàng)建多條記錄variables為記錄數(shù)組返回值是包含新記錄id與完整fields的數(shù)組Airtable 會自動為每條新記錄分配rec開頭的記錄 ID寫入結(jié)果中的id字段即取自該 ID。update / updateMany更新記錄update: async ({ resource, id, variables }) { const { fields } await base(resource).update(id.toString(), variables); return { data: { id, ...fields } }; }, updateMany: async ({ resource, ids, variables }) { const requestParams ids.map((id) ({ id: id.toString(), fields: { ...variables } })); const data await base(resource).update(requestParams); return { data: data.map((p) ({ id: p.id, ...p.fields })) }; },update更新單條記錄注意id會被顯式轉(zhuǎn)為字符串后傳給 AirtableupdateMany會把同一個variables應(yīng)用到所有目標(biāo) ID構(gòu)造出[{ id, fields }]形式的批量更新參數(shù)一次調(diào)用完成多條更新。deleteOne / deleteMany刪除記錄deleteOne: async ({ resource, id }) { const { fields } await base(resource).destroy(id.toString()); return { data: { id, ...fields } }; }, deleteMany: async ({ resource, ids }) { const data await base(resource).destroy(ids.map(String)); return { data: data.map((p) ({ id: p.id, ...p.fields })) }; },刪除操作直接調(diào)用 Airtable 客戶端的destroy方法返回被刪除記錄的最后狀態(tài)。deleteMany通過ids.map(String)統(tǒng)一轉(zhuǎn)字符串后批量銷毀。排序從 CrudSorting 到 Airtable sort 參數(shù)排序邏輯位于 packages/airtable/src/utils/generateSort.tsexport const generateSort (sorters?: CrudSorting) { return sorters?.map((item) ({ field: item.field, direction: item.order, })); };Refine 的CrudSorting結(jié)構(gòu){ field, order }其中order為asc或desc被原樣映射為 Airtableselect方法接受的sort: [{ field, direction }]數(shù)組。也就是說你可以在useList或useTable中直接傳入useTable({ sorters: { initial: [ { field: title, order: asc }, { field: created_at, order: desc }, ], }, });多個排序字段會按數(shù)組順序生效。對應(yīng)測試見 packages/airtable/test/utils/generateSort.spec.ts以及 test/getList/index.spec.ts 中對title降序排序返回結(jié)果的驗證。篩選Refine 過濾器到 Airtable Formula 的編譯管線篩選是refinedev/airtable最有技術(shù)含量的一部分。Refine 的filters需要被翻譯成 Airtable 的filterByFormula字符串這一管線由 packages/airtable/src/utils 目錄下的多個模塊協(xié)作完成并最終借助qualifyze/airtable-formulator把中間表示編譯為 Formula 字符串。編譯流程調(diào)用鏈如下generateFilter.ts入口函數(shù)。若傳入了filters則以[AND, ...generateFilterFormula(filters)]為根節(jié)點調(diào)用compile()輸出最終 Formula由于 Refine 的CrudFilters頂層數(shù)組語義就是各條件之間取 AND因此這里顯式包了一層AND。若未傳入篩選條件返回undefinedgetList就不會攜帶filterByFormulagenerateFilterFormula.ts遍歷條件數(shù)組遇到operator or時遞歸生成[OR, ...]子表達(dá)式其余條件交給generateLogicalFilterFormulagenerateLogicalFilterFormula.ts將單個邏輯條件轉(zhuǎn)換為 Airtable Formula 的數(shù)組中間表示如[, { field }, value]。操作符支持矩陣下表整理自 isSimpleOperator.ts 與 generateLogicalFilterFormula.tsRefine 操作符語義生成的 Airtable Formula說明eq等于{field} value簡單比較直接映射ne不等于{field} ! value簡單比較lt小于{field} value簡單比較lte小于等于{field} value簡單比較gt大于{field} value簡單比較gte大于等于{field} value簡單比較containss包含區(qū)分大小寫FIND(value, {field}) ! 0借助FIND定位子串結(jié)果非 0 即包含ncontainss不包含區(qū)分大小寫FIND(value, {field}) 0同上取反contains包含不區(qū)分大小寫FIND(LOWER(value), LOWER({field})) ! 0雙方先LOWER再FINDncontains不包含不區(qū)分大小寫FIND(LOWER(value), LOWER({field})) 0同上取反null為空{(diào)field} BLANK()匹配空值nnull非空{(diào)field} ! BLANK()匹配非空值or邏輯或OR(...)在generateFilterFormula中遞歸展開其他操作符—拋出Error(Operator ${operator} is not supported for the Airtable data provider)如in、between等不支持其中簡單比較操作符的映射關(guān)系定義在 isSimpleOperator.tsexport const simpleOperatorMapping: RecordSimpleOperators, OperatorSymbol { eq: , ne: !, lt: , lte: , gt: , gte: , } as const;值得注意的細(xì)節(jié)是contains與containss的差異contains系列會對字段與值同時做LOWER()轉(zhuǎn)換實現(xiàn)大小寫不敏感的模糊匹配而containss系列保持大小寫敏感。對應(yīng)操作符判定邏輯見 isContainsOperator.ts單元測試見 test/utils 下的generateFilterFormula.spec.ts、generateLogicalFilterFormula.spec.ts、isContainsOperator.spec.ts、isSimpleOperator.spec.ts。組合條件的實際效果由于頂層數(shù)組隱式取 ANDor顯式取 OR你可以組合出常見的業(yè)務(wù)查詢。例如下面的篩選條件filters: [ { field: status, operator: eq, value: published }, { operator: or, value: [ { field: author, operator: contains, value: john }, { field: author, operator: contains, value: jane }, ], }, ]會被編譯為類似AND({status}published, OR(FIND(LOWER(john), LOWER({author})) ! 0, FIND(LOWER(jane), LOWER({author})) ! 0))的 Formula 交給 Airtable 執(zhí)行。認(rèn)證機(jī)制與第三方客戶端注入refinedev/airtable底層使用 Airtable 官方 JavaScript 客戶端airtable.js發(fā)起請求認(rèn)證方式為new Airtable({ apiKey: apiKey }).base(baseId)即通過API Token傳統(tǒng) API Key完成認(rèn)證。官方文檔特別提示Airtable 的 Personal Access Token個人訪問令牌目前不被支持請勿混用。同時工廠函數(shù)暴露了可選的第三個參數(shù)airtableClient允許調(diào)用方注入一個自定義的AirtableBase實例import Airtable from airtable; const customBase new Airtable({ apiKey: API_TOKEN, endpointUrl: https://... }).base(BASE_ID); dataProvider(API_TOKEN, BASE_ID, customBase)傳入后dataProvider會優(yōu)先使用該實例這在接入代理、Mock 服務(wù)或自定義網(wǎng)絡(luò)配置的場景下非常實用倉庫內(nèi)的測試也正是通過 nock 攔截請求、配合真實 airtable 客戶端完成的。已知限制與注意事項基于文檔與源碼使用該數(shù)據(jù)提供者時需要了解以下邊界getApiUrl與custom未實現(xiàn)調(diào)用會拋出Not implemented on refine-airtable data provider.錯誤見 dataProvider.ts 末尾依賴這兩者的功能如custom自由請求不可用操作符支持有限僅支持上表列出的操作符in、between、startswith、endswith等 Refine 內(nèi)置操作符會直接拋錯分頁在內(nèi)存中進(jìn)行g(shù)etList每次向 Airtable 拉取 100 條后切片數(shù)據(jù)量超過 100 條時無法訪問到第 100 條之后的記錄getMany同樣依賴?yán)砗髢?nèi)存過濾記錄結(jié)構(gòu)被扁平化Airtable 記錄的列值統(tǒng)一放在fields中數(shù)據(jù)提供者將其平鋪為{ id, ...fields }關(guān)聯(lián)表、附件等復(fù)雜字段類型會以其原始對象/數(shù)組形式暴露版本配套包版本5.0.1需要refinedev/core^5.0.0與 Node.js 20接入前請確認(rèn)項目版本認(rèn)證僅支持 API Token不支持 Personal Access Token。可運(yùn)行示例與延伸閱讀倉庫中提供了完整可運(yùn)行的示例工程 examples/data-provider-airtable其中 App.tsx 展示了數(shù)據(jù)提供者與路由、資源、Ant Design 主題布局的完整集成方式包含blog_posts、categories兩個資源的 list/create/edit/show 頁面組織適合作為腳手架參考。若想進(jìn)一步理解 Refine 的數(shù)據(jù)獲取機(jī)制DataProvider接口約定、useList/useOne/useUpdate等數(shù)據(jù) Hook、基于 TanStack Query 的緩存與失效策略、多數(shù)據(jù)提供者混用等請閱讀官方指南 Data Fetching。本文涉及的源碼與測試均可直接在倉庫的 packages/airtable 目錄中繼續(xù)研讀?！久赓M(fèi)下載鏈接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.項目地址: https://gitcode.com/GitHub_Trending/re/refine創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考