必會(huì)：詳解ArkUI @Builder與Builder設(shè)計(jì)模式)
1. 先分清 Builder 的兩種身份不然你后面會(huì)越看越亂前陣子在重構(gòu)一個(gè)鴻蒙項(xiàng)目的首頁(yè)時(shí)我發(fā)現(xiàn)團(tuán)隊(duì)里關(guān)于 Builder 的討論特別多。有人說“用 Builder 封裝一個(gè)頭部組件”有人說“我的 Builder 實(shí)現(xiàn)了一個(gè)復(fù)雜對(duì)象”還有人拿著一張 SketchUp 的報(bào)錯(cuò)截圖來(lái)問是不是 HarmonyOS 的問題。后來(lái)我意識(shí)到大家口中的 Builder 不只是同一個(gè)東西在鴻蒙開發(fā)里它既是 ArkUI 聲明式框架里的Builder 裝飾器又是設(shè)計(jì)模式里的建造者模式甚至在一些第三方工具里也出現(xiàn)過同名概念。對(duì)于做 HarmonyOS 原生應(yīng)用的人來(lái)說最常打交道的其實(shí)是 ArkUI 提供的Builder 自定義構(gòu)建函數(shù)。它的核心作用是把一段 UI 描述封裝成一個(gè)函數(shù)在多個(gè)頁(yè)面或組件內(nèi)復(fù)用避免重復(fù)寫同樣的布局代碼。而設(shè)計(jì)模式里的 Builder更多是用在 ArkTS 的數(shù)據(jù)建模、復(fù)雜參數(shù)構(gòu)建上跟 UI 不直接相關(guān)但工程上也很實(shí)用。所以這篇文章我打算把兩件事串起來(lái)講前面五個(gè)部分全部圍繞 ArkUI 的 Builder 展開包括全局 Builder、局部 Builder、參數(shù)傳遞、BuilderParam 和尾隨閉包最后一部分再重點(diǎn)聊一下 Builder 設(shè)計(jì)模式在 ArkTS 工程中的落地場(chǎng)景。這樣不管你是剛?cè)腴T的新手還是已經(jīng)寫了幾個(gè)月鴻蒙頁(yè)面但一直沒把 Builder 理清的老手都能找到自己需要的答案。2. 全局自定義構(gòu)建函數(shù)最常用也最容易被忽略的細(xì)節(jié)2.1 全局 Builder 的聲明方式全局 Builder 是定義在組件外部的函數(shù)它的作用域是整個(gè)模塊。你可以把它當(dāng)作一段“UI 模板”在任何組件里直接調(diào)用。// GlobalBuilder.ets Builder export function GlobalHeaderBuilder($$: { title: string }) { Row() { Text($$.title) .fontSize(20) .fontWeight(FontWeight.Bold) Blank() Text(更多) .fontSize(14) .fontColor(#999) } .width(100%) .padding({ left: 16, right: 16, top: 12, bottom: 12 }) .backgroundColor(#F5F5F5) }調(diào)用時(shí)不需要new也不需要實(shí)例化直接在 build 方法里寫Component struct IndexPage { build() { Column() { GlobalHeaderBuilder({ title: 首頁(yè) }) // 其他內(nèi)容 } } }這里的參數(shù)傳遞用了$$語(yǔ)法后面會(huì)單獨(dú)講但先記住一個(gè)結(jié)論如果希望 Builder 內(nèi)部對(duì)參數(shù)的修改能同步到外層狀態(tài)或者希望依賴的狀態(tài)變量可以雙向聯(lián)動(dòng)建議使用$$。2.2 全局 Builder 的優(yōu)勢(shì)和坑全局 Builder 最大的優(yōu)勢(shì)是跨組件復(fù)用。多個(gè)頁(yè)面里只要有相同的頁(yè)頭、空狀態(tài)、錯(cuò)誤提示都可以抽出來(lái)做成全局 Builder。我習(xí)慣把項(xiàng)目中通用的 UI 片段全部放到一個(gè)common/builders目錄下按功能命名比如EmptyStateBuilder、ErrorStateBuilder、PageHeaderBuilder。但全局 Builder 有一個(gè)非常容易踩的坑它不能訪問組件內(nèi)部的State變量。因?yàn)槿趾瘮?shù)沒有綁定到任何一個(gè)組件實(shí)例上所以想從組件里把狀態(tài)傳給全局 Builder只能通過參數(shù)傳進(jìn)去。如果你在全局 Builder 里直接使用this編譯階段就直接報(bào)錯(cuò)。所以我一般只在以下場(chǎng)景使用全局 Builder頁(yè)面級(jí)通用頭部、底部。下拉刷新、加載失敗、空數(shù)據(jù)等與業(yè)務(wù)狀態(tài)解耦的占位 UI。需要在多個(gè)Entry頁(yè)面里復(fù)用的純展示型組件片段。如果某段 UI 強(qiáng)依賴當(dāng)前組件的狀態(tài)、需要調(diào)用當(dāng)前組件的方法或者需要和組件的生命周期聯(lián)動(dòng)我的建議是不要用全局 Builder直接用局部 Builder也就是下面第三部分要說的內(nèi)容。3. 組件內(nèi)自定義構(gòu)建函數(shù)狀態(tài)訪問更自由的局部 Builder3.1 在組件內(nèi)部聲明 Builder局部 Builder 就是把Builder函數(shù)寫在組件struct的內(nèi)部。由于它定義在當(dāng)前組件實(shí)例中所以可以直接訪問this包括State、Prop、Link以及普通成員變量和方法。Component struct ProductCard { State productName: string HarmonyOS 實(shí)戰(zhàn)指南 Builder ProductCardContent() { Column() { Text(this.productName) .fontSize(16) .fontColor(#333) Text(點(diǎn)擊查看詳情) .fontSize(12) .fontColor(#666) } .padding(12) .backgroundColor(#FFFFFF) .borderRadius(8) } build() { Column() { // 直接調(diào)用 this.ProductCardContent() } .padding(16) } }這個(gè)例子雖然簡(jiǎn)單但它體現(xiàn)了局部 Builder 最核心的價(jià)值Builder 內(nèi)部和組件共享同一個(gè)上下文。當(dāng)你修改productName時(shí)Builder 內(nèi)的Text會(huì)自動(dòng)更新不需要你手動(dòng)同步任何參數(shù)。3.2 局部 Builder 為什么能做到狀態(tài)同步很多初學(xué)者會(huì)問this.ProductCardContent()不就是一個(gè)函數(shù)調(diào)用嗎為什么狀態(tài)變了它會(huì)自動(dòng)刷新這里要注意ArkUI 的 Builder 并不是普通的函數(shù)。它在編譯階段會(huì)被框架特殊處理成為渲染樹的一部分。當(dāng)組件狀態(tài)變化時(shí)框架會(huì)依據(jù)狀態(tài)依賴關(guān)系定位到具體的 UI 組件而不是把整個(gè) build 方法重新執(zhí)行一遍。換句話說Builder 內(nèi)部的Text和build()里的組件一樣都建立在相同的狀態(tài)跟蹤基礎(chǔ)之上。這就帶來(lái)一個(gè)很實(shí)用的技巧如果某個(gè)區(qū)域的 UI 邏輯特別復(fù)雜或者被if/else、ForEach包裹得很亂可以單獨(dú)拆成一個(gè)局部 Builder讓代碼可讀性提升不少。但注意局部 Builder 不適合在多個(gè)不同組件之間復(fù)用因?yàn)橐坏?A 組件寫的 Builder 想拿到 B 組件里用就要改成全局 Builder或者提取成公共組件。4. 參數(shù)傳遞默認(rèn)值、值傳遞和 $$ 引用傳遞一次搞明白4.1 基礎(chǔ)參數(shù)傳遞與默認(rèn)值Builder 函數(shù)也支持普通參數(shù)和默認(rèn)值。比如Builder function InfoBuilder(content: string 默認(rèn)文案, showIcon: boolean true) { Row({ space: 8 }) { if (showIcon) { Text(●) } Text(content) } }調(diào)用時(shí)可以不傳參InfoBuilder()也可以傳部分參數(shù)InfoBuilder(自定義文案, false)但這里有兩個(gè)規(guī)則要記牢Builder 函數(shù)參數(shù)不能同時(shí)使用按引用傳遞和按值傳遞的混寫方式。要么全部用普通參數(shù)值傳遞要么使用$$對(duì)象形式引用傳遞。參數(shù)默認(rèn)值只支持普通參數(shù)類型比如字符串、數(shù)字、布爾值不支持?jǐn)?shù)組、對(duì)象類型。如果默認(rèn)值是一個(gè)動(dòng)態(tài)狀態(tài)變量那就不能用默認(rèn)值機(jī)制必須顯式傳入。4.2 用 $$ 實(shí)現(xiàn)引用傳遞官方推薦的傳參方式之一是把參數(shù)包裝成一個(gè)對(duì)象并在參數(shù)名稱前加$$?？催@個(gè)例子Builder function ClickableTextBuilder($$: { count: number }) { Button(點(diǎn)擊次數(shù)${$$.count}) .onClick(() { $$.count }) }父組件里這樣用Component struct CounterPage { State total: number 0 build() { Column() { ClickableTextBuilder({ count: this.total }) Text(父組件計(jì)數(shù)${this.total}) } } }當(dāng) Builder 內(nèi)部修改了$$.count父組件的total也會(huì)跟著變因?yàn)檫@里的$$表示引用傳遞this.total和$$.count指向同一個(gè)狀態(tài)源。如果你不用$$直接寫成ClickableTextBuilder({ count: this.total }) // 但函數(shù)定義是普通參數(shù) function ClickableTextBuilder(count: number) { ... }那么 Builder 內(nèi)部拿到的是.total的一個(gè)快照不管怎么修改都不會(huì)影響父組件。這對(duì)某些只讀展示的場(chǎng)景是合理的但如果期望在 Builder 內(nèi)觸發(fā)狀態(tài)更新就必須用$$。我在實(shí)際開發(fā)里幾乎都統(tǒng)一用$$對(duì)象傳參避免踩“改半天沒反應(yīng)”的坑。4.3 值傳遞和引用傳遞應(yīng)該如何選擇選擇規(guī)則其實(shí)很短如果 Builder 只是展示不修改入?yún)⒂闷胀▍?shù)足夠。如果 Builder 內(nèi)部需要修改入?yún)⒉⑼礁附M件用$$。如果參數(shù)是State、Link等狀態(tài)變量的引用建議用$$確保聯(lián)動(dòng)。如果一個(gè) Builder 有七八個(gè)參數(shù)強(qiáng)烈建議全部放進(jìn)一個(gè)$$對(duì)象里管理。這樣調(diào)用時(shí)的代碼看著像一個(gè)配置對(duì)象語(yǔ)義清晰也不容易把參數(shù)順序搞錯(cuò)。5. BuilderParam把 UI 片段當(dāng)參數(shù)傳進(jìn)門5.1 理解 BuilderParam 的插槽思想BuilderParam是 Builder 的進(jìn)階版它解決的場(chǎng)景非常直接父組件想往子組件里塞一段自定義 UI而不是塞一個(gè)值。熟悉前端的開發(fā)者一眼就能認(rèn)出來(lái)這就是“插槽”思路。舉個(gè)例子有一個(gè)通用卡片組件卡片上半部分是固定的標(biāo)題欄下半部分需要父組件自由填充內(nèi)容。我可以這樣設(shè)計(jì)Component export struct CardContainer { BuilderParam contentBuilder: () void build() { Column() { Text(卡片標(biāo)題) .fontSize(18) .fontWeight(FontWeight.Bold) Divider() // 這里渲染父組件傳入的 UI 片段 this.contentBuilder() } .padding(16) .backgroundColor(#FFFFFF) .borderRadius(12) } }父組件通過BuilderParam把自定義內(nèi)容傳進(jìn)來(lái)Builder function CustomContentBuilder() { Column() { Text(自定義區(qū)域) Button(按鈕) } } Component struct ParentPage { build() { Column() { CardContainer({ contentBuilder: CustomContentBuilder }) } } }這里的contentBuilder類型是() void意思是“一個(gè)沒有參數(shù)的構(gòu)建函數(shù)”。父組件傳一個(gè) Builder 函數(shù)進(jìn)去子組件在合適的位置調(diào)用它。5.2 初始化方式一通過普通參數(shù)傳入第一種是上面這種直接把一個(gè)已有 Builder 作為參數(shù)傳入。這種方式在父組件內(nèi)部已經(jīng)定義好一段 UI 時(shí)最自然。5.3 初始化方式二尾隨閉包第二種在 API 10 之后非常常用就是“尾隨閉包”寫法。如果子組件的最后一個(gè)參數(shù)是BuilderParam可以直接在子組件后面跟一個(gè)花括號(hào)里面寫 UICardContainer() { // 這里的內(nèi)容會(huì)傳給 contentBuilder Row({ space: 8 }) { Text(自定義標(biāo)題) Image($r(app.media.icon)) .width(24) .height(24) } }這種方式閱讀起來(lái)特別像普通布局代碼父組件不需要單獨(dú)定義一個(gè) Builder 函數(shù)代碼更緊湊。我個(gè)人在寫通用列表項(xiàng)、彈窗內(nèi)容、頁(yè)面骨架時(shí)非常喜歡這種寫法因?yàn)樗选白咏M件的固定部分”和“父組件的自定義部分”分得很開。5.4 幾個(gè)容易踩的初始化細(xì)節(jié)BuilderParam有一些隱藏規(guī)則新手經(jīng)常在這里翻車子組件的 BuilderParam 數(shù)量不能太多。雖說不限制數(shù)量但超過兩個(gè)后調(diào)用代碼的可讀性會(huì)急劇下降。如果確實(shí)需要多個(gè)插槽建議用普通 Builder 傳參給子組件再在子組件內(nèi)部用 if 處理不同區(qū)域。BuilderParam 參數(shù)名如果在初始化時(shí)沒有傳也不會(huì)有默認(rèn)值。如果父組件沒傳contentBuilder子組件調(diào)用this.contentBuilder()時(shí)會(huì)報(bào)錯(cuò)。因此對(duì)于某些可選插槽我會(huì)在子組件內(nèi)部提供一個(gè)默認(rèn) Builder 兜底。尾隨閉包方式和普通參數(shù)方式不能同時(shí)使用。一個(gè) BuilderParam 只能選擇一種傳入方式初始化。// 錯(cuò)誤的寫法既有參數(shù)傳入又寫了尾隨閉包 CardContainer({ contentBuilder: CustomContentBuilder }) { Text(這段閉包不生效) }這種代碼編譯不會(huì)直接報(bào)錯(cuò)但閉包內(nèi)容會(huì)被忽略排查起來(lái)很浪費(fèi)時(shí)間。5.5 實(shí)際案例做一個(gè)可定制彈窗外殼我項(xiàng)目中有一個(gè)通用彈窗組件外層有遮罩、圓角容器、動(dòng)畫內(nèi)部?jī)?nèi)容完全由調(diào)用方?jīng)Q定。用 BuilderParam 做起來(lái)非常清爽Component export struct CommonDialog { BuilderParam dialogContent: () void build() { Stack() { // 遮罩 Column() .width(100%) .height(100%) .backgroundColor(rgba(0, 0, 0, 0.4)) .onClick(() { /* 關(guān)閉邏輯 */ }) // 彈窗內(nèi)容 Column() { this.dialogContent() } .padding(20) .backgroundColor(#FFF) .borderRadius(16) .margin({ left: 24, right: 24 }) } } }使用方只需要傳具體內(nèi)容CommonDialog() { Column({ space: 12 }) { Text(確定要?jiǎng)h除這條數(shù)據(jù)嗎) Row({ space: 20 }) { Button(取消) Button(刪除) } } }這樣彈窗的交互框架和業(yè)務(wù)內(nèi)容完全解耦新增任何彈窗都不需要再改彈窗容器代碼。6. 實(shí)戰(zhàn)避坑Builder 狀態(tài)不刷新、循環(huán)構(gòu)建和參數(shù)失效問題6.1 狀態(tài)更新不生效的經(jīng)典場(chǎng)景有網(wǎng)友和我反饋過一個(gè)問題在 Builder 里用setInterval修改一個(gè)普通變量界面不刷新?？吹酱a后發(fā)現(xiàn)他用的是普通成員變量沒有用State裝飾。這是理解上的誤區(qū)Builder 負(fù)責(zé)復(fù)用 UI 描述但不負(fù)責(zé)“魔法化”所有變量。想要 Builder 里的 UI 感知數(shù)據(jù)變化數(shù)據(jù)源必須是狀態(tài)變量State、Prop、Link、Provide等或者能被框架觀察到的對(duì)象屬性。排查 Builder 不刷新問題我一般按這個(gè)順序查數(shù)據(jù)變量是否加了State或Observed傳遞參數(shù)是否用了$$引用傳遞如果用了值傳遞Builder 內(nèi)部再改也不會(huì)觸發(fā)父組件更新。Builder 內(nèi)部是否使用了this全局 Builder 里訪問不到組件狀態(tài)所以只能靠傳參。如果是對(duì)象屬性更新對(duì)象是否實(shí)現(xiàn)了Observed并且屬性在類內(nèi)部聲明6.2 在 LazyForEach 和列表項(xiàng)中使用 Builder列表頁(yè)是 Builder 的高頻場(chǎng)景。很多人把列表項(xiàng)寫成普通Component然后通過ForEach循環(huán)渲染。這沒問題但如果列表項(xiàng)只是一段靜態(tài) UI且不需要獨(dú)立狀態(tài)用 Builder 會(huì)更輕量。Builder function ProductItemBuilder(item: ProductModel) { Row({ space: 12 }) { Image(item.cover) .width(80) .height(80) .borderRadius(8) Column() { Text(item.name) .fontSize(16) Text(item.price) .fontSize(14) .fontColor(#E84026) } .alignItems(HorizontalAlign.Start) } .width(100%) .padding(10) }在LazyForEach中使用時(shí)我會(huì)把 Builder 直接放在LazyForEach的子項(xiàng)生成區(qū)域里L(fēng)azyForEach(this.productDataSource, (item: ProductModel, index: number) { ProductItemBuilder(item) })這里有一個(gè)經(jīng)驗(yàn)如果列表項(xiàng)內(nèi)部還需要點(diǎn)擊跳轉(zhuǎn)、需要訪問當(dāng)前組件的路由方法建議寫成組件而不是 Builder。因?yàn)?Builder 里很難方便地處理生命周期和事件上下文強(qiáng)行用 Builder 反而會(huì)增加復(fù)雜度。6.3 常見問題速查表現(xiàn)象可能原因推薦解法Builder 內(nèi)部修改數(shù)據(jù)不刷新變量不是狀態(tài)變量改用 State 或 Observed父組件傳入?yún)?shù)后 Builder 里改不動(dòng)沒有用 $$ 引用傳遞修改參數(shù)為 $$ 對(duì)象形式全局 Builder 訪問 this 報(bào)錯(cuò)全局作用域沒有組件實(shí)例改為組件內(nèi)局部 Builder 或通過參數(shù)傳入BuilderParam 沒有渲染內(nèi)容初始化方式?jīng)_突或未傳值檢查是否用普通參數(shù)和尾隨閉包混用Builder 內(nèi) ForEach 多次渲染后卡頓每次調(diào)用都創(chuàng)建了新數(shù)組使用 LazyForEach 并確認(rèn)數(shù)據(jù)源 ID 穩(wěn)定Builder 內(nèi)使用路由方法報(bào)錯(cuò)缺少組件上下文改為 Component 并在 build 中調(diào)用6.4 一個(gè)容易被忽略的編譯約束Builder 函數(shù)內(nèi)不能使用Builder裝飾的變量其實(shí)不是。但有一個(gè)規(guī)則值得注意在 Builder 內(nèi)定義局部狀態(tài)變量是不允許的。比如Builder function WrongBuilder() { State value: number 0 // 編譯報(bào)錯(cuò) Text(錯(cuò)誤示例) }狀態(tài)變量必須要放在組件結(jié)構(gòu)體的頂層Builder 只是一個(gè)構(gòu)建函數(shù)不能擁有自己的狀態(tài)存儲(chǔ)。如果需要局部狀態(tài)可以新建一個(gè)獨(dú)立的Component子組件把 Builder 區(qū)域替換成組件調(diào)用。這也是為什么很多時(shí)候組件和 Builder 要按場(chǎng)景取舍而不是一味追求“全部用 Builder 封裝”。6.5 代碼組織上的建議項(xiàng)目里 Builder 多起來(lái)以后命名和文件組織特別重要。我的習(xí)慣是全局 Builder 文件名用*Builder.ets命名如ListEmptyBuilder.ets。Builder 函數(shù)名用“用途 Builder”后綴如EmptyStateBuilder、ErrorStateBuilder。局部 Builder 放在組件結(jié)構(gòu)體底部和build()方法分開用注釋塊分隔。只在同一個(gè).ets文件里使用的 Builder優(yōu)先做成局部 Builder不導(dǎo)出到全局。7. 順手聊聊 Builder 設(shè)計(jì)模式在 ArkTS 工程里的應(yīng)用7.1 數(shù)據(jù)對(duì)象構(gòu)造場(chǎng)景ArkUI 開發(fā)中經(jīng)常要構(gòu)造復(fù)雜的請(qǐng)求參數(shù)、表單提交對(duì)象、或者一個(gè)包含多個(gè)配置項(xiàng)的數(shù)據(jù)模型。直接用構(gòu)造函數(shù)傳參參數(shù)一多代碼就變得難讀而且容易傳錯(cuò)順序。這時(shí)候就可以用 Builder 設(shè)計(jì)模式。比如有一個(gè)UserProfile對(duì)象class UserProfile { name: string age: number 0 email: string phone: string address: string }用 Builder 模式封裝后class UserProfileBuilder { private profile: UserProfile new UserProfile() setName(name: string): UserProfileBuilder { this.profile.name name return this } setAge(age: number): UserProfileBuilder { this.profile.age age return this } setEmail(email: string): UserProfileBuilder { this.profile.email email return this } setPhone(phone: string): UserProfileBuilder { this.profile.phone phone return this } build(): UserProfile { return this.profile } }調(diào)用時(shí)就很舒服const user new UserProfileBuilder() .setName(張三) .setAge(28) .setEmail(zhangsanexample.com) .setPhone(13800138000) .build()這個(gè)寫法在構(gòu)建復(fù)雜對(duì)象、DTO、或者測(cè)試數(shù)據(jù)時(shí)能明顯提升代碼可讀性。7.2 什么時(shí)候不要用 Builder 模式如果對(duì)象本身只有兩三個(gè)字段直接構(gòu)造函數(shù)傳入反而更清晰。Builder 模式最大的代價(jià)是代碼量增大、每次構(gòu)建多創(chuàng)建一次臨時(shí)對(duì)象而且不支持在 Build 方法里再繼續(xù)復(fù)用已有狀態(tài)。所以我的建議是參數(shù)數(shù)量在 5 個(gè)以上時(shí)優(yōu)先考慮 Builder。需要鏈?zhǔn)秸{(diào)用、且每個(gè)參數(shù)具備默認(rèn)值時(shí)適合 Builder。如果對(duì)象是可變對(duì)象、需要頻繁修改一部分字段不要用 Builder直接類屬性賦值更簡(jiǎn)單。7.3 Builder 設(shè)計(jì)模式和 Builder 裝飾器能混用嗎可以。在同一個(gè)項(xiàng)目里既有 UI 層面的 Builder也有數(shù)據(jù)層/業(yè)務(wù)層的 Builder 設(shè)計(jì)模式。我通常會(huì)把數(shù)據(jù)對(duì)象構(gòu)建放在model/builders文件里UI 片段構(gòu)建放在view/builders文件里。兩者互不干擾但要注意命名空間不能在同一個(gè)文件中定義同名的xxxBuilder類和一個(gè) Builder 函數(shù)否則會(huì)沖突。8. 寫在最后的實(shí)操提醒上面這些內(nèi)容前五部分是在項(xiàng)目里總結(jié)出來(lái)的 ArkUI Builder 核心玩法最后一部分是設(shè)計(jì)模式工程化的補(bǔ)充。很多人看著官方文檔覺得 Builder 就是“裝飾器 函數(shù)”但實(shí)際寫起來(lái)之后關(guān)于參數(shù)傳遞、BuilderParam 的初始化方式、以及全局局部選型這些問題才是真正拉開開發(fā)效率差距的地方。我在實(shí)際開發(fā)中的一個(gè)體會(huì)是Builder 的本質(zhì)是“復(fù)用”但復(fù)用的粒度要控制好。UI 結(jié)構(gòu)完全固定、且不需要交互上下文的優(yōu)先用全局 Builder需要共享組件狀態(tài)、又不想拆組件的用局部 Builder需要讓外部決定某一塊區(qū)域內(nèi)容的用 BuilderParam需要鏈?zhǔn)綐?gòu)造復(fù)雜數(shù)據(jù)對(duì)象的用設(shè)計(jì)模式 Builder。按這個(gè)思路去決策基本能覆蓋日常 90% 的場(chǎng)景。最后再分享一個(gè)小技巧如果遇到“Builder 內(nèi)部刷新不生效”這種問題先別急著查數(shù)據(jù)先看看你傳進(jìn)來(lái)的是對(duì)象還是對(duì)象屬性的引用。ArkUI 的狀態(tài)觀察是按照屬性級(jí)別追蹤的如果你把一個(gè)對(duì)象傳入 Builder但對(duì)象的屬性不是Observed裝飾的那大概率會(huì)出現(xiàn)改了值但界面沒反映的情況。這個(gè)坑我至少踩過三次每次排查半天最后都發(fā)現(xiàn)是對(duì)象觀察層級(jí)的問題。記住這句話能幫你省下不少時(shí)間。 HarmonyOS開發(fā)必會(huì)：詳解ArkUI @Builder與Builder設(shè)計(jì)模式
1. 先分清 Builder 的兩種身份不然你后面會(huì)越看越亂前陣子在重構(gòu)一個(gè)鴻蒙項(xiàng)目的首頁(yè)時(shí)我發(fā)現(xiàn)團(tuán)隊(duì)里關(guān)于 Builder 的討論特別多。有人說“用 Builder 封裝一個(gè)頭部組件”有人說“我的 Builder 實(shí)現(xiàn)了一個(gè)復(fù)雜對(duì)象”還有人拿著一張 SketchUp 的報(bào)錯(cuò)截圖來(lái)問是不是 HarmonyOS 的問題。后來(lái)我意識(shí)到大家口中的 Builder 不只是同一個(gè)東西在鴻蒙開發(fā)里它既是 ArkUI 聲明式框架里的Builder 裝飾器又是設(shè)計(jì)模式里的建造者模式甚至在一些第三方工具里也出現(xiàn)過同名概念。對(duì)于做 HarmonyOS 原生應(yīng)用的人來(lái)說最常打交道的其實(shí)是 ArkUI 提供的Builder 自定義構(gòu)建函數(shù)。它的核心作用是把一段 UI 描述封裝成一個(gè)函數(shù)在多個(gè)頁(yè)面或組件內(nèi)復(fù)用避免重復(fù)寫同樣的布局代碼。而設(shè)計(jì)模式里的 Builder更多是用在 ArkTS 的數(shù)據(jù)建模、復(fù)雜參數(shù)構(gòu)建上跟 UI 不直接相關(guān)但工程上也很實(shí)用。所以這篇文章我打算把兩件事串起來(lái)講前面五個(gè)部分全部圍繞 ArkUI 的 Builder 展開包括全局 Builder、局部 Builder、參數(shù)傳遞、BuilderParam 和尾隨閉包最后一部分再重點(diǎn)聊一下 Builder 設(shè)計(jì)模式在 ArkTS 工程中的落地場(chǎng)景。這樣不管你是剛?cè)腴T的新手還是已經(jīng)寫了幾個(gè)月鴻蒙頁(yè)面但一直沒把 Builder 理清的老手都能找到自己需要的答案。2. 全局自定義構(gòu)建函數(shù)最常用也最容易被忽略的細(xì)節(jié)2.1 全局 Builder 的聲明方式全局 Builder 是定義在組件外部的函數(shù)它的作用域是整個(gè)模塊。你可以把它當(dāng)作一段“UI 模板”在任何組件里直接調(diào)用。// GlobalBuilder.ets Builder export function GlobalHeaderBuilder($$: { title: string }) { Row() { Text($$.title) .fontSize(20) .fontWeight(FontWeight.Bold) Blank() Text(更多) .fontSize(14) .fontColor(#999) } .width(100%) .padding({ left: 16, right: 16, top: 12, bottom: 12 }) .backgroundColor(#F5F5F5) }調(diào)用時(shí)不需要new也不需要實(shí)例化直接在 build 方法里寫Component struct IndexPage { build() { Column() { GlobalHeaderBuilder({ title: 首頁(yè) }) // 其他內(nèi)容 } } }這里的參數(shù)傳遞用了$$語(yǔ)法后面會(huì)單獨(dú)講但先記住一個(gè)結(jié)論如果希望 Builder 內(nèi)部對(duì)參數(shù)的修改能同步到外層狀態(tài)或者希望依賴的狀態(tài)變量可以雙向聯(lián)動(dòng)建議使用$$。2.2 全局 Builder 的優(yōu)勢(shì)和坑全局 Builder 最大的優(yōu)勢(shì)是跨組件復(fù)用。多個(gè)頁(yè)面里只要有相同的頁(yè)頭、空狀態(tài)、錯(cuò)誤提示都可以抽出來(lái)做成全局 Builder。我習(xí)慣把項(xiàng)目中通用的 UI 片段全部放到一個(gè)common/builders目錄下按功能命名比如EmptyStateBuilder、ErrorStateBuilder、PageHeaderBuilder。但全局 Builder 有一個(gè)非常容易踩的坑它不能訪問組件內(nèi)部的State變量。因?yàn)槿趾瘮?shù)沒有綁定到任何一個(gè)組件實(shí)例上所以想從組件里把狀態(tài)傳給全局 Builder只能通過參數(shù)傳進(jìn)去。如果你在全局 Builder 里直接使用this編譯階段就直接報(bào)錯(cuò)。所以我一般只在以下場(chǎng)景使用全局 Builder頁(yè)面級(jí)通用頭部、底部。下拉刷新、加載失敗、空數(shù)據(jù)等與業(yè)務(wù)狀態(tài)解耦的占位 UI。需要在多個(gè)Entry頁(yè)面里復(fù)用的純展示型組件片段。如果某段 UI 強(qiáng)依賴當(dāng)前組件的狀態(tài)、需要調(diào)用當(dāng)前組件的方法或者需要和組件的生命周期聯(lián)動(dòng)我的建議是不要用全局 Builder直接用局部 Builder也就是下面第三部分要說的內(nèi)容。3. 組件內(nèi)自定義構(gòu)建函數(shù)狀態(tài)訪問更自由的局部 Builder3.1 在組件內(nèi)部聲明 Builder局部 Builder 就是把Builder函數(shù)寫在組件struct的內(nèi)部。由于它定義在當(dāng)前組件實(shí)例中所以可以直接訪問this包括State、Prop、Link以及普通成員變量和方法。Component struct ProductCard { State productName: string HarmonyOS 實(shí)戰(zhàn)指南 Builder ProductCardContent() { Column() { Text(this.productName) .fontSize(16) .fontColor(#333) Text(點(diǎn)擊查看詳情) .fontSize(12) .fontColor(#666) } .padding(12) .backgroundColor(#FFFFFF) .borderRadius(8) } build() { Column() { // 直接調(diào)用 this.ProductCardContent() } .padding(16) } }這個(gè)例子雖然簡(jiǎn)單但它體現(xiàn)了局部 Builder 最核心的價(jià)值Builder 內(nèi)部和組件共享同一個(gè)上下文。當(dāng)你修改productName時(shí)Builder 內(nèi)的Text會(huì)自動(dòng)更新不需要你手動(dòng)同步任何參數(shù)。3.2 局部 Builder 為什么能做到狀態(tài)同步很多初學(xué)者會(huì)問this.ProductCardContent()不就是一個(gè)函數(shù)調(diào)用嗎為什么狀態(tài)變了它會(huì)自動(dòng)刷新這里要注意ArkUI 的 Builder 并不是普通的函數(shù)。它在編譯階段會(huì)被框架特殊處理成為渲染樹的一部分。當(dāng)組件狀態(tài)變化時(shí)框架會(huì)依據(jù)狀態(tài)依賴關(guān)系定位到具體的 UI 組件而不是把整個(gè) build 方法重新執(zhí)行一遍。換句話說Builder 內(nèi)部的Text和build()里的組件一樣都建立在相同的狀態(tài)跟蹤基礎(chǔ)之上。這就帶來(lái)一個(gè)很實(shí)用的技巧如果某個(gè)區(qū)域的 UI 邏輯特別復(fù)雜或者被if/else、ForEach包裹得很亂可以單獨(dú)拆成一個(gè)局部 Builder讓代碼可讀性提升不少。但注意局部 Builder 不適合在多個(gè)不同組件之間復(fù)用因?yàn)橐坏?A 組件寫的 Builder 想拿到 B 組件里用就要改成全局 Builder或者提取成公共組件。4. 參數(shù)傳遞默認(rèn)值、值傳遞和 $$ 引用傳遞一次搞明白4.1 基礎(chǔ)參數(shù)傳遞與默認(rèn)值Builder 函數(shù)也支持普通參數(shù)和默認(rèn)值。比如Builder function InfoBuilder(content: string 默認(rèn)文案, showIcon: boolean true) { Row({ space: 8 }) { if (showIcon) { Text(●) } Text(content) } }調(diào)用時(shí)可以不傳參InfoBuilder()也可以傳部分參數(shù)InfoBuilder(自定義文案, false)但這里有兩個(gè)規(guī)則要記牢Builder 函數(shù)參數(shù)不能同時(shí)使用按引用傳遞和按值傳遞的混寫方式。要么全部用普通參數(shù)值傳遞要么使用$$對(duì)象形式引用傳遞。參數(shù)默認(rèn)值只支持普通參數(shù)類型比如字符串、數(shù)字、布爾值不支持?jǐn)?shù)組、對(duì)象類型。如果默認(rèn)值是一個(gè)動(dòng)態(tài)狀態(tài)變量那就不能用默認(rèn)值機(jī)制必須顯式傳入。4.2 用 $$ 實(shí)現(xiàn)引用傳遞官方推薦的傳參方式之一是把參數(shù)包裝成一個(gè)對(duì)象并在參數(shù)名稱前加$$?？催@個(gè)例子Builder function ClickableTextBuilder($$: { count: number }) { Button(點(diǎn)擊次數(shù)${$$.count}) .onClick(() { $$.count }) }父組件里這樣用Component struct CounterPage { State total: number 0 build() { Column() { ClickableTextBuilder({ count: this.total }) Text(父組件計(jì)數(shù)${this.total}) } } }當(dāng) Builder 內(nèi)部修改了$$.count父組件的total也會(huì)跟著變因?yàn)檫@里的$$表示引用傳遞this.total和$$.count指向同一個(gè)狀態(tài)源。如果你不用$$直接寫成ClickableTextBuilder({ count: this.total }) // 但函數(shù)定義是普通參數(shù) function ClickableTextBuilder(count: number) { ... }那么 Builder 內(nèi)部拿到的是.total的一個(gè)快照不管怎么修改都不會(huì)影響父組件。這對(duì)某些只讀展示的場(chǎng)景是合理的但如果期望在 Builder 內(nèi)觸發(fā)狀態(tài)更新就必須用$$。我在實(shí)際開發(fā)里幾乎都統(tǒng)一用$$對(duì)象傳參避免踩“改半天沒反應(yīng)”的坑。4.3 值傳遞和引用傳遞應(yīng)該如何選擇選擇規(guī)則其實(shí)很短如果 Builder 只是展示不修改入?yún)⒂闷胀▍?shù)足夠。如果 Builder 內(nèi)部需要修改入?yún)⒉⑼礁附M件用$$。如果參數(shù)是State、Link等狀態(tài)變量的引用建議用$$確保聯(lián)動(dòng)。如果一個(gè) Builder 有七八個(gè)參數(shù)強(qiáng)烈建議全部放進(jìn)一個(gè)$$對(duì)象里管理。這樣調(diào)用時(shí)的代碼看著像一個(gè)配置對(duì)象語(yǔ)義清晰也不容易把參數(shù)順序搞錯(cuò)。5. BuilderParam把 UI 片段當(dāng)參數(shù)傳進(jìn)門5.1 理解 BuilderParam 的插槽思想BuilderParam是 Builder 的進(jìn)階版它解決的場(chǎng)景非常直接父組件想往子組件里塞一段自定義 UI而不是塞一個(gè)值。熟悉前端的開發(fā)者一眼就能認(rèn)出來(lái)這就是“插槽”思路。舉個(gè)例子有一個(gè)通用卡片組件卡片上半部分是固定的標(biāo)題欄下半部分需要父組件自由填充內(nèi)容。我可以這樣設(shè)計(jì)Component export struct CardContainer { BuilderParam contentBuilder: () void build() { Column() { Text(卡片標(biāo)題) .fontSize(18) .fontWeight(FontWeight.Bold) Divider() // 這里渲染父組件傳入的 UI 片段 this.contentBuilder() } .padding(16) .backgroundColor(#FFFFFF) .borderRadius(12) } }父組件通過BuilderParam把自定義內(nèi)容傳進(jìn)來(lái)Builder function CustomContentBuilder() { Column() { Text(自定義區(qū)域) Button(按鈕) } } Component struct ParentPage { build() { Column() { CardContainer({ contentBuilder: CustomContentBuilder }) } } }這里的contentBuilder類型是() void意思是“一個(gè)沒有參數(shù)的構(gòu)建函數(shù)”。父組件傳一個(gè) Builder 函數(shù)進(jìn)去子組件在合適的位置調(diào)用它。5.2 初始化方式一通過普通參數(shù)傳入第一種是上面這種直接把一個(gè)已有 Builder 作為參數(shù)傳入。這種方式在父組件內(nèi)部已經(jīng)定義好一段 UI 時(shí)最自然。5.3 初始化方式二尾隨閉包第二種在 API 10 之后非常常用就是“尾隨閉包”寫法。如果子組件的最后一個(gè)參數(shù)是BuilderParam可以直接在子組件后面跟一個(gè)花括號(hào)里面寫 UICardContainer() { // 這里的內(nèi)容會(huì)傳給 contentBuilder Row({ space: 8 }) { Text(自定義標(biāo)題) Image($r(app.media.icon)) .width(24) .height(24) } }這種方式閱讀起來(lái)特別像普通布局代碼父組件不需要單獨(dú)定義一個(gè) Builder 函數(shù)代碼更緊湊。我個(gè)人在寫通用列表項(xiàng)、彈窗內(nèi)容、頁(yè)面骨架時(shí)非常喜歡這種寫法因?yàn)樗选白咏M件的固定部分”和“父組件的自定義部分”分得很開。5.4 幾個(gè)容易踩的初始化細(xì)節(jié)BuilderParam有一些隱藏規(guī)則新手經(jīng)常在這里翻車子組件的 BuilderParam 數(shù)量不能太多。雖說不限制數(shù)量但超過兩個(gè)后調(diào)用代碼的可讀性會(huì)急劇下降。如果確實(shí)需要多個(gè)插槽建議用普通 Builder 傳參給子組件再在子組件內(nèi)部用 if 處理不同區(qū)域。BuilderParam 參數(shù)名如果在初始化時(shí)沒有傳也不會(huì)有默認(rèn)值。如果父組件沒傳contentBuilder子組件調(diào)用this.contentBuilder()時(shí)會(huì)報(bào)錯(cuò)。因此對(duì)于某些可選插槽我會(huì)在子組件內(nèi)部提供一個(gè)默認(rèn) Builder 兜底。尾隨閉包方式和普通參數(shù)方式不能同時(shí)使用。一個(gè) BuilderParam 只能選擇一種傳入方式初始化。// 錯(cuò)誤的寫法既有參數(shù)傳入又寫了尾隨閉包 CardContainer({ contentBuilder: CustomContentBuilder }) { Text(這段閉包不生效) }這種代碼編譯不會(huì)直接報(bào)錯(cuò)但閉包內(nèi)容會(huì)被忽略排查起來(lái)很浪費(fèi)時(shí)間。5.5 實(shí)際案例做一個(gè)可定制彈窗外殼我項(xiàng)目中有一個(gè)通用彈窗組件外層有遮罩、圓角容器、動(dòng)畫內(nèi)部?jī)?nèi)容完全由調(diào)用方?jīng)Q定。用 BuilderParam 做起來(lái)非常清爽Component export struct CommonDialog { BuilderParam dialogContent: () void build() { Stack() { // 遮罩 Column() .width(100%) .height(100%) .backgroundColor(rgba(0, 0, 0, 0.4)) .onClick(() { /* 關(guān)閉邏輯 */ }) // 彈窗內(nèi)容 Column() { this.dialogContent() } .padding(20) .backgroundColor(#FFF) .borderRadius(16) .margin({ left: 24, right: 24 }) } } }使用方只需要傳具體內(nèi)容CommonDialog() { Column({ space: 12 }) { Text(確定要?jiǎng)h除這條數(shù)據(jù)嗎) Row({ space: 20 }) { Button(取消) Button(刪除) } } }這樣彈窗的交互框架和業(yè)務(wù)內(nèi)容完全解耦新增任何彈窗都不需要再改彈窗容器代碼。6. 實(shí)戰(zhàn)避坑Builder 狀態(tài)不刷新、循環(huán)構(gòu)建和參數(shù)失效問題6.1 狀態(tài)更新不生效的經(jīng)典場(chǎng)景有網(wǎng)友和我反饋過一個(gè)問題在 Builder 里用setInterval修改一個(gè)普通變量界面不刷新?？吹酱a后發(fā)現(xiàn)他用的是普通成員變量沒有用State裝飾。這是理解上的誤區(qū)Builder 負(fù)責(zé)復(fù)用 UI 描述但不負(fù)責(zé)“魔法化”所有變量。想要 Builder 里的 UI 感知數(shù)據(jù)變化數(shù)據(jù)源必須是狀態(tài)變量State、Prop、Link、Provide等或者能被框架觀察到的對(duì)象屬性。排查 Builder 不刷新問題我一般按這個(gè)順序查數(shù)據(jù)變量是否加了State或Observed傳遞參數(shù)是否用了$$引用傳遞如果用了值傳遞Builder 內(nèi)部再改也不會(huì)觸發(fā)父組件更新。Builder 內(nèi)部是否使用了this全局 Builder 里訪問不到組件狀態(tài)所以只能靠傳參。如果是對(duì)象屬性更新對(duì)象是否實(shí)現(xiàn)了Observed并且屬性在類內(nèi)部聲明6.2 在 LazyForEach 和列表項(xiàng)中使用 Builder列表頁(yè)是 Builder 的高頻場(chǎng)景。很多人把列表項(xiàng)寫成普通Component然后通過ForEach循環(huán)渲染。這沒問題但如果列表項(xiàng)只是一段靜態(tài) UI且不需要獨(dú)立狀態(tài)用 Builder 會(huì)更輕量。Builder function ProductItemBuilder(item: ProductModel) { Row({ space: 12 }) { Image(item.cover) .width(80) .height(80) .borderRadius(8) Column() { Text(item.name) .fontSize(16) Text(item.price) .fontSize(14) .fontColor(#E84026) } .alignItems(HorizontalAlign.Start) } .width(100%) .padding(10) }在LazyForEach中使用時(shí)我會(huì)把 Builder 直接放在LazyForEach的子項(xiàng)生成區(qū)域里L(fēng)azyForEach(this.productDataSource, (item: ProductModel, index: number) { ProductItemBuilder(item) })這里有一個(gè)經(jīng)驗(yàn)如果列表項(xiàng)內(nèi)部還需要點(diǎn)擊跳轉(zhuǎn)、需要訪問當(dāng)前組件的路由方法建議寫成組件而不是 Builder。因?yàn)?Builder 里很難方便地處理生命周期和事件上下文強(qiáng)行用 Builder 反而會(huì)增加復(fù)雜度。6.3 常見問題速查表現(xiàn)象可能原因推薦解法Builder 內(nèi)部修改數(shù)據(jù)不刷新變量不是狀態(tài)變量改用 State 或 Observed父組件傳入?yún)?shù)后 Builder 里改不動(dòng)沒有用 $$ 引用傳遞修改參數(shù)為 $$ 對(duì)象形式全局 Builder 訪問 this 報(bào)錯(cuò)全局作用域沒有組件實(shí)例改為組件內(nèi)局部 Builder 或通過參數(shù)傳入BuilderParam 沒有渲染內(nèi)容初始化方式?jīng)_突或未傳值檢查是否用普通參數(shù)和尾隨閉包混用Builder 內(nèi) ForEach 多次渲染后卡頓每次調(diào)用都創(chuàng)建了新數(shù)組使用 LazyForEach 并確認(rèn)數(shù)據(jù)源 ID 穩(wěn)定Builder 內(nèi)使用路由方法報(bào)錯(cuò)缺少組件上下文改為 Component 并在 build 中調(diào)用6.4 一個(gè)容易被忽略的編譯約束Builder 函數(shù)內(nèi)不能使用Builder裝飾的變量其實(shí)不是。但有一個(gè)規(guī)則值得注意在 Builder 內(nèi)定義局部狀態(tài)變量是不允許的。比如Builder function WrongBuilder() { State value: number 0 // 編譯報(bào)錯(cuò) Text(錯(cuò)誤示例) }狀態(tài)變量必須要放在組件結(jié)構(gòu)體的頂層Builder 只是一個(gè)構(gòu)建函數(shù)不能擁有自己的狀態(tài)存儲(chǔ)。如果需要局部狀態(tài)可以新建一個(gè)獨(dú)立的Component子組件把 Builder 區(qū)域替換成組件調(diào)用。這也是為什么很多時(shí)候組件和 Builder 要按場(chǎng)景取舍而不是一味追求“全部用 Builder 封裝”。6.5 代碼組織上的建議項(xiàng)目里 Builder 多起來(lái)以后命名和文件組織特別重要。我的習(xí)慣是全局 Builder 文件名用*Builder.ets命名如ListEmptyBuilder.ets。Builder 函數(shù)名用“用途 Builder”后綴如EmptyStateBuilder、ErrorStateBuilder。局部 Builder 放在組件結(jié)構(gòu)體底部和build()方法分開用注釋塊分隔。只在同一個(gè).ets文件里使用的 Builder優(yōu)先做成局部 Builder不導(dǎo)出到全局。7. 順手聊聊 Builder 設(shè)計(jì)模式在 ArkTS 工程里的應(yīng)用7.1 數(shù)據(jù)對(duì)象構(gòu)造場(chǎng)景ArkUI 開發(fā)中經(jīng)常要構(gòu)造復(fù)雜的請(qǐng)求參數(shù)、表單提交對(duì)象、或者一個(gè)包含多個(gè)配置項(xiàng)的數(shù)據(jù)模型。直接用構(gòu)造函數(shù)傳參參數(shù)一多代碼就變得難讀而且容易傳錯(cuò)順序。這時(shí)候就可以用 Builder 設(shè)計(jì)模式。比如有一個(gè)UserProfile對(duì)象class UserProfile { name: string age: number 0 email: string phone: string address: string }用 Builder 模式封裝后class UserProfileBuilder { private profile: UserProfile new UserProfile() setName(name: string): UserProfileBuilder { this.profile.name name return this } setAge(age: number): UserProfileBuilder { this.profile.age age return this } setEmail(email: string): UserProfileBuilder { this.profile.email email return this } setPhone(phone: string): UserProfileBuilder { this.profile.phone phone return this } build(): UserProfile { return this.profile } }調(diào)用時(shí)就很舒服const user new UserProfileBuilder() .setName(張三) .setAge(28) .setEmail(zhangsanexample.com) .setPhone(13800138000) .build()這個(gè)寫法在構(gòu)建復(fù)雜對(duì)象、DTO、或者測(cè)試數(shù)據(jù)時(shí)能明顯提升代碼可讀性。7.2 什么時(shí)候不要用 Builder 模式如果對(duì)象本身只有兩三個(gè)字段直接構(gòu)造函數(shù)傳入反而更清晰。Builder 模式最大的代價(jià)是代碼量增大、每次構(gòu)建多創(chuàng)建一次臨時(shí)對(duì)象而且不支持在 Build 方法里再繼續(xù)復(fù)用已有狀態(tài)。所以我的建議是參數(shù)數(shù)量在 5 個(gè)以上時(shí)優(yōu)先考慮 Builder。需要鏈?zhǔn)秸{(diào)用、且每個(gè)參數(shù)具備默認(rèn)值時(shí)適合 Builder。如果對(duì)象是可變對(duì)象、需要頻繁修改一部分字段不要用 Builder直接類屬性賦值更簡(jiǎn)單。7.3 Builder 設(shè)計(jì)模式和 Builder 裝飾器能混用嗎可以。在同一個(gè)項(xiàng)目里既有 UI 層面的 Builder也有數(shù)據(jù)層/業(yè)務(wù)層的 Builder 設(shè)計(jì)模式。我通常會(huì)把數(shù)據(jù)對(duì)象構(gòu)建放在model/builders文件里UI 片段構(gòu)建放在view/builders文件里。兩者互不干擾但要注意命名空間不能在同一個(gè)文件中定義同名的xxxBuilder類和一個(gè) Builder 函數(shù)否則會(huì)沖突。8. 寫在最后的實(shí)操提醒上面這些內(nèi)容前五部分是在項(xiàng)目里總結(jié)出來(lái)的 ArkUI Builder 核心玩法最后一部分是設(shè)計(jì)模式工程化的補(bǔ)充。很多人看著官方文檔覺得 Builder 就是“裝飾器 函數(shù)”但實(shí)際寫起來(lái)之后關(guān)于參數(shù)傳遞、BuilderParam 的初始化方式、以及全局局部選型這些問題才是真正拉開開發(fā)效率差距的地方。我在實(shí)際開發(fā)中的一個(gè)體會(huì)是Builder 的本質(zhì)是“復(fù)用”但復(fù)用的粒度要控制好。UI 結(jié)構(gòu)完全固定、且不需要交互上下文的優(yōu)先用全局 Builder需要共享組件狀態(tài)、又不想拆組件的用局部 Builder需要讓外部決定某一塊區(qū)域內(nèi)容的用 BuilderParam需要鏈?zhǔn)綐?gòu)造復(fù)雜數(shù)據(jù)對(duì)象的用設(shè)計(jì)模式 Builder。按這個(gè)思路去決策基本能覆蓋日常 90% 的場(chǎng)景。最后再分享一個(gè)小技巧如果遇到“Builder 內(nèi)部刷新不生效”這種問題先別急著查數(shù)據(jù)先看看你傳進(jìn)來(lái)的是對(duì)象還是對(duì)象屬性的引用。ArkUI 的狀態(tài)觀察是按照屬性級(jí)別追蹤的如果你把一個(gè)對(duì)象傳入 Builder但對(duì)象的屬性不是Observed裝飾的那大概率會(huì)出現(xiàn)改了值但界面沒反映的情況。這個(gè)坑我至少踩過三次每次排查半天最后都發(fā)現(xiàn)是對(duì)象觀察層級(jí)的問題。記住這句話能幫你省下不少時(shí)間。