在日常開發中，如果你有類似「左側導航 + 右側內容」的布局需求，比如后臺管理界面、文件管理器、設置頁等，??SideBarContainer?? 是非常值得掌握的組件。它自帶側邊欄和主內容區的分離機制，還支持折疊、拖拽、控制按鈕和多種顯示模式，是構建復雜頁面結構的好幫手。
這篇文章將從實際開發視角出發，用一段簡化的示例代碼，帶你快速掌握 ??SideBarContainer?? 的使用方法，并逐步解析核心屬性與交互行為。
組件簡介
??SideBarContainer?? 是 HarmonyOS 提供的一個雙區域容器，固定由兩個子組件組成：
- 第一個子組件表示側邊欄；
- 第二個子組件表示主內容區。
組件內部已實現側邊欄的顯示與隱藏邏輯，開發者只需關注如何傳入正確結構和控制顯示行為即可。
支持三種布局類型：
- ?
?Embed??：并排展示； - ?
?Overlay??：側邊欄懸浮； - ?
?Auto??：根據容器寬度自動選擇 Embed 或 Overlay。
示例場景：基本側邊欄菜單布局
下面是一個常見的布局案例：左邊是圖標 + 文本菜單項，右邊是內容展示區。
@Entry
@Component
struct SideBarContainerExample {normalIcon: Resource = $r("app.media.startIcon")selectedIcon: Resource = $r("app.media.startIcon")@State arr: number[] = [1, 2, 3]@State current: number = 1build() {SideBarContainer(SideBarContainerType.Embed) {// 左側導航欄Column() {ForEach(this.arr, (item: number) => {Column({ space: 5 }) {Image(this.current === item ? this.selectedIcon : this.normalIcon).width(48).height(48)Text("菜單 " + item).fontSize(20).fontColor(this.current === item ? '#0A59F7' : '#777').fontFamily('HarmonyOS Sans')}.onClick(() => {this.current = item})}, (item: number) => item.toString())}.width('100%').justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).backgroundColor('#F3F3F3')// 右側主內容區Column() {Text(`當前內容：菜單 ${this.current}`).fontSize(24).fontWeight(FontWeight.Medium)Text('這是側邊欄對應的內容區，可根據選擇進行切換').fontSize(18).margin({ top: 10 })}.padding({ top: 50, left: 20, right: 20 })}.controlButton({left: 12,top: 40,width: 28,height: 28,icons: {hidden: $r('app.media.startIcon'),shown: $r('app.media.startIcon'),switching: $r('app.media.startIcon')}}).sideBarWidth(180).minSideBarWidth(60).maxSideBarWidth(280).minContentWidth(300).divider({strokeWidth: '2vp',color: '#CCCCCC',startMargin: '6vp',endMargin: '6vp'}).onChange((visible: boolean) => {console.info('側邊欄當前狀態：' + (visible ? '顯示' : '隱藏'))})}
}
核心知識點說明
子組件數量限制
- 必須且只能兩個子組件，否則布局會異常。
- 一個子組件 → 只展示側邊欄。
- 超過兩個 → 只保留前兩個。
顯示模式控制
通過構造函數傳入 ??SideBarContainerType?? 類型參數控制顯示樣式，推薦用法：
- ?
?.Embed??：固定并排展示； - ?
?.Overlay??：懸浮在內容上； - ?
?.Auto??：根據整體寬度智能切換模式。
尺寸控制參數
| 方法名 | 說明 |
|---|---|
??.sideBarWidth()?? | 默認寬度 |
??.minSideBarWidth()?? | 拖拽最小寬度 |
??.maxSideBarWidth()?? | 拖拽最大寬度 |
??.minContentWidth()?? | 內容區最小展示寬度 |
尺寸單位通常用 ??vp???，支持直接傳入數字，也支持百分比和 ??Length?? 類型。
控制按鈕樣式
通過 ??.controlButton({...})?? 方法自定義控制按鈕的大小、位置與圖標，圖標支持：
- ?
?shown??：側邊欄展開時； - ?
?hidden??：側邊欄隱藏時； - ?
?switching??：切換中狀態。
圖標資源建議使用 PixelMap 或 ??$r()?? 形式引用本地媒體資源。
分割線樣式
通過 ??.divider({...})?? 方法自定義側邊欄和內容區中間的分隔線，支持設置線寬、顏色、邊距等。
常見問題說明
- 側邊欄高度怎么控制？
- 側邊欄會自動繼承容器高度，建議不要直接設置 ?
?height??。
- 寬度設置無效？
- 注意：不能直接對側邊欄子組件設置 ?
?width???，請統一用 ??.sideBarWidth()?? 控制。
- 如何響應收起 / 展開狀態變化？
- 使用 ?
?.onChange()?? 監聽器獲取當前狀態，可用于聯動 UI 或輸出日志。
總結建議
??SideBarContainer?? 是構建復雜結構頁面時非常實用的組件，重點在于理解它對子組件數量的限制、布局樣式的選擇邏輯、以及各類尺寸控制參數。實際使用中，可以與頁面狀態管理、資源圖標切換等邏輯配合，構建出靈活可交互的側邊欄體驗。
建議從 Embed 模式開始練習，等熟悉后再嘗試 Overlay 或 Auto 模式的布局響應性處理。
)
