Flutter三方庫適配OpenHarmony【harmony_ui】導航類控件實戰(zhàn)標題欄、子頁簽、底部頁簽與輪播前言harmony_ui是 Material/Cupertino 風格的 Flutter 組件庫完整實現(xiàn)了HarmonyOS 設計語言覆蓋官方「控件概覽」的 6 大類 42 個控件并額外實現(xiàn)了沉浸光感材質(zhì)與 UI Design Kit 增強能力。本系列按官方控件類別逐類實戰(zhàn)本篇是第 1 篇導航類。導航類是應用骨架的第一層標題欄OhosAppBar定義頁面頭部子頁簽OhosTabBar做頁面內(nèi)切換底部頁簽OhosNavigationBar做全局導航輪播OhosSwiper與導航點OhosPageIndicator承載首屏內(nèi)容流。5 個控件全部對齊官方規(guī)范且是沉浸光感落點最集中的類別——標題欄、底部頁簽的光感材質(zhì)、動態(tài)模糊、光池效果都在這里。本系列全部代碼都在OpenHarmony 模擬器上直接運行驗證Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截圖環(huán)境API 261280×2832。環(huán)境搭建、依賴引入與構(gòu)建步驟見文首「環(huán)境與版本」「安裝與引入 harmony_ui」以及第九節(jié)倉庫地址AtomGit / GitHub。環(huán)境與版本本文的示例與截圖基于以下環(huán)境組合2026-10 實測組件版本說明Flutter SDKOH 適配版3.47.7-ohos-1.0.1oh-flutter/flutter_flutteroh-3.47-dev分支DevEco Studio26.0.0 Release提供 hvigor / ohpm / hdc / JBR 等工具鏈OpenHarmony SDK / APIAPI 2626.0.0模擬器與 SDK 均為 API 26運行設備OpenHarmony 模擬器API 261280×2832環(huán)境搭建分叉獲取、DevEco Studio 與 SDK 配置、模擬器創(chuàng)建請按官方指導操作OpenHarmony-flutter 環(huán)境搭建指導。harmony_ui是純 Dart/Flutter 組件庫不依賴 ohos 平臺通道在官方 Flutter SDK 上也能運行用于跨平臺預覽。只有跑example/ohos工程、構(gòu)建 HAP 時才需要上面的 OH 適配版 SDK。安裝與引入 harmony_uiharmony_ui已發(fā)布到 pub.dev當前最新版本是0.3.0。在應用工程的pubspec.yaml中聲明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依賴fvm flutter pub get如果團隊需要固定到倉庫的某個提交例如使用尚未發(fā)版的修復改用 git 依賴dependencies:harmony_ui:git:url:https://atomgit.com/oh-flutter/harmony_ui.gitref:v0.3.0# 固定 tag寫 main 則跟隨最新提交fvm flutter pub getpub.dev 與 git 兩種方式二選一不要同時聲明。CI 中建議固定 tag如v0.3.0而不是main避免構(gòu)建結(jié)果隨上游漂移。harmony_ui目前只依賴qr一個三方包ohos_icons是可選配套圖標包不引入也不影響組件使用。一、導航類總覽官方「導航類」共 5 個控件harmony_ui實現(xiàn)如下官方控件實現(xiàn)關(guān)鍵特性標題欄OhosAppBar沉浸光感、動態(tài)模糊滾動效果、自動返回鍵子頁簽OhosTabBar下劃線 24×3vp / 膠囊兩種形態(tài)、分割線跟手底部頁簽OhosNavigationBar平鋪 48vp / 懸浮 56vp、光池跟隨、角標導航點OhosPageIndicator輪播指示點支持自定義顏色尺寸輪播OhosSwiper自動播放、循環(huán)、內(nèi)置指示點使用導航類組件前先用OhosTheme包一層應用根節(jié)點所有顏色走主題 Tokenimportpackage:flutter/material.dart;importpackage:harmony_ui/harmony_ui.dart;voidmain()runApp(constMyApp());classMyAppextendsStatelessWidget{constMyApp({super.key});overrideWidgetbuild(BuildContextcontext){returnMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);}}二、標題欄 OhosAppBar2.1 基礎結(jié)構(gòu)OhosAppBar是PreferredSizeWidget可直接傳給OhosScaffold.appBar。高度默認56vptitle/leading/actions三區(qū)結(jié)構(gòu)OhosScaffold(appBar:OhosAppBar(title:constText(設置),actions:[OhosIconButton(icon:constIcon(Icons.search),onPressed:_onSearch),OhosIconButton(icon:constIcon(Icons.more_horiz),onPressed:_onMore),],),body:constMyBody(),)title任意 Widget通常用OhosText標題字階leading左側(cè)區(qū)域不傳且頁面可pop時自動插入返回鍵automaticallyImplyLeading默認 trueactions右側(cè)圖標按鈕列表推薦 2-3 個圖標 24×24vpelevation默認 0鴻蒙風格標題欄不做投影分層層次交給光感材質(zhì)。2.2 自定義高度與背景height/backgroundColor/scrolledBackgroundColor都開放。沉浸式頁面內(nèi)容延伸到標題欄后面把背景設為透明OhosAppBar(height:64,backgroundColor:Colors.transparent,title:constOhosText(首頁,level:OhosTextLevel.headlineMedium),)注意OhosScaffold內(nèi)部把OhosAppBar與body按 Column 布局v0.1.0 之前是 Stack 疊加導致內(nèi)容被遮擋已修復。要做內(nèi)容穿透標題欄的沉浸式效果用scrollEffect動態(tài)模糊見 3.2 節(jié)而不是自己改 Scaffold 布局。三、沉浸光感標題欄3.1 光感材質(zhì) lightMaterial打開lightMaterial: true標題欄背景由不透明色替換為ULTRA_THIN 光感材質(zhì)8vp sigma 模糊 表面填充 頂部漸變淡出懸浮在內(nèi)容之上的薄紗效果OhosAppBar(lightMaterial:true,// 默認檔位 ultraThinlightLevel:OhosLightMaterialLevel.ultraThin,// 可顯式指定五檔之一title:constText(首頁),actions:const[OhosIconButton(icon:Icon(Icons.more_horiz),onPressed:null),],)3.2 動態(tài)模糊 scrollEffectscrollEffect是 UI Design Kit「動態(tài)模糊標題欄」能力的實現(xiàn)內(nèi)容穿透標題欄滾動滾動位移進入blurEffectiveStartOffset ~ blurEffectiveEndOffset區(qū)間后模糊背板按進度淡入。三種效果類型OhosAppBar(backgroundColor:Colors.transparent,title:constText(首頁),scrollController:_scroller,scrollEffect:constOhosAppBarScrollEffectOptions(effect:OhosAppBarScrollEffectType.commonBlur,blurEffectiveStartOffset:0,// 開始產(chǎn)生模糊的偏移blurEffectiveEndOffset:60,// 模糊達到滿值的偏移blurSigma:10,// 模糊強度),scrolledBackgroundColor:Colors.white,)效果類型行為適用場景commonBlur進入?yún)^(qū)間后常顯模糊背板常規(guī)內(nèi)容流頁面transitionBlur模糊隨滾動進度連續(xù)變化沉浸式首屏gradientBlur模糊 漸變蒙層疊加大圖頭部頁面動態(tài)模糊標題欄在模擬器上的實機效果滾動后背板淡入動態(tài)模糊標題欄內(nèi)容穿透滾動進入閾值區(qū)間后commonBlur背板淡入四、子頁簽 OhosTabBar4.1 下劃線式OhosTabBar與 Flutter 的TabBar一樣需要配合TabController/DefaultTabController使用tabs傳ListWidget。下劃線式默認的指示條嚴格對齊官方規(guī)范24×3vp 品牌色DefaultTabController(length:3,child:Scaffold(body:NestedScrollView(headerSliverBuilder:(_,__)[SliverToBoxAdapter(child:OhosTabBar(tabs:const[Text(推薦),Text(熱榜),Text(關(guān)注)],type:OhosTabBarType.underline,// 默認值可省略),),],body:constTabBarView(children:[Center(child:Text(推薦頁)),Center(child:Text(熱榜頁)),Center(child:Text(關(guān)注頁))],),),),)頁簽可滾動isScrollable: true頁簽數(shù)量多時不換行、橫向滑動指示條顏色indicatorColor默認取主題品牌色#0A59F7。4.2 膠囊式膠囊式capsule激活項品牌色實底、未激活項comp_background_gray灰底對齊官方子頁簽規(guī)范OhosTabBar(tabs:const[Text(日),Text(周),Text(月)],type:OhosTabBarType.capsule,height:40,)多選/篩選場景用OhosChipGroup膠囊組合間距默認 8vp官方建議不宜過大OhosChipGroup(items:constOhosChipItem[OhosChipItem(label:Text(全部)),OhosChipItem(label:Text(進行中)),OhosChipItem(label:Text(已完成)),],multiple:true,// 多選模式selectedIndexes:_selected,// 已選索引集合onSelectionChanged:(Setintv)setState(()_selectedv),)導航類組件整體效果沉浸光感標題欄 子頁簽 ChipGroup 底部頁簽導航類頂部沉浸光感標題欄中部下劃線 膠囊子頁簽與 ChipGroup底部平鋪/懸浮頁簽膠囊子頁簽 ChipGroup 多選實機效果膠囊式子頁簽激活項品牌色實底、未激活灰底ChipGroup 多選篩選五、子頁簽分割線divider 三模式OhosTabBar通過dividerOhosTabBarDividerOptions控制頁簽欄下方的分割線三種模式模式行為OhosTabBarDividerMode.visible常顯OhosTabBarDividerMode.none常隱OhosTabBarDividerMode.followScroll跟手內(nèi)容下滑淡入、回頂?shù)鯫hosTabBar(tabs:const[Text(推薦),Text(熱榜),Text(關(guān)注)],divider:constOhosTabBarDividerOptions(mode:OhosTabBarDividerMode.followScroll,followStartOffset:0,// 開始淡入的滾動偏移followEndOffset:20,// 淡入完成的滾動偏移strokeWidth:1,),scrollController:_scroller,// followScroll 模式必須提供)分割線實機效果visible常顯模式子頁簽分割線常顯 / 常隱 / 跟手三種模式提示分割線顏色默認取主題font_fourth20% 黑可用divider.color覆蓋startMargin/endMargin可讓分割線兩端縮進與內(nèi)容邊距對齊。六、底部頁簽 OhosNavigationBar6.1 平鋪式與懸浮式OhosNavigationBar對齊官方底部頁簽規(guī)范平鋪式高48vp通欄懸浮式高56vp圓角懸浮條激活項用 20% 品牌色comp_emphasize_secondary填充圖標 24×24vp頁簽數(shù)量建議3-5 個形態(tài)默認高度外觀典型場景tile平鋪默認48vp通欄無投影標準應用float懸浮56vp圓角懸浮條 投影配合沉浸光感// 平鋪式OhosNavigationBar(currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:const[OhosNavigationDestination(icon:Icon(Icons.home_outlined),label:首頁),OhosNavigationDestination(icon:Icon(Icons.square_grid_2x2),label:組件),OhosNavigationDestination(icon:Icon(Icons.person_outline),label:我的),],)6.2 雙圖標與角標每個頁簽可以配置selectedIcon選中態(tài)圖標不傳則用icon與badge圖標角標OhosBadge數(shù)字或紅點OhosNavigationDestination(icon:constIcon(Icons.person_outline),selectedIcon:constIcon(Icons.person_filled),label:我的,badge:constOhosBadge(count:5),// 數(shù)字角標不傳 count 為紅點)七、光感底部頁簽與光池懸浮式 lightMaterial: true是導航類的光感重頭戲THIN 材質(zhì)16vp sigma懸浮條彩色光池跟隨選中項移動按壓時指尖出現(xiàn)光暈OhosNavigationBar(type:OhosNavigationBarType.float,lightMaterial:true,lightLevel:OhosLightMaterialLevel.thin,// 懸浮式默認檔位glow:true,// 光池跟隨選中項enablePressGlow:true,// 按壓觸發(fā)指尖光斑currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:destinations,)光池移動帶動畫過渡切換頁簽時光暈平滑滑動而非瞬移按壓光斑抬手后自動淡出與OhosGeometry.spring90ms曲線一致光池配色來自OhosLightPalette.glowColors明暗主題自動適配。平鋪式與懸浮式底部頁簽實機對比底部頁簽上為平鋪式48vp 通欄下為懸浮式56vp 圓角懸浮條 光感材質(zhì)八、輪播 OhosSwiper 與導航點8.1 OhosSwiperOhosSwiper封裝了PageView內(nèi)置自動播放、循環(huán)與指示點是首屏 Banner 的主力OhosSwiper(height:180,autoPlay:true,autoPlayInterval:constDuration(seconds:4),loop:true,// 無限循環(huán)indicator:true,// 內(nèi)置導航點默認開啟clipRadius:BorderRadius.circular(16),onPageChanged:(int i)setState(()_pagei),children:[OhosImage(image:NetworkImage(https://example.com/a.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/b.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/c.png),width:double.infinity),],)8.2 OhosPageIndicator需要自定義指示點位置如放在圖片外時OhosSwiper(indicator: false)關(guān)掉內(nèi)置點用OhosPageIndicator單獨渲染Column(children:[SizedBox(height:180,child:OhosSwiper(indicator:false,children:bannerImages),),constSizedBox(height:12),OhosPageIndicator(count:3,currentIndex:_page,dotSize:8,spacing:6,),],)activeColor/inactiveColor默認取主題色品牌色 / 20% 黑導航點尺寸默認 8vp、間距 6vp與官方規(guī)范一致。8.3 導航類常見坑OhosTabBar不傳 controller既沒有TabController也沒有DefaultTabController祖先時會取不到控制器而報錯頁簽頁務必用DefaultTabController(length:)包裹輪播圖片不圓角OhosImage自帶圓角但OhosSwiper翻頁切換時會露出直角邊緣給OhosSwiper(clipRadius:)傳同樣的圓角懸浮頁簽被內(nèi)容遮擋OhosNavigationBar(type: float)懸浮在內(nèi)容之上頁面底部要留 56vp 安全區(qū)的 padding否則最后一行列表會被蓋住動態(tài)模糊不生效scrollEffect必須同時傳scrollController且滾動容器真實使用它backgroundColor設為不透明色時模糊被背景擋住需設透明。九、在鴻蒙模擬器上運行導航類的所有效果光感標題欄、動態(tài)模糊、光池都在 gallery 示例應用的「導航」分類頁可交互運行。最短運行路徑安裝3.47.7-ohos-1.0.1的 OH 適配版 SDK。該版本在倉庫里是 git tag按 tag 淺克隆到 fvm 版本目錄后在工程內(nèi)切換gitclone--depth1--branch3.47.7-ohos-1.0.1\https://atomgit.com/oh-flutter/flutter_flutter.git\~/fvm/versions/ohos/oh-3.47.7-releasecdharmony_ui 倉庫根目錄fvm use ohos/oh-3.47.7-release fvm flutter--version# 應輸出 Flutter 3.47.7-ohos-1.0.1fvm 的fvm install alias/ref只識別分支名3.47.7-ohos-1.0.1是 tag不能直接 install按上面的方式 clone 到版本目錄后fvm use即可。source env.sh加載 DevEco Studio26.0.0 Release的工具鏈node / ohpm / hvigor / SDK toolchains如果命令不可用按文首的環(huán)境搭建指導檢查DEVECO_SDK_HOME、JAVA_HOME與hdc進入example/fvm flutter pub get fvm flutter create --platforms ohos .構(gòu)建并安裝到模擬器fvm flutter build hap--debug--no-codesign hdc list targets hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap hdc shell aa start-aEntryAbility-bcom.example.ohos_ui_example光感效果依賴BackdropFilter模擬器與真機渲染一致若真機上模糊邊緣有毛刺優(yōu)先檢查設備 GPU 驅(qū)動而非組件參數(shù)。十、最佳實踐層級唯一一個頁面只有一個標題欄actions最多 3 個按鈕更多操作收進更多菜單頁簽數(shù)量底部頁簽 3-5 個子頁簽 2-5 個超出說明信息架構(gòu)該拆頁了光感節(jié)制標題欄 懸浮底部頁簽同時開光感即可彈層再疊加光感時注意同屏模糊層數(shù)量≥3 層時低端機會掉幀動態(tài)模糊閾值blurEffectiveEndOffset建議 40-80vp太小模糊感突兀太大幾乎看不到選中態(tài)圖標底部頁簽務必配selectedIcon線性→面性切換是官方視覺的重要組成部分寬屏適配≥840vp 窗口建議底部頁簽改側(cè)邊頁簽OhosSideBar見系列第 7 篇增強類導航與反饋聯(lián)動頁簽切換失敗時配合showOhosToast提示切換成功保持靜默——導航層成功不打擾、失敗有交代。十一、常見問題 FAQ11.1flutter pub get找不到 harmony_ui先確認版本口徑pub.dev 上最新為0.3.0pubspec.yaml寫harmony_ui: ^0.3.0若使用 git 依賴檢查url/ref是否可達并確認沒有同時聲明 pub.dev 與 git 兩份依賴。改完后執(zhí)行fvm flutter clean fvm flutter pub get如果仍解析到舊版本刪除pubspec.lock與.dart_tool/后重試不要手改pubspec.lock。11.2 組件能編譯但運行時顏色/字階與截圖不一致通常是主題沒有注入。OhosTheme要放在MaterialApp.home或builder里包住頁面根節(jié)點所有Ohos*組件都通過OhosTheme.of(context)讀取 TokenMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);只import package:harmony_ui/harmony_ui.dart不會自動注入主題未包OhosTheme時組件會回退到默認亮色 Token。11.3 光感、動態(tài)模糊不生效按順序檢查OhosAppBar(scrollEffect: ...)是否同時傳了scrollController且滾動容器真的使用了這個 controllerbackgroundColor是否被設成了不透明色——不透明背景會擋住BackdropFilter需要透明或半透明同一屏的模糊層是否過多標題欄 懸浮頁簽 彈層同時開啟。層數(shù)越多開銷越大減少層數(shù)通常比調(diào)參數(shù)更有效。11.4 真機上模糊邊緣有毛刺、光感發(fā)灰模擬器與真機的光感效果基本一致真機出現(xiàn)邊緣毛刺時優(yōu)先排查設備 GPU 驅(qū)動與系統(tǒng)版本而不是組件參數(shù)?？梢栽谡鏅C上把scatterScale調(diào)低、glowScale略降后再對比深色模式如果過曝glowScale建議保持在 0.8–0.9。11.5 頁簽報No TabController輪播圖片露出直角這是組件約定不是 bugOhosTabBar需要有TabController或DefaultTabController祖先頁簽頁用DefaultTabController(length: ...)包住即可OhosSwiper翻頁時會裁切子組件的圓角需要給OhosSwiper(clipRadius:)傳與OhosImage相同的圓角。更多導航類細節(jié)見 8.3 節(jié)。11.6 構(gòu)建時報npm not found、hvigor不存在或DEVECO_SDK_HOME錯誤說明 DevEco 工具鏈沒有進入 PATH。在倉庫根目錄執(zhí)行source env.sh按 DevEco Studio 26.0.0 Release 的默認安裝路徑配置確認node、ohpm、hvigor、hdc都可執(zhí)行DEVECO_SDK_HOME必須指向.../Contents/sdk而不是 DevEco 的安裝根目錄。首次構(gòu)建前可用fvm flutter doctor -v檢查 OHOS 設備識別情況。11.7 模擬器安裝失敗或提示簽名錯誤OpenHarmony 模擬器接受未簽名 debug HAPfvm flutter build hap--debug--no-codesign hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap如果要用flutter run熱重載 / 斷點調(diào)試則需要簽名配置在 DevEco Studio 中打開example/ohos勾選自動簽名或參考 oh-flutter 的自動簽名方案。真機安裝必須使用調(diào)試證書簽名的 HAP。11.8 能在官方 FlutterAndroid / iOS / Web上使用嗎可以。harmony_ui是純 Dart/Flutter 組件庫不依賴平臺通道差異主要在視覺HarmonyOS 字體在非鴻蒙平臺會回退到系統(tǒng)字體光感與模糊的最終效果也取決于平臺 GPU?？缙脚_預覽用官方 Flutter 即可鴻蒙模擬器/真機驗證使用 3.47.7-ohos-1.0.1。11.9 該用 pub.dev 的 0.3.0還是倉庫 main以 pub.dev 的0.3.0為準它對應倉庫 tagv0.3.0main可能包含尚未發(fā)版的改動。生產(chǎn)項目固定版本號或 tag嘗鮮再跟main。升級前查看 CHANGELOG確認是否有 API 變更?？偨Y(jié)導航類 5 個控件是harmony_ui與官方規(guī)范對齊度最高的一組標題欄 56vp、下劃線指示條 24×3vp、平鋪 48vp / 懸浮 56vp 底部頁簽數(shù)字都來自官方文檔不是拍腦袋調(diào)的。加上沉浸光感標題欄、動態(tài)模糊與光池跟隨導航層就能達到以假亂真的鴻蒙質(zhì)感。下一篇進入展示類文本字階、圖片、進度條、徽標、索引條、二維碼等 13 個控件逐個拆解。如果這篇文章對你有幫助歡迎點贊、收藏?、關(guān)注你的支持是我持續(xù)創(chuàng)作的動力相關(guān)資源harmony_ui 倉庫AtomGithttps://atomgit.com/oh-flutter/harmony_uiharmony_ui 倉庫GitHubhttps://github.com/shaohushuo/harmony_uiharmony_ui pub.dev 發(fā)布頁https://pub.dev/packages/harmony_uiFlutter OH 適配版3.47.7-ohos-1.0.1https://atomgit.com/oh-flutter/flutter_flutterFlutter OH 環(huán)境搭建指導https://atomgit.com/oh-flutter/flutter_samples/blob/master/ohos/docs/03_environment/OpenHarmony-flutter%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA%E6%8C%87%E5%AF%BC.mdDevEco Studio 官方頁面本文使用 26.0.0 Releasehttps://developer.huawei.com/consumer/cn/deveco-studio/配套圖標包 ohos_iconshttps://pub.dev/packages/ohos_icons官方底部頁簽規(guī)范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/bottomtab-0000001956787789官方子頁簽規(guī)范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/chipsgroup-0000001929788350官方沉浸光感規(guī)范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/immersivelight-0000002612101053fvm 多版本管理https://fvm.app