HarmonyOS：ComposeTitleBar 組件自學指南

在日常的鴻蒙應用開發工作中，我們常常會面臨構建美觀且功能實用的用戶界面的挑戰。而標題欄作為應用界面的重要組成部分，它不僅承載著展示頁面關鍵信息的重任，還能為用戶提供便捷的操作入口。最近在參與的一個項目里，我就深深體會到了選擇合適的標題欄組件對于提升用戶體驗的關鍵作用。當時，團隊對于標題欄有著多樣化的需求，既要簡潔明了地呈現頁面主題，又要能靈活地配置菜單選項以滿足不同場景下的交互操作。在探索的過程中，我發現了 ComposeTitleBar 組件，經過一番深入鉆研與實踐，成功地將其運用到項目中，顯著優化了界面效果。為了幫助更多開發者少走彎路，快速掌握這個強大的組件，我決定寫下這篇自學指南，分享我在學習與使用過程中的經驗與心得。

一、組件初相識

ComposeTitleBar 組件從 API Version 10 開始支持，這意味著只要你的開發環境適配該版本及以上，就能引入并使用它。后續版本如有新增內容，則采用上角標單獨標記該內容的起始版本，所以大家在學習和使用時，一定要留意版本差異，以便充分利用組件的最新特性。

二、導入模塊

要使用 ComposeTitleBar 組件，首先需要正確導入相關模塊：

import { ComposeTitleBar } from '@kit.ArkUI'

這里簡潔明了地從指定的 ArkUI 工具包中引入了 ComposeTitleBar 組件，這是使用該組件的第一步，也是后續構建標題欄功能的基礎。

三、子組件

值得注意的是，ComposeTitleBar 組件沒有子組件，它自身就具備相對獨立且完善的功能結構，專注于標題欄的呈現與交互。

四、屬性詳解

不支持通用屬性：這一點需要牢記，在使用時不能按照常規組件的通用屬性思維來配置它，而是要依據其特定的屬性規則。
ComposeTitleBar 構造函數：
- ComposeTitleBar({item?: ComposeTitleBarMenuItem, title: ResourceStr, subtitle?: ResourceStr, menuItems?: Array<ComposeTitleBarMenuItem>})
- 裝飾器類型：@Component，這表明它遵循組件的基本構建規范，方便在鴻蒙應用的組件體系中進行整合。
- 元服務 API：從 API version 11 開始，該接口支持在元服務中使用，拓展了其應用場景，讓開發者可以在元服務開發中也能借助該組件打造專業的標題欄。
- 系統能力：SystemCapability.ArkUI.ArkUI.Full，意味著需要系統具備相應的 ArkUI 完整能力支持，在開發環境搭建與適配時要確保滿足這一條件。
- 具體屬性：
  - item：類型為?ComposeTitleBarMenuItem，可選。它用于左側頭像的單個菜單項目，為標題欄的左側交互區域提供定制化功能，比如可以設置頭像點擊后的動作、顯示樣式等。
  - title：類型為?ResourceStr，必填。這是標題欄最核心的展示內容，用于清晰地告知用戶當前頁面的主題，需要根據頁面功能準確填寫。
  - subtitle：類型為?ResourceStr，可選。作為標題的補充信息，能進一步細化頁面的描述，提升信息傳達的完整性，在一些需要詳細說明的頁面場景中十分實用。
  - menuItems：類型為?Array<ComposeTitleBarMenuItem>，可選。它是右側菜單項目列表，通過配置多個菜單項，可以為用戶提供一系列操作選擇，極大地增強了標題欄的交互性。
- 入參對象不可為?undefined：即?ComposeTitleBar(undefined)?這種寫法是錯誤的，確保在使用組件時傳入正確且有效的參數值。
ComposeTitleBarMenuItem：
- 系統能力：同樣依賴?SystemCapability.ArkUI.ArkUI.Full。
- 具體屬性：
  - value：類型為?ResourceStr，必填。它代表圖標資源，用于在菜單中顯示直觀的圖標，讓用戶一眼就能識別操作含義，提升交互效率。
  - label13+：類型為?ResourceStr，從 API version 13 開始支持在元服務中使用，可選。它為圖標提供標簽描述，在一些圖標表意不夠清晰或者需要輔助說明的情況下，能幫助用戶更好地理解操作功能，特別是對于無障礙訪問場景尤為重要。
  - isEnabled：類型為?boolean，可選，默認禁用。用于控制菜單項是否可用，當?isEnabled?為?true?時表示啟用，用戶可以點擊觸發相應操作；為?false?時表示禁用，避免用戶誤操作或者在特定場景下限制某些功能的使用。需要注意的是，item?屬性不支持觸發?isEnabled?屬性。
  - action：類型為?() => void，可選。它是觸發時的動作閉包，定義了用戶點擊菜單項后要執行的操作，比如彈出提示框、跳轉頁面等。同樣，item?屬性不支持觸發?action?事件。

五、事件

ComposeTitleBar 組件不支持通用事件，這就要求我們在開發過程中，充分利用其提供的屬性配置來實現交互邏輯，而不是依賴傳統的通用事件監聽方式。

六、示例剖析與實踐拓展

下面讓我們深入研究給定的示例，理解如何將這些知識轉化為實際的界面構建。
示例實現了簡單的標題欄，帶有返回箭頭的標題欄和帶有右側菜單項目列表的標題欄。

import { ComposeTitleBar, promptAction, ComposeTitleBarMenuItem } from '@kit.ArkUI'@Entry
@Component
struct Index {//定義右側菜單項目列表private menuItems: Array<ComposeTitleBarMenuItem> = [{//菜單圖片資源value: $r('app.media.ic_public_save'),//啟用圖標isEnabled: true,//點擊菜單時觸發事件action: () => promptAction.showToast({ message: "保存成功" })},{value: $r('app.media.ic_public_reduce'),isEnabled: true,action: () => promptAction.showToast({ message: "縮小操作" })},{value: $r('app.media.ic_public_edit'),isEnabled: true,action: () => promptAction.showToast({ message: "進入編輯模式" })},{value: $r('app.media.ic_public_remove'),isEnabled: true,action: () => promptAction.showToast({ message: "刪除操作" })},]build() {Row() {Column() {//分割線Divider().height(2).color(0xCCCCCC)ComposeTitleBar({title: "精彩資訊頁面",subtitle: "每日最新動態",menuItems: this.menuItems.slice(0, 1),})Divider().height(2).color(0xCCCCCC)ComposeTitleBar({title: "個人中心",subtitle: "管理您的賬戶",menuItems: this.menuItems.slice(0, 2),})Divider().height(2).color(0xCCCCCC)ComposeTitleBar({title: "設置",subtitle: "個性化配置",menuItems: this.menuItems,})Divider().height(2).color(0xCCCCCC)//定義帶頭像的標題欄ComposeTitleBar({menuItems: [{ isEnabled: true, value: $r('app.media.ic_public_save'),action: () => promptAction.showToast({ message: "收藏成功" })}],title: "收藏夾",subtitle: "您的專屬收藏",item: { isEnabled: true, value: $r('app.media.app_icon') }})Divider().height(2).color(0xCCCCCC)}}.height('100%')}
}

在這個示例中：

首先，我們導入了必要的模塊，包括 ComposeTitleBar、promptAction（用于彈出提示信息）以及 ComposeTitleBarMenuItem。
接著，定義了一個私有的?menuItems?數組，其中包含了多個?ComposeTitleBarMenuItem?對象，每個對象詳細配置了圖標資源、是否啟用以及點擊后的動作，比如保存、編輯、刪除等操作對應的提示信息，讓用戶在交互時有明確的反饋。
在?build?方法中，通過?Row?和?Column?組件構建了頁面布局結構，并在其中插入了多個?ComposeTitleBar?組件實例。每個實例根據不同的頁面場景設置了獨特的標題、副標題以及右側菜單項目。例如，在 “精彩資訊頁面” 標題欄，設置了簡潔的標題和副標題，同時只展示了一個 “保存” 菜單選項；而在 “設置” 頁面的標題欄，則完整展示了所有的菜單選項，滿足用戶對多樣化操作的需求。對于帶頭像的標題欄，如 “收藏夾” 頁面，不僅配置了頭像的圖標資源，還設置了頭像點擊后的收藏提示動作，豐富了標題欄的交互維度。

七、實踐拓展建議

樣式定制：可以嘗試修改?Divider?的樣式，如更改顏色為與應用主題更匹配的色調，或者調整高度以適應不同屏幕尺寸下的視覺效果。對于?ComposeTitleBar?本身，探索修改標題、副標題的字體大小、顏色，使其在不同頁面有更突出的顯示效果，增強信息可讀性。
交互優化：在?action?閉包中，不僅僅局限于彈出提示框，可以實現頁面跳轉，比如點擊 “編輯” 菜單跳轉到編輯頁面，或者與后端數據交互，實現實時保存用戶在標題欄操作后的設置變更等復雜功能。
適配多設備：考慮不同設備屏幕尺寸，對于菜單選項的顯示數量、布局進行動態調整，確保在手機、平板等設備上都能有良好的用戶體驗。例如，在平板上可以適當增加菜單選項的橫向排列數量，充分利用大屏幕空間。

總之，ComposeTitleBar 組件為鴻蒙應用開發的標題欄構建提供了強大而便捷的解決方案。通過深入理解其屬性、合理運用示例代碼并積極實踐拓展，相信大家都能快速上手，打造出滿足各種需求的優質標題欄，提升應用的整體品質與用戶滿意度。