桌面應(yīng)用跨平臺(tái)前端【免費(fèi)下載鏈接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.項(xiàng)目地址https://gitcode.com/gh_mirrors/re/readest點(diǎn)擊查看免費(fèi)下載導(dǎo)讀本文以 Readest 開源電子書閱讀器中的 OPDS 分組輪播Group Carousel功能為主線詳細(xì)講解其實(shí)現(xiàn)原理與工程細(xì)節(jié)。當(dāng)你通過 OPDS 協(xié)議瀏覽的書目摘要包含多個(gè)分組如流行最近時(shí)Readest 會(huì)將每個(gè)分組渲染為一條橫向虛擬化輪播軌道而非縱向網(wǎng)格從而保持頁面緊湊、便于快速瀏覽。讀完本文你將掌握輪播與網(wǎng)格的切換判定邏輯、基于react-virtuoso的橫向虛擬化實(shí)現(xiàn)、按索引翻頁替代像素滾動(dòng)的關(guān)鍵技巧、封面懶加載機(jī)制以及 jsdom 環(huán)境下如何為虛擬列表編寫可靠測(cè)試。本文內(nèi)容以倉庫記憶文檔 opds-groups-carousel-4750.md 為骨架結(jié)合 FeedView.tsx、GroupCarousel.tsx、PublicationCard.tsx 等源碼逐一展開。背景OPDS 分組與閱讀器目錄瀏覽OPDSOpen Publication Distribution System是電子書分發(fā)領(lǐng)域的事實(shí)標(biāo)準(zhǔn)協(xié)議通過 Atom/JSON 格式描述目錄Catalog、分組Groups、導(dǎo)航條目Navigation與出版物Publications。Readest 在 opds 目錄下實(shí)現(xiàn)了完整的 OPDS 客戶端目錄管理、Feed 渲染、搜索、出版物詳情與下載等。在 FeedView.tsx 中可以看到Feed 數(shù)據(jù)模型包含metadata標(biāo)題/副標(biāo)題、navigation導(dǎo)航入口、publications出版物列表、groups分組列表、facets篩選面與links分頁鏈接。當(dāng)一個(gè)目錄返回多個(gè)分組時(shí)如何呈現(xiàn)成為關(guān)鍵的用戶體驗(yàn)問題若每個(gè)分組都渲染為完整縱向網(wǎng)格頁面會(huì)變得極長(zhǎng)翻越大量分組十分繁瑣。這正是 issue #4750 要解決的問題當(dāng) OPDS feed 的分組數(shù) ≥ 2 時(shí)將每個(gè)分組渲染為橫向輪播分組數(shù)為 1 時(shí)保持原有網(wǎng)格布局。該行為與 Thorium另一款知名開源閱讀器的表現(xiàn)一致。相關(guān)實(shí)現(xiàn)在 PR #4755 中合并并沉淀為項(xiàng)目記憶文檔 opds-groups-carousel-4750.md。分組渲染的分流邏輯網(wǎng)格與輪播的切換FeedView是分組渲染的決策中樞。核心判定只有一行FeedView.tsxconst useCarousel (feed.groups?.length ?? 0) 2;feed.groups.length 2啟用輪播模式每個(gè) group 的publications/navigation由GroupCarousel渲染單分組groups.length 1或沒有分組回退到gridClassName定義的網(wǎng)格布局。網(wǎng)格與輪播的差異也體現(xiàn)在視覺細(xì)節(jié)上FeedView.tsx維度輪播模式≥2 組網(wǎng)格模式單組分組標(biāo)題text-lg font-bold緊湊間距mb-2text-2xl font-bold寬裕間距mb-4分組區(qū)塊間距mb-6mb-12分組尾部鏈接保留 View All 按鈕btn btn-ghost保留 View All 按鈕在輪播模式下FeedView通過GroupCarousel的itemContent回調(diào)把數(shù)據(jù)喂給虛擬列表GroupCarousel count{group.publications.length} defaultRowHeight{250} coverCentered itemContent{(itemIndex) ( div>it(renders each group as a horizontal carousel when there are two or more groups, () { renderFeed(feedWithGroups([Popular, Recent])); expect(screen.getAllByTestId(group-carousel)).toHaveLength(2); }); it(does not use a carousel when there is only one group, () { renderFeed(feedWithGroups([Only Group])); expect(screen.queryByTestId(group-carousel)).toBeNull(); });GroupCarousel根節(jié)點(diǎn)帶有data-testidgroup-carousel測(cè)試通過該標(biāo)識(shí)斷言每個(gè)分組渲染一條輪播與單分組不渲染輪播。GroupCarousel橫向虛擬化的核心組件GroupCarousel.tsx 是輪播的核心實(shí)現(xiàn)對(duì)外暴露四個(gè) propsProp類型作用countnumber條目總數(shù)itemContent(index: number) React.ReactNode由調(diào)用方提供的條目渲染函數(shù)defaultRowHeightnumber初始行高px避免真實(shí)高度測(cè)量前的布局閃爍coverCenteredboolean默認(rèn)false箭頭是否以封面中線為錨點(diǎn)垂直居中組件內(nèi)部基于react-virtuoso的Virtuoso組件啟用horizontalDirection讓列表沿水平軸滾動(dòng)GroupCarousel.tsxVirtuoso ref{virtuosoRef} horizontalDirection totalCount{count} itemContent{itemContent} increaseViewportBy{200} classNameno-scrollbar px-4 pb-2 style{{ height: rowHeight }} scrollerRef{(ref) { scrollerRef.current ref as HTMLElement; }} rangeChanged{(range) { rangeRef.current range; }} atTopStateChange{(atStart) setShowLeftArrow(!atStart)} atBottomStateChange{(atEnd) setShowRightArrow(!atEnd)} totalListHeightChanged{measure} /虛擬化的收益封面懶加載Virtuoso 的核心價(jià)值是只掛載視口內(nèi)的條目含increaseViewportBy{200}的提前量配合PublicationCard中的 CachedImage 組件實(shí)現(xiàn)封面圖片的按需請(qǐng)求。記憶文檔中記錄的實(shí)測(cè)現(xiàn)象是每個(gè)分組無論規(guī)模多大初始僅拉取約 12 張封面位于最右側(cè)的條目只有在滾動(dòng)到附近時(shí)才發(fā)起圖片請(qǐng)求。這意味著即使是包含數(shù)百本書的分組首屏也只渲染約一屏卡片、發(fā)起少量封面請(qǐng)求內(nèi)存與網(wǎng)絡(luò)開銷都保持在低水平——這正是虛擬化橫向輪播相比一次性渲染整個(gè)網(wǎng)格的核心優(yōu)勢(shì)。行高測(cè)量與箭頭錨點(diǎn)由于虛擬列表在渲染前沒有可用的布局尺寸GroupCarousel采用先給默認(rèn)高度、再測(cè)量修正的策略defaultRowHeight作為初始style.height保證首幀即可渲染導(dǎo)航條目 80px、出版物條目 250px掛載后通過totalListHeightChanged回調(diào)觸發(fā)measure()從滾動(dòng)容器中查詢第一個(gè)[data-carousel-item]元素用getBoundingClientRect().height覆蓋真實(shí)行高GroupCarousel.tsx若啟用coverCentered再定位第一個(gè)figure封面容器計(jì)算其中線相對(duì)輪播容器頂部的偏移coverCenter作為箭頭按鈕的top值。為什么箭頭要單獨(dú)對(duì)準(zhǔn)封面因?yàn)镻ublicationCard在封面下方還渲染標(biāo)題與作者行整行高度大于封面。若箭頭以整行中線居中視覺上會(huì)明顯偏低看起來懸空。以封面中線為錨點(diǎn)top: coverCenter ?? 50%箭頭始終穩(wěn)穩(wěn)卡在封面垂直中心與書封對(duì)齊更協(xié)調(diào)GroupCarousel.tsx。實(shí)戰(zhàn)踩坑為什么橫向模式不能按像素滾動(dòng)記憶文檔明確記錄了一個(gè)花費(fèi)真實(shí)調(diào)試成本的坑VirtuosoHandle.scrollBy({left})在橫向模式下是 no-op。Virtuoso 的 handle 內(nèi)部把滾動(dòng)軸映射到垂直方向像素滾動(dòng)在橫向模式下不生效同時(shí) Virtuoso 對(duì)橫向軌道采用懶尺寸計(jì)算即便直接操作原生 scroller 元素調(diào)用像素scrollBy也會(huì)被鉗制在當(dāng)前已渲染寬度內(nèi)——因?yàn)檐壍郎形幢粨伍_到完整內(nèi)容寬度。因此GroupCarousel的翻頁按鈕全部改為按索引翻頁GroupCarousel.tsxconst scrollByPage (direction: -1 | 1) { const { startIndex, endIndex } rangeRef.current; if (direction 1) { virtuosoRef.current?.scrollToIndex({ index: Math.min(count - 1, endIndex), align: start, behavior: smooth, }); } else { virtuosoRef.current?.scrollToIndex({ index: Math.max(0, startIndex), align: end, behavior: smooth, }); } };核心思路維護(hù)可見范圍rangeChanged持續(xù)把當(dāng)前可見的首尾索引寫入rangeRef{ startIndex, endIndex }向右翻頁取Math.min(count - 1, endIndex)——即當(dāng)前最右側(cè)可見項(xiàng)——以align: start對(duì)齊到起點(diǎn)等價(jià)于推進(jìn)大約一屏向左翻頁取Math.max(0, startIndex)——當(dāng)前最左側(cè)可見項(xiàng)——以align: end對(duì)齊等價(jià)于回退大約一屏。scrollToIndex是 Virtuoso 提供的按條目定位 API不依賴像素測(cè)量因此繞開了橫向軌道的懶尺寸問題。配合behavior: smooth獲得平滑滾動(dòng)動(dòng)畫。箭頭顯隱與滾動(dòng)條隱藏箭頭顯隱atTop / atBottom 狀態(tài)左右箭頭由 Virtuoso 的滾動(dòng)位置回調(diào)驅(qū)動(dòng)GroupCarousel.tsxatTopStateChange{(atStart) setShowLeftArrow(!atStart)} atBottomStateChange{(atEnd) setShowRightArrow(!atEnd)}在橫向模式下Virtuoso 把頂部/底部語義映射為左側(cè)/右側(cè)滾動(dòng)到最左端時(shí)atTop為 true左箭頭隱藏滾動(dòng)到最右端時(shí)atBottom為 true右箭頭隱藏。這樣用戶能直觀感知還有內(nèi)容可滾。滾動(dòng)條隱藏scoped no-scrollbar 工具類橫向軌道本身不展示滾動(dòng)條由 globals.css 中定義的作用域工具類實(shí)現(xiàn).no-scrollbar { scrollbar-width: none; /* Firefox */ -ms-overflow-style: none; /* 舊 Edge/IE */ } .no-scrollbar::-webkit-scrollbar { display: none; /* WebKit/Blink */ }該工具類在倉庫中被多處橫向滾動(dòng)場(chǎng)景復(fù)用如 library/page.tsx、RecentShelf.tsx但只在目標(biāo)滾動(dòng)容器上作用域化應(yīng)用不會(huì)影響全局滾動(dòng)條樣式。按鈕樣式eink-bordered左右箭頭按鈕使用eink-bordered類GroupCarousel.tsx這是 Readest 針對(duì)電子墨水屏E-ink模式設(shè)計(jì)的樣式系統(tǒng)普通屏幕下按鈕帶圓角、陰影與 hover 邊框過渡E-ink 屏幕沒有 hover 概念eink-bordered保證按鈕始終具備清晰的base-100表面與 1pxbase-content邊框避免同類色塊在 E-ink 上糊成一片參見 AnnotationToolbarCustomizerEink.test.tsx 對(duì)該不變量的斷言。PublicationCard輪播與網(wǎng)格共享的出版物卡片PublicationCard.tsx 同時(shí)服務(wù)于輪播與網(wǎng)格是分組渲染的最小復(fù)用單元。其要點(diǎn)封面選取優(yōu)先級(jí)優(yōu)先取 rel 含http://opds-spec.org/image/thumbnail的縮略圖回退到第一張任意圖片真正展示時(shí)先找http://opds-spec.org/imagecover再回退 thumbnailPublicationCard.tsx緩存失效策略cacheVersion{publication.metadata?.updated}將 Atom 條目的updated值傳給CachedImage封面被替換時(shí)緩存自動(dòng)失效。測(cè)試 publication-card.test.tsx 驗(yàn)證了這一行為issue #5492作者名清洗通過formatContributorName把 Calibre 序列化的管道符Doe| John還原為逗號(hào)Doe, John再以連接issue #5183見 opdsUtils.ts圓角封面與徽標(biāo)移除本次變更封面容器改為overflow-hidden rounded-sm與圖書館書架卡片風(fēng)格統(tǒng)一同時(shí)移除了卡片上的行內(nèi)獲取/價(jià)格徽標(biāo)acquisition/price badge該徽標(biāo)仍保留在詳情頁 PublicationView.tsx 中渲染。詳情頁是輪播的下一跳點(diǎn)擊輪播條目會(huì)調(diào)用onPublicationSelect(groupIndex, itemIndex)最終進(jìn)入 PublicationView.tsx那里才展示完整獲取/價(jià)格信息、格式下載按鈕、流式閱讀與音頻播放入口。測(cè)試策略jsdom 下 mock react-virtuoso虛擬化組件依賴真實(shí)布局計(jì)算而 jsdom 沒有布局引擎直接渲染 Virtuoso 會(huì)得到空列表。因此測(cè)試必須對(duì)react-virtuoso進(jìn)行 mock。倉庫的 feed-view.test.tsx 采用了與 TOCView/BooknoteView 測(cè)試一致的方案——用itemContent同步渲染全部條目vi.mock(react-virtuoso, async () { const React await import(react); const renderAll ( { totalCount, itemContent }: { totalCount: number; itemContent: (index: number) React.ReactNode }, _ref: React.Refunknown, ) ( div {Array.from({ length: totalCount }, (_, index) ( div key{index}{itemContent(index)}/div ))} /div ); return { Virtuoso: React.forwardRef(renderAll), VirtuosoGrid: React.forwardRef(renderAll), }; });同時(shí)還需 mockCachedImage與useTranslation。這套 mock 的價(jià)值在于測(cè)試聚焦于數(shù)據(jù)驅(qū)動(dòng)邏輯哪個(gè)分組用輪播、點(diǎn)擊回調(diào)攜帶正確的(groupIndex, itemIndex)參數(shù)、單組回退網(wǎng)格而非 Virtuoso 自身的滾動(dòng)行為——后者由 react-virtuoso 上游測(cè)試覆蓋。測(cè)試用例覆蓋feed-view.test.tsx兩個(gè)及以上分組 → 每個(gè)分組渲染一條group-carousel單分組 → 不渲染輪播出版物走網(wǎng)格布局Calibre 管道符作者名還原Doe| John Walter→Doe, John Walter Smith, James Richard點(diǎn)擊輪播條目 →onPublicationSelect收到正確的(groupIndex, itemIndex)。與 OverlayScrollbars 的關(guān)聯(lián)記憶文檔末尾關(guān)聯(lián)了virtuoso_overlayscrollbars。在 Readest 的滾動(dòng)體系里OPDS 輪播軌道走的是隱藏原生滾動(dòng)條 按索引翻頁方案本組件而其他依賴 OverlayScrollbars 定制滾動(dòng)條外觀的場(chǎng)景如閱讀器側(cè)欄則使用另一套虛擬化滾動(dòng)條組合。兩者都是 Virtuoso 生態(tài)在 Readest 中的落地形態(tài)前者強(qiáng)調(diào)極致緊湊與低開銷后者強(qiáng)調(diào)可定制的滾動(dòng)條觀感。小結(jié)與實(shí)戰(zhàn)要點(diǎn)要點(diǎn)結(jié)論切換判定feed.groups.length 2走輪播單組走網(wǎng)格FeedView.tsx虛擬化Virtuoso horizontalDirection僅掛載視口內(nèi)條目increaseViewportBy{200}預(yù)渲染懶加載每個(gè)分組初始僅請(qǐng)求約 12 張封面遠(yuǎn)端條目滾動(dòng)到附近才加載翻頁禁用像素scrollBy橫向 no-op 軌道懶尺寸改用scrollToIndex按索引分頁箭頭錨點(diǎn)以首個(gè)figure封面中線為top避免整行居中導(dǎo)致的視覺下沉滾動(dòng)條scoped.no-scrollbar隱藏軌道滾動(dòng)條箭頭用eink-bordered適配 E-ink卡片PublicationCard共享輪播/網(wǎng)格圓角封面 移除行內(nèi)徽標(biāo)徽標(biāo)移至PublicationView詳情頁測(cè)試jsdom 下 mockreact-virtuoso經(jīng)itemContent同步渲染全部條目?jī)H驗(yàn)證數(shù)據(jù)驅(qū)動(dòng)邏輯如果你要在其他基于 Virtuoso 的場(chǎng)景中實(shí)現(xiàn)橫向輪播請(qǐng)牢記本項(xiàng)目用實(shí)際調(diào)試換來的三條教訓(xùn)橫向模式用索引而非像素滾動(dòng)、箭頭狀態(tài)取自 atTop/atBottom 回調(diào)、行高必須先給默認(rèn)值再測(cè)量修正——這三條直接決定了輪播的可用性與視覺質(zhì)量。贊分享桌面應(yīng)用跨平臺(tái)前端【免費(fèi)下載鏈接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.項(xiàng)目地址https://gitcode.com/gh_mirrors/re/readest點(diǎn)擊查看免費(fèi)下載相關(guān)推薦react-native-swiper橫向與縱向切換實(shí)現(xiàn)多方向輪播功能react native swiper橫向與縱向切換實(shí)現(xiàn)多方向輪播功能 你是否在開發(fā)React Native應(yīng)用時(shí)遇到輪播組件只能單向滑動(dòng)的問題想讓圖片既能移動(dòng)開發(fā)UI組件如何快速掌握WCDB數(shù)據(jù)庫框架面向移動(dòng)開發(fā)者的完整指南如何快速掌握WCDB數(shù)據(jù)庫框架面向移動(dòng)開發(fā)者的完整指南 WCDBWeChat Database是騰訊微信團(tuán)隊(duì)開源的高性能跨平臺(tái)數(shù)據(jù)庫框架基于SQLite數(shù)據(jù)庫嵌入式數(shù)據(jù)庫ORM移動(dòng)開發(fā)Readest BooknoteView 虛擬化后的自動(dòng)滾動(dòng)回歸修復(fù)基于 Virtuoso 與 OverlayScrollbars 的最近標(biāo)注定位實(shí)踐Readest BooknoteView 虛擬化后的自動(dòng)滾動(dòng)回歸修復(fù)基于 Virtuoso 與 OverlayScrollbars 的最近標(biāo)注定位實(shí)踐 導(dǎo)讀桌面應(yīng)用跨平臺(tái)前端上一篇Node.js v0.6.13Stable發(fā)布全解libuv 跨平臺(tái)修復(fù)與 npm 1.1.9 升級(jí)下一篇OrcaSlicer 與 Simplify3D 功能對(duì)比專業(yè)用戶需求滿足度測(cè)評(píng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考