從去年底把通訊錄模塊重構(gòu)完到這次把城市選擇器、商品分類頁全部收斂到同一個(gè)索引列表方案上前前后后差不多磨了半年。這半年里RcIndexList 從最初一個(gè)只能“點(diǎn)字母跳分組”的雛形慢慢長成了現(xiàn)在既能處理多級分組、又能和雙列表聯(lián)動、還扛得住大數(shù)據(jù)量滾動刷新的通用組件。趁著這次把案例整理成冊把過程中踩過的坑、想通的設(shè)計(jì)、以及那些文檔里根本不會寫的細(xì)節(jié)一并沉淀下來。這篇進(jìn)階篇面向的是已經(jīng)用過 IndexList、或者至少對 ArkUI 列表類組件有基本認(rèn)識的開發(fā)者。如果你只是剛接觸 HarmonyOS 開發(fā)建議先跑一遍基礎(chǔ)組件的官方示例再回來看這篇否則很多優(yōu)化點(diǎn)和坑點(diǎn)會缺少上下文。我盡量把每個(gè)案例拆到“為什么要這么做”的層面而不是只給代碼。1. 為什么需要一個(gè)叫 RcIndexList 的索引列表組件1.1 通訊錄場景的三個(gè)硬需求最初的需求其實(shí)只有一個(gè)做一個(gè)帶字母索引的通訊錄。聽起來簡單但把需求拆開之后就變成三個(gè)繞不開的硬指標(biāo)。第一右側(cè)字母索引條必須常駐。用戶在快速找人時(shí)肌肉記憶會直接去點(diǎn)屏幕右側(cè)的字母如果索引條要滑動才出現(xiàn)體驗(yàn)上就廢了一半。第二列表滾動時(shí)索引條上的高亮字母必須同步變化而且不能滯后。第三按壓索引條時(shí)彈出的字母氣泡IndexPopup要跟手拖動到哪個(gè)字母氣泡就得立刻切到哪個(gè)字母。這三條分別對應(yīng)了索引條的繪制、列表滾動狀態(tài)的雙向綁定、以及手勢層級的處理。系統(tǒng)自帶的 IndexList 能解決一部分但做到“跟手”和“同步”這兩件事時(shí)自定義程度明顯不夠。IndexList 內(nèi)部把索引條和列表綁定得比較死想改索引條的布局、想接入雙列表聯(lián)動、想在滾動時(shí)做額外的狀態(tài)分發(fā)都會覺得施展不開。于是我們決定自己封裝底層列表仍用原生組件索引條和錨點(diǎn)定位邏輯自己做對外暴露一套簡潔的分組數(shù)據(jù)模型和回調(diào)。這樣既保留原生列表的滾動性能又把控制權(quán)收回到手中。1.2 組件邊界做什么不做什么封裝組件最容易犯的錯(cuò)是“什么都管”。RcIndexList 的設(shè)計(jì)初期就有三件事被明確排除在外不做數(shù)據(jù)源管理、不做網(wǎng)絡(luò)加載、不做業(yè)務(wù)占位樣式。它只做一件事把“分組數(shù)據(jù)”渲染成“可滾動、可定位、索引同步”的列表。數(shù)據(jù)源由調(diào)用方傳入組件內(nèi)部只維護(hù)分組結(jié)構(gòu)。調(diào)用方把數(shù)據(jù)按組整理好比如 contacts: { A: [張三, 張四], B: [李五], …… }組件負(fù)責(zé)遍歷渲染、計(jì)算錨點(diǎn)、響應(yīng)索引條事件。這樣做最直接的好處是接入成本低任何場景只要你能把數(shù)據(jù)整理成分組結(jié)構(gòu)就能直接用。底層技術(shù)上走的是“List 容器 sticky 標(biāo)題 自定義 overlay 索引條”的組合。為什么不直接用系統(tǒng) IndexBar因?yàn)槲覀円乃饕龡l在某些場景下是“熱”字、在某些場景下是“#”號甚至有些場景還要支持雙列索引。系統(tǒng)的 justifyContent 和布局規(guī)則沒法覆蓋這么多變體自己畫反而成本更低。// RcIndexList 對外暴露的最小接口示意 Component export struct RcIndexList { Prop groups: RcIndexGroup[]; // 分組數(shù)據(jù) Builder itemBuilder: (group: RcIndexGroup, index: number) void; // 列表項(xiàng)渲染 Builder indexBarBuilder?: (groups: RcIndexGroup[], activeKey: string) void; // 索引條渲染 Event onIndexChange?: (key: string) void; // 索引變化回調(diào) Event onScrollToIndex?: (groupIndex: number) void; // 滾動定位回調(diào) }2. 案例一通訊錄模塊的字母索引與錨點(diǎn)定位2.1 數(shù)據(jù)分組與索引 key 的生成通訊錄的分組邏輯看似簡單——按姓氏拼音首字母分組——但真正落地時(shí)有兩個(gè)坑多音字和特殊字符。多音字的典型例子是“單”姓讀“shàn”時(shí)歸入 S 組讀“dān”時(shí)歸入 D 組。項(xiàng)目里最終采用的方案是引入一個(gè)簡化的多音字姓氏映射表只覆蓋常見的高頻姓氏匹配不到就按當(dāng)前拼音庫的結(jié)果走。這個(gè)表一開始只加了十幾個(gè)姓后來通過用戶反饋逐步擴(kuò)充最終覆蓋了市面上絕大多數(shù)通訊錄場景。特殊字符和數(shù)字開頭的聯(lián)系人則統(tǒng)一歸到一個(gè)“#”組放在列表末尾。注意這里有個(gè)細(xì)節(jié)當(dāng)沒有特殊字符聯(lián)系人時(shí)“#”組不應(yīng)該出現(xiàn)在索引條上。所以索引條的數(shù)據(jù)源是“由實(shí)際分組數(shù)據(jù)推導(dǎo)出來的”而不是定義死的 26 個(gè)字母。interface ContactModel { name: string; phone: string; pinyin: string; // 預(yù)計(jì)算拼音 } function groupContacts(contacts: ContactModel[]): RcIndexGroup[] { const map new Mapstring, ContactModel[](); const special #; // 特殊字符組名 for (const contact of contacts) { const char contact.name.charCodeAt(0); const isLetter (char 65 char 90) || (char 97 char 122); let groupKey: string; if (isLetter) { groupKey contact.pinyin.charAt(0).toUpperCase(); } else { groupKey special; } if (!map.has(groupKey)) { map.set(groupKey, []); } map.get(groupKey)!.push(contact); } // 按字母序排列# 組固定放在最后 const keys Array.from(map.keys()).sort((a, b) { if (a special) return 1; if (b special) return -1; return a.localeCompare(b); }); return keys.map(key ({ key, items: map.get(key)!, isSpecial: key special })); }分組數(shù)據(jù)的 key 生成建議在數(shù)據(jù)進(jìn)列表之前完成不要在渲染時(shí)臨時(shí)算拼音。通訊錄這種場景數(shù)據(jù)量不大但商品類和城市類場景可能有上萬條數(shù)據(jù)渲染時(shí)臨時(shí)計(jì)算會造成可感知的卡頓。2.2 懸掛標(biāo)題與索引條聯(lián)動實(shí)現(xiàn)通訊錄的列表項(xiàng)需要“字母標(biāo)題在滾動時(shí)吸頂”這個(gè)在 ArkUI 里直接用 List 的 sticky 屬性就能做List({ space: 0, scroller: this.scroller }) { ForEach(this.groups, (group: RcIndexGroup, groupIndex: number) { ListItem() { Text(group.key) .fontSize(14) .width(100%) .padding({ left: 16, top: 8, bottom: 8 }) .backgroundColor(#F5F5F5) } .sticky(StickyStyle.Header) // 標(biāo)題吸頂關(guān)鍵屬性 ForEach(group.items, (item: ContactModel) { ListItem() { // 聯(lián)系人行的 UI 渲染 } }) }) }sticky 屬性加在 ListItem 上指定 Header 樣式即可實(shí)現(xiàn)吸頂效果。這比自己在滾動回調(diào)里計(jì)算偏移再補(bǔ)位要省事得多也是官方推薦做法。索引條聯(lián)動是這部分的重點(diǎn)。右側(cè)索引條用 overlay 疊加在 List 上方不參與布局。核心邏輯分成兩塊點(diǎn)擊/拖動索引條時(shí)跳轉(zhuǎn)到對應(yīng)分組列表滾動時(shí)反向更新索引條高亮。跳轉(zhuǎn)分組的實(shí)現(xiàn)依賴 scroller 的 scrollToIndex 方法因?yàn)?List 的 item 順序和分組順序是嚴(yán)格對應(yīng)的所以分組序號可以直接映射成 item 序號。這里有個(gè)精妙處由于 sticky 標(biāo)題占據(jù)了額外的布局空間直接 scrollToIndex 會讓目標(biāo)組停留在列表頂部恰好和吸頂標(biāo)題的位置重合視覺上完全無感。scrollToGroup(groupIndex: number) { // 需要補(bǔ)償?shù)谝粋€(gè)標(biāo)題的位置否則標(biāo)題會恰好頂在頂部被遮住 const targetIndex groupIndex * (itemsPerGroup 1); this.scroller.scrollToIndex(targetIndex, true, ScrollAlign.START); }2.3 字母氣泡IndexPopup的表現(xiàn)細(xì)節(jié)按壓索引條時(shí)的字母氣泡是體驗(yàn)好壞最直觀的地方。具體到實(shí)現(xiàn)氣泡本質(zhì)是一個(gè)跟隨手指位置移動的浮層里面顯示當(dāng)前命中的字母。這里有三點(diǎn)控制直接決定手感氣泡跟隨不跟手的主要原因是浮層更新和手勢事件的頻率不對齊。手指滑動的 onTouch 事件頻率遠(yuǎn)高于 UI 刷新的能力所以要在浮層里做一層緩沖記錄上一次顯示的字母只有字母變化時(shí)才更新狀態(tài)避免每幀都觸發(fā)重新渲染。氣泡的尺寸不要太小。我們試過 64vp 直徑在高速滑動時(shí)人眼容易丟失焦點(diǎn)最終定在 84vp 左右視覺上既不搶眼又能讓余光穩(wěn)定捕捉到字母變化。氣泡的圓角、陰影、背景透明度盡量做成參數(shù)暴露不要寫死在組件里。城市選擇器里我們用了完全不同的氣泡風(fēng)格方角、無陰影同一個(gè)組件的可配置性在這一刻體現(xiàn)出了價(jià)值。// 索引條按壓浮層的核心交互邏輯 .onTouch((event: TouchEvent) { if (event.type TouchType.Down || event.type TouchType.Move) { const y event.touch[0].y; const groupIndex this.getGroupIndexByPosition(y); if (groupIndex ! this.currentGroupIndex) { this.currentGroupIndex groupIndex; this.activeKey this.groups[groupIndex].key; this.popupVisible true; this.popupKey this.activeKey; } } else if (event.type TouchType.Up || event.type TouchType.Cancel) { this.popupVisible false; } })3. 案例二城市選擇器與多級分組數(shù)據(jù)3.1 熱門城市與字母分組的雙層結(jié)構(gòu)城市選擇器的數(shù)據(jù)結(jié)構(gòu)和通訊錄有一個(gè)本質(zhì)區(qū)別頂部多了一個(gè)“熱門城市”區(qū)域。這個(gè)區(qū)域不是普通分組它固定懸浮在列表上方不參與滾動也不出現(xiàn)在右側(cè)索引條上。如果簡單地把熱門城市作為列表的第一個(gè)分組那么“回到頂部”這個(gè)操作會先經(jīng)過熱門區(qū)再回到 A 組交互上多一步。更好的做法是熱門區(qū)作為一個(gè)獨(dú)立的容器放在 RcIndexList 外面滾動事件只作用于下方列表。這樣頂部區(qū)域天然固定下方的索引定位也完全不需要知道熱門區(qū)的存在。具體實(shí)現(xiàn)時(shí)頁面的 Column 結(jié)構(gòu)為頂部熱門區(qū)高度自適應(yīng)不滾動 中間狀態(tài)欄可選 下方 RcIndexList占滿剩余空間。城市列表沿用分組模型但有一個(gè)特殊處理索引條的最頂部增加一個(gè)“”符號代表“熱門”。點(diǎn)擊“”時(shí)列表滾動回頂部。這比把“熱門”作為第一個(gè)分組更合理因?yàn)椤盁衢T”不是字母也不是首字母分組的自然成員它在語義上屬于“快捷入口”而不是“分組”。3.2 特殊索引字符與分組偏移計(jì)算城市選擇器的另一個(gè)變體需求是索引條除了 A-Z 之外開頭有“*”熱門結(jié)尾通常還有“#”其他區(qū)縣、港澳臺或特殊地名。這意味著索引條的總高度、每個(gè)索引項(xiàng)的高度分配都跟通訊錄場景不一樣。RcIndexList 在處理索引條時(shí)不能寫死“每項(xiàng)高度相等”。實(shí)測下來當(dāng)城市數(shù)量多、索引項(xiàng)密的時(shí)候“*”和“#”如果和其他字母一樣高手指定位時(shí)容易誤觸。我們把特殊字符的項(xiàng)高度設(shè)置為字母項(xiàng)的 1.2 倍并在命中判斷時(shí)單獨(dú)處理點(diǎn)擊區(qū)域和視覺區(qū)域保持一致。分組偏移量計(jì)算是城市選擇器最容易出 bug 的地方。列表假設(shè)有 36 個(gè)分組26 個(gè)字母 熱門 數(shù)字 特殊 其他其中“熱門”并沒有占據(jù)列表的滾動位置而是懸浮在上方。因此索引條上“熱門”對應(yīng)的分組序號是 -1點(diǎn)擊時(shí)直接讓列表滾動到 offset 為 0 的位置而不是 scrollToIndex(-1)否則會崩潰或定位錯(cuò)亂。onIndexBarSelect(key: string) { if (key *) { this.listScroller.scrollEdge(Edge.Top); // 回到頂部 } else { const groupIndex this.groups.findIndex(g g.key key); if (groupIndex 0) { this.listScroller.scrollToIndex(this.getListItemIndex(groupIndex), true); } } }一個(gè)更隱蔽的問題是當(dāng)熱門區(qū)高度變化比如不同城市數(shù)量導(dǎo)致熱門區(qū)顯示 4 個(gè)或 6 個(gè)城市時(shí)列表的滾動區(qū)域高度不變但錨點(diǎn)位置會受影響嗎不會。因?yàn)闊衢T區(qū)在列表外面列表內(nèi)部的滾動錨點(diǎn)是獨(dú)立計(jì)算的只需關(guān)注當(dāng)前分組在列表內(nèi)的 item 序號即可。3.3 大列表全量刷新與數(shù)據(jù)重建開銷城市數(shù)據(jù)通常是省市區(qū)三級結(jié)構(gòu)一份全量數(shù)據(jù)大約兩三千條。在用戶切換省份時(shí)需要重新生成城市列表的分組數(shù)據(jù)。直接重建數(shù)組并推給 List會引發(fā)全量刷新代價(jià)不小。實(shí)測下來有三個(gè)優(yōu)化點(diǎn)收益最明顯。分組數(shù)據(jù)生成后用不可變數(shù)據(jù)結(jié)構(gòu)存儲每次切換省份只替換整個(gè)分組數(shù)組的引用而不是修改已有數(shù)組的項(xiàng)。單元格的 key 用穩(wěn)定 ID城市編碼而不是索引。這樣即使列表重建相同 key 的單元格也能被框架復(fù)用不會出現(xiàn)閃爍或位移。切換到省份時(shí)如果當(dāng)前已經(jīng)有列表位置優(yōu)先嘗試保持當(dāng)前位置的視覺連續(xù)性。做法是把當(dāng)前的滾動偏移按舊數(shù)據(jù)的總高度折算成新數(shù)據(jù)的近似偏移再 scrollToIndex。這個(gè)做過和沒做過用戶的感知差異非常大。onProvinceChange(newProvince: ProvinceModel) { const oldFirstVisible this.listScroller.currentOffset().yOffset; const oldTotalHeight this.totalListHeight; // 重新生成分組數(shù)據(jù) this.groups this.buildGroups(newProvince.cities); // 換算新的近似偏移 const ratio this.totalListHeight / oldTotalHeight; const approximateY oldFirstVisible * ratio; // 先恢復(fù)到近似位置再平滑調(diào)整 this.listScroller.scrollTo({ yOffset: approximateY, animated: false }); }這里要注意 ratio 的邊界當(dāng)舊列表高度為 0首次加載時(shí)ratio 會變成無窮大要兜底處理。這類邊界條件肉眼很難發(fā)現(xiàn)建議寫單元測試覆蓋。4. 案例三商品分類頁的雙列表聯(lián)動4.1 左右布局與滾動方向的定義商品分類頁是電商類應(yīng)用的標(biāo)配左側(cè)是分類軸右側(cè)是對應(yīng)分類下的商品列表。這里的“分類軸”在視覺效果上跟字母索引條很像但本質(zhì)上是另一個(gè) List。也就是說這個(gè)頁面是“兩個(gè) List 聯(lián)動”一個(gè)橫向意義上的狀態(tài)選擇器一個(gè)縱向滾動的商品流。RcIndexList 在這個(gè)場景下做了一個(gè)特殊的變體右側(cè)列表復(fù)用索引列表的分組模型但索引條不再浮在右側(cè)而是變成左側(cè)的獨(dú)立列表。這也是當(dāng)初設(shè)計(jì)時(shí)把索引條抽象成 builder 插槽的原因——同一個(gè)定位邏輯可以驅(qū)動完全不同的視覺形態(tài)。右側(cè)列表的分組和通訊錄一樣每組一個(gè)標(biāo)題 若干商品項(xiàng)。左側(cè)列表則是簡化版的一維 List。聯(lián)動關(guān)系只有一句話點(diǎn)擊左側(cè)分類右側(cè)滾動到對應(yīng)分組錨點(diǎn)右側(cè)滾動經(jīng)過分組標(biāo)題左側(cè)高亮同步切換到對應(yīng)分類。4.2 錨點(diǎn)滾動的兩種實(shí)現(xiàn)對比實(shí)現(xiàn)右側(cè)列表“滾到對應(yīng)分組”有兩種路線。第一種是把滾動偏移換算成分組在列表中的 item 索引然后 scrollToIndex。這也是 RcIndexList 通訊錄場景的默認(rèn)做法。問題在于當(dāng)商品列表項(xiàng)高度不一致不同商品卡片高度不同還有橫幅、活動位穿插時(shí)單純按索引定位可能不夠精確需要額外測量高度。第二種是直接 scrollToOffset把目標(biāo)分組的標(biāo)題偏移量作為 yOffset。實(shí)現(xiàn)這種方式需要預(yù)先測量每個(gè)分組在滾動容器中的偏移量商品數(shù)據(jù)變化后還要重新測量。代碼復(fù)雜度高但定位精度是絕對的。實(shí)測下來的結(jié)論是只要商品項(xiàng)不是異形高度差異特別大scrollToIndex 的精度完全夠用而且實(shí)現(xiàn)和調(diào)試成本都低得多。最終的落地方案是默認(rèn)走 scrollToIndex并在分組高度波動劇烈的特殊頁面里用 scrollToOffset 作為策略插件的另一套實(shí)現(xiàn)。// 策略插件的接口設(shè)計(jì) interface ScrollStrategy { scrollToGroup(groupIndex: number, scroller: Scroller): void; } class IndexScrollStrategy implements ScrollStrategy { scrollToGroup(groupIndex: number, scroller: Scroller) { const targetItemIndex groupIndex * (ITEMS_PER_GROUP 1); scroller.scrollToIndex(targetItemIndex, true, ScrollAlign.START); } } class OffsetScrollStrategy implements ScrollStrategy { private groupOffsets: number[] []; // 需要初始化時(shí)測量每個(gè)分組的位置 scrollToGroup(groupIndex: number, scroller: Scroller) { const offset this.groupOffsets[groupIndex] ?? 0; scroller.scrollTo({ yOffset: offset, animated: true }); } }4.3 左右狀態(tài)同步的節(jié)流與邊界處理右側(cè)滾動時(shí)左側(cè)高亮要跟著變。這個(gè)邏輯準(zhǔn)確說來自右側(cè)列表的 onScrollIndex 回調(diào)。onScrollIndex 會返回當(dāng)前顯示的第一個(gè) item 的索引但觸發(fā)頻率很高直接 setState 會發(fā)生肉眼可見的抖動和性能下降。節(jié)流方案不是簡單的“定時(shí)器限頻”而是結(jié)合“當(dāng)前可見項(xiàng)發(fā)生變化才更新狀態(tài)”去重。實(shí)踐代碼中維護(hù)一個(gè) lastGroupIndex只有 onScrollIndex 推導(dǎo)出的分組號發(fā)生變化時(shí)才更新左側(cè)高亮。此外還要加 200ms 的防抖保護(hù)當(dāng)快速連續(xù)滾動經(jīng)過多個(gè)分組時(shí)最后一次停留超過 200ms 才允許左側(cè)高亮跟隨避免視覺上“跳跳跳”的割裂感。邊界處理中有兩個(gè)極容易被忽略的場景。第一個(gè)是列表滾動到最底部時(shí)最后一個(gè)分組因?yàn)閮?nèi)容不足一屏onScrollIndex 可能永遠(yuǎn)無法觸達(dá)它的標(biāo)題序號導(dǎo)致左側(cè)最后一個(gè)分類一直無法高亮。解決辦法是判斷滾動到底部的回調(diào)一旦觸發(fā)就直接把左側(cè)高亮切到最后分類。第二個(gè)是左側(cè)分類點(diǎn)擊后右側(cè)的滾動動畫還沒結(jié)束用戶又快速點(diǎn)擊了下一個(gè)分類。如果不做打斷處理動畫會互相干擾列表最終停在錯(cuò)誤位置。處理方式是每次發(fā)起新的 scrollToIndex 調(diào)用的同時(shí)設(shè)置一個(gè)標(biāo)志位在下一個(gè) onScrollIndex 回調(diào)里消費(fèi)掉并清除標(biāo)志確保動畫執(zhí)行的連續(xù)性。onRightListScroll(index: number) { const currentGroup this.getGroupIndexByItemIndex(index); if (currentGroup this.lastGroupIndex) return; // 去重 this.lastGroupIndex currentGroup; // 防抖更新左側(cè)高亮 if (this.highlightTimer) clearTimeout(this.highlightTimer); this.highlightTimer setTimeout(() { this.leftActiveGroup currentGroup; }, 200); }5. RcIndexList 的核心機(jī)制與關(guān)鍵 API 深度解析5.1 分組數(shù)據(jù)模型與錨點(diǎn)映射機(jī)制索引列表能工作的本質(zhì)是維護(hù)了一張“分組 key → 列表 item 序號”的映射表。RcIndexList 內(nèi)部每次數(shù)據(jù)更新時(shí)會重建這張表映射關(guān)系需要保證 O(1) 查詢否則索引條高頻拖動時(shí)會卡。映射表的生成依賴分組數(shù)據(jù)每個(gè)分組是一個(gè) RcIndexGroup包含 groupKey 和 items 數(shù)組。列表的 item 序號并不是連續(xù)的分組序號而是要考慮“分組標(biāo)題行”占據(jù)的 item 位置。比如第一個(gè)分組有 10 個(gè)聯(lián)系人那么整個(gè)列表的 item 布局是標(biāo)題 0、聯(lián)系人 1-10、標(biāo)題 11、聯(lián)系人 12-……。所以從分組序號到 item 序號的計(jì)算公式是itemIndex groupIndex sum(itemsCount[0..groupIndex-1])這個(gè)計(jì)算在數(shù)據(jù)量大時(shí)可以提前做好存放在錨點(diǎn)映射數(shù)組里。索引條點(diǎn)擊響應(yīng)時(shí)直接用數(shù)組下標(biāo)取出目標(biāo) itemIndex不需要遍歷。性能測試中3000 條數(shù)據(jù)、36 個(gè)分組的情況下整個(gè)查找過程耗時(shí)低于 0.1ms完全可以支撐高頻拖動。5.2 索引條自繪與浮層技術(shù)索引條為什么必須自繪系統(tǒng)組件能顯示字母但我們還需要顯示“*”“#”“熱”等特殊字符需要自定義背景色、按壓圓角、氣泡定位參考點(diǎn)甚至在某些場景要支持分段顏色高亮。與其被限制不如用 Row/Column 布局自己畫。核心繪制邏輯就是一個(gè) Column遍歷分組 key 列表逐個(gè)渲染文本項(xiàng)。自繪索引條需要處理一個(gè)關(guān)鍵問題觸摸事件。索引條懸浮在 List 上方如果不處理事件沖突手指按住索引條時(shí) List 也會收到滑動事件導(dǎo)致列表跟著滾動。這里要在索引條上使用 priorityGesture 搶占手勢并在手勢識別成功后阻止 List 的事件分發(fā)。ArkUI 中手勢優(yōu)先級從高到低依次是 priorityGesture 普通 gesture 子組件默認(rèn)手勢。把 onTouch 綁定在索引條上配合 gesture 的并行識別可以保證索引條手勢優(yōu)先響應(yīng)列表滾動。IndexBar() .priorityGesture(Gesture.create(GestureType.Touch)) .gesture( Gesture.create(GestureType.Touch) .onAction((event: GestureEvent) { // 索引條自身的手勢處理 }) )需要注意的是priorityGesture 雖然優(yōu)先識別但默認(rèn)情況下并不會阻斷 List 的滾動事件。想要阻斷需要在手勢的 onTouch 事件里手動處理“列表不再響應(yīng)”的狀態(tài)或者在 overlay 浮層上增加一塊透明區(qū)域攔截事件。前者實(shí)現(xiàn)簡單后者視覺表現(xiàn)更細(xì)膩索引條以外的半透明遮罩區(qū)域也能響應(yīng)關(guān)閉。5.3 Builder 插槽與數(shù)據(jù)刷新機(jī)制RcIndexList 的易用性很大程度來自 Builder 插槽設(shè)計(jì)。分組標(biāo)題、列表項(xiàng)、索引條、氣泡浮層四件事全部可以外部注入渲染。這樣組件本身只負(fù)責(zé)狀態(tài)和聯(lián)動具體長什么樣由調(diào)用方?jīng)Q定。這里有一個(gè)性能上的建議Builder 插槽的內(nèi)容如果包含復(fù)雜業(yè)務(wù)組件務(wù)必用 Builder 函數(shù)聲明而不是直接寫成子組件節(jié)點(diǎn)。實(shí)測中Builder 的編譯期優(yōu)化能讓列表項(xiàng)渲染性能提升 30% 左右尤其對 1000 條以上數(shù)據(jù)的場景效果明顯。數(shù)據(jù)刷新方面RcIndexList 內(nèi)部對分組數(shù)據(jù)的變更做了“整組替換而不是逐項(xiàng)修改”的約定。調(diào)用方傳新的 groups 數(shù)組時(shí)組件先比對 groupKey 列表是否一致。一致則只刷新對應(yīng)組內(nèi)的 items不一致則整個(gè)列表重建。這個(gè)邏輯用簡單的引用比較 淺層 diff 就能顯著降低無效刷新。Watch(onGroupsChange) groups: RcIndexGroup[] []; onGroupsChange() { const newKeys this.groups.map(g g.key); if (this.groupKeys.length newKeys.length this.groupKeys.every((k, i) k newKeys[i])) { this.updateItemMap(); // 分組結(jié)構(gòu)不變只更新錨點(diǎn)映射 } else { this.rebuildAll(); // 分組結(jié)構(gòu)變化整體重建 } }6. 半年踩坑實(shí)錄這些偏離文檔的細(xì)節(jié)最費(fèi)時(shí)間6.1 分組項(xiàng)無法準(zhǔn)確跳到列表項(xiàng)的根因這個(gè)坑斷斷續(xù)續(xù)折騰了兩天才定位?，F(xiàn)象是點(diǎn)擊索引條的“W”分組列表滾到了 X 組或者 V 組附近就是不落在 W 組標(biāo)題上。排查后發(fā)現(xiàn)根因是 scrollToIndex 的目標(biāo) index 算錯(cuò)了。通訊錄場景的分組映射公式?jīng)]有問題但商品分類頁的水平布局里左側(cè)分類列表本身也參與滾動計(jì)算導(dǎo)致右側(cè)列表的起始偏移不為 0。錨點(diǎn)映射表只計(jì)算了右側(cè)列表內(nèi)部的 item 序號卻忽略了外部容器的滾動偏移。最終解決方案是給 RcIndexList 增加一個(gè) optional 的 startOffset 參數(shù)當(dāng)容器存在頂部偏移時(shí)動態(tài)修正目標(biāo)偏移量。這個(gè)問題也給后續(xù)所有嵌套滾動場景提了個(gè)醒錨點(diǎn)計(jì)算永遠(yuǎn)要基于“列表內(nèi)容在滾動容器中的絕對位置”不能假設(shè)內(nèi)容從 0 開始。6.2 索引條高亮跳變與防抖閾值設(shè)置滾動列表時(shí)索引條的高亮字母偶發(fā)地快速左右跳動。比如明明滾動經(jīng)過的是 B 組高亮卻瞬間閃到 C 組又跳回 B 組。定位過程發(fā)現(xiàn) onScrollIndex 的回調(diào)頻率在某些設(shè)備尤其是低端機(jī)上會低至每幀一次同時(shí)也存在一幀內(nèi)多次回調(diào)。當(dāng)回調(diào)序號正好落在相鄰分組的交界處時(shí)分組判斷函數(shù)會在兩個(gè)分組之間反復(fù)橫跳。處理方式不只是加防抖而是給“判斷當(dāng)前分組”加上變化容忍度只有當(dāng)前分組連續(xù) 3 次回調(diào)都指向同一個(gè)新分組時(shí)才正式切換狀態(tài)。這個(gè)改動讓高亮變得穩(wěn)定代價(jià)是切換延遲僅有約兩幀肉眼基本無感。6.3 自繪索引條點(diǎn)擊事件和 List 滾動的沖突自己畫索引條后一個(gè)必然遇到的問題就是按住索引條上下滑動時(shí)下方的 List 也同時(shí)在滾動。RcIndexList 最初版本的做法是索引條手勢識別后手動設(shè)置 List 的 enabled(false)抬手再恢復(fù)。這個(gè)方案簡單粗暴但用戶體驗(yàn)有明顯頓挫感。更好的做法是用 ArkUI 的并行手勢 事件攔截。讓索引條區(qū)域的手勢事件直接進(jìn)入自己的處理邏輯同時(shí)阻止 List 接收觸摸事件不改變 List 的可用狀態(tài)。這樣 List 不會產(chǎn)生慣性滾動抬手后的停留位置也是精確的。另外還要處理一個(gè)細(xì)節(jié)按壓索引條時(shí)如果彈出氣泡氣泡要覆蓋在索引條本身上方更高 zIndex如果不彈氣泡索引條自身要做按壓態(tài)背景反饋否則用戶感受不到“已經(jīng)按住了”。6.4 懶加載與全量刷新的矛盾處理引入 LazyForEach 后分組數(shù)據(jù)量大時(shí)滾動性能確實(shí)上來了但隨之而來的問題是“數(shù)據(jù)更新后舊位置的錨點(diǎn)失效”。比如分組 B 增加了 10 條數(shù)據(jù)列表項(xiàng)序號整體后移之前緩存的分組偏移表全部過期。這里我的建議是不要試圖在懶加載模式下做復(fù)雜的局部增量映射更新這在復(fù)雜度上不值得。分組數(shù)據(jù)的變動頻率遠(yuǎn)低于列表項(xiàng)數(shù)據(jù)的變動頻率所以每次分組變動直接重建錨點(diǎn)映射表即可。因?yàn)殄^點(diǎn)映射表只是一組整數(shù)數(shù)組重建成本遠(yuǎn)低于重新渲染列表。真正的性能熱點(diǎn)在列表項(xiàng)的渲染不在映射表的生成。此外LazyForEach 的數(shù)據(jù)源需要實(shí)現(xiàn) ID 生成規(guī)則。如果 ID 不穩(wěn)定比如根據(jù) items 數(shù)組重建時(shí)每個(gè)對象都生成新 IDLazyForEach 會退化成全量刷新。穩(wěn)定 ID 的做法是給每個(gè)數(shù)據(jù)實(shí)體綁定一個(gè)持久化的業(yè)務(wù)主鍵城市用 adcode聯(lián)系人用手機(jī)號商品用 skuId。class ContactDataSource extends DataSource { public totalCount(): number { return this.contacts.length; } public getData(index: number): ContactModel { return this.contacts[index]; } public getDataId(index: number): string { // 用業(yè)務(wù)主鍵作為穩(wěn)定 ID避免全量失效 return this.contacts[index].phone; } }7. 后續(xù)還能怎么擴(kuò)展RcIndexList 目前已經(jīng)在多個(gè)核心頁面落地但它的擴(kuò)展空間還很大。一個(gè)是“索引條搜索模式”在索引條頂部加一個(gè)放大鏡圖標(biāo)點(diǎn)擊后列表平滑切換到搜索輸入框。這本質(zhì)上是在索引條事件里增加一個(gè)特殊 key 的分支處理組件結(jié)構(gòu)完全兼容。另一個(gè)是“自定義排序規(guī)則”默認(rèn)按字母但某些場景需要按熱度、按價(jià)格段、按時(shí)間軸分組。分組 key 的生成邏輯不在組件內(nèi)部所以只要調(diào)用方在分組數(shù)據(jù)中給出正確的 keyRcIndexList 就能原樣渲染索引條照樣工作。還有一個(gè)真正有價(jià)值的方向把錨點(diǎn)映射表暴露出來讓外部組件也能利用“分組 key 定位列表”的能力。比如商家門店列表和商品列表聯(lián)動、多 Tab 場景中的子頁聯(lián)動。這半年打磨下來我最深的體會有兩點(diǎn)一是索引列表的核心競爭力在“狀態(tài)同步”而不在“單點(diǎn)定位”任何一處沒有考慮滾動邊界都會在真機(jī)的高頻交互里露餡二是組件封裝不要貪多數(shù)據(jù)層、業(yè)務(wù)層和表現(xiàn)層的邊界劃清楚了后面加減功能都會很輕松。希望這份案例集能給正在做同類需求的開發(fā)者一些參考少走幾個(gè)我已經(jīng)趟平的坑。