在 HarmonyOS ArkUI 开发中，toolbar 是一个全局通用属性，主要用于为支持的容器或页面组件绑定顶部工具栏和导航栏的自定义布局。通过 @Builder 构建函数定义内容，配合 ToolBarItem 实现按钮、滑块、搜索框等控件的灵活排列，支持顶部导航栏左右两侧（LEADING / TRAILING）的布局需求。
核心能力包括：
- 为 Navigation、NavDestination、Page 等组件定制工具栏
- 多控件组合布局支持
- 导航页与子页面独立配置不同工具栏
- 页面级与导航级顶部菜单的统一管理
一、核心 API 定义
1. toolbar 通用属性
toolbar(builder: BuilderAttrParam): void
作用是为当前组件绑定自定义工具栏布局。参数接受一个 @Builder 自定义构建函数，无返回值。
2. ToolBarItem 工具栏项
ToolBarItem(options: { placement: ToolBarItemPlacement })
用于定义工具栏内子元素的位置：
TOP_BAR_LEADING：顶部栏左侧（前导位置）TOP_BAR_TRAILING：顶部栏右侧（尾随位置）
3. 支持的子组件
Button、Slider、Search、Text、Image 等系统组件均可放入工具栏中进行布局。
二、核心使用规则
编写时需注意几个关键点。首先必须使用 @Builder 来定义工具栏的内容结构。其次，内部必须使用 ToolBarItem 包裹每一个子控件，否则无法正确识别位置。此外，支持一个页面绑定独立的 toolbar，也支持 NavDestination 子页面独立配置不同的 toolbar，并且能够灵活实现左右分栏布局。
三、完整可运行示例代码
下面是一个完整的 SideBarContainerExample 示例，展示了如何在主页面和子页面分别配置不同的工具栏。
// MainPage.ets
@Entry
@Component
struct SideBarContainerExample {
normalIcon: Resource = $r('app.media.startIcon')
selectedIcon: Resource = $r('app.media.startIcon')
@State arr: number[] = [1, , ]
: =
() : = ()
() {
({ : . }) {
().()
}
({ : . }) {
().()
}
}
() {
({ : . }) {
().()
}
({ : . }) {
().()
}
}
(: ) {
() {
() {
().().(.)
}.(.)
}
}
() {
(.) {
() {
(., {
({ : }) {
(. === item ? . : .)
.()
.()
( + item)
.()
.(. === item ? : )
.()
}.( {
. = item
})
}, item.())
}.()
.(.)
.()
(.) {
() {
(, { : , : . })
.()
.()
.()
.(.)
(, { : , : . })
.()
.()
.()
.( {
..({ : })
})
}.()
.()
}
.(.)
.()
.([, ])
.()
.(.)
.()
.()
}
.()
.()
.()
.()
.( {
.( + value)
})
.({ : , : ., : , : })
}
}
