• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Toolbar
2
3You can configure the toolbar for a component.
4
5>  **NOTE**
6>
7>  The feature is supported since API version 20. Updates will be marked with a superscript to indicate their earliest API version.
8>
9>  This toolbar is a universal attribute for components. Note the distinction from the toolbar attribute of the [Navigation](ts-basic-components-navigation.md#navigation) component.
10
11## toolbar
12
13toolbar(value: CustomBuilder)
14
15Creates a toolbar bound to the component in the window's title bar section. The toolbar position corresponds to the component's position in the layout. The [CustomBuilder](ts-types.md#custombuilder8) must consist of [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) components to take effect.
16
17**System capability**: SystemCapability.ArkUI.ArkUI.Full
18
19**Parameters**
20
21| Name| Type                                       | Mandatory| Description                                           |
22| ------ | ------------------------------------------- | ---- | ----------------------------------------------- |
23| value  | [CustomBuilder](ts-types.md#custombuilder8) | Yes  | Custom toolbar of the CustomBuilder type for the current component.|
24
25>  **NOTE**
26>  1. Only fixed title bars are supported; floating title bars in three-button navigation mode are not supported.
27>
28>  2. You can customize the toolbar layout and place it on the left or right side. However, if the number of elements exceeds the available space, layout truncation or focus frame overlap may occur, rendering some actions invisible or causing interaction conflicts. There is no automatic shrinking, so keep the number of elements reasonable.
29>
30>  3. The toolbar only supports single-line layouts, so avoid putting multi-line elements in it.
31>
32>  4. The toolbar only works when [NavigationMode](ts-basic-components-navigation.md#navigationmode9) is set to **Split**. It does not work with **Stack** or **Auto** modes.
33>
34>  5. The title bar height dynamically adjusts based on the [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) components in the toolbar:
35>     * There is a default 4 vp margin between the [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) components and the title bar.
36>     * If the tallest [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) component is less than or equal to 48 vp, the title bar height will adjust to 56 vp. This setting is suitable for universal components such as title bars, toolbars, and search bars.
37>     * If the tallest [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) component is between 48 vp and 56 vp, the title bar height will adjust to 64 vp. This setting is suitable for toolbars that display both icons and text.
38>     * If the tallest [ToolBarItem](ts-basic-components-toolbaritem.md#toolbaritem) component exceeds 56 vp, the title bar height will adjust to 72 vp. If it exceeds 64 vp, the title bar height will remain at 72 vp, and any excess area will be clipped.
39
40## Example
41
42This example demonstrates how to:
43
441. Bind the universal **toolbar** attribute to a [Button](ts-basic-components-button.md#button) component under [Navigation](ts-basic-components-navigation.md#navigation), adding two button toolbar items at the start of the **Navbar** section in the title bar.
452. Bind the **toolbar** attribute to a [Text](ts-basic-components-text.md#text) component under [NavDestination](ts-basic-components-navdestination.md#navdestination) to add a slider and a search bar component as toolbar items at the end of the **NavDestination** section in the title bar.
46
47```ts
48// xxx.ets
49@Entry
50@Component
51struct SideBarContainerExample {
52  normalIcon: Resource = $r("app.media.startIcon")
53  selectedIcon: Resource = $r("app.media.startIcon")
54  @State arr: number[] = [1, 2, 3]
55  @State current: number = 1
56  @Provide('navPathStack') navPathStack: NavPathStack = new NavPathStack()
57
58  @Builder
59  MyToolBar() {
60    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_LEADING }) {
61      Button("left").height("30vp")
62    }
63
64    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_LEADING }) {
65      Button("right").height("30vp")
66    }
67  }
68
69  @Builder
70  MyToolbarNavDest() {
71    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_TRAILING }) {
72      Slider().width("120vp")
73    }
74
75    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_TRAILING }) {
76      Search().width("120vp")
77    }
78  }
79
80  @Builder
81  PageNavDest(name: string) {
82    if (name = "1")
83    NavDestination() {
84      Column() {
85        Text("add toolbar")
86          .fontSize(30)
87          .toolbar(this.MyToolbarNavDest())
88      }
89      .backgroundColor(Color.Grey)
90    }
91  }
92
93  build() {
94    SideBarContainer(SideBarContainerType.Embed) {
95      Column() {
96        ForEach(this.arr, (item: number) => {
97          Column({ space: 5 }) {
98            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
99            Text("Index0" + item)
100              .fontSize(25)
101              .fontColor(this.current === item ? '#0A59F7' : '#999')
102              .fontFamily('source-sans-pro,cursive,sans-serif')
103          }
104          .onClick(() => {
105            this.current = item
106          })
107        }, (item: string) => item)
108      }.width('100%')
109      .justifyContent(FlexAlign.SpaceEvenly)
110      .backgroundColor('#19000000')
111
112      Navigation(this.navPathStack) {
113        Column() {
114          Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
115            .width('20%')
116            .height(40)
117            .margin(20)
118            .toolbar(this.MyToolBar)
119          Button('showNavDest', { stateEffect: true, type: ButtonType.Capsule })
120            .width('20%')
121            .height(40)
122            .margin(20)
123            .onClick(() => {
124              this.navPathStack.pushPath({ name: "1" })
125            })
126        }
127        .width('100%')
128        .height('100%')
129      }
130      .navBarPosition(NavBarPosition.Start)
131      .navBarWidth("50%")
132      .navBarWidthRange(["25%", "70%"])
133      .hideBackButton(true)
134      .navDestination(this.PageNavDest)
135      .height('100%')
136      .title('Navigation')
137    }
138    .sideBarWidth(150)
139    .minSideBarWidth(50)
140    .maxSideBarWidth(300)
141    .minContentWidth(0)
142    .onChange((value: boolean) => {
143      console.info('status:' + value)
144    })
145    .divider({
146      strokeWidth: '1vp',
147      color: Color.Gray,
148      startMargin: '4vp',
149      endMargin: '4vp'
150    })
151  }
152}
153```
154<!--no_check-->