• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 工具栏设置
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @jiangtao92-->
5<!--Designer: @piggyguy-->
6<!--Tester: @songyanhong-->
7<!--Adviser: @HelloCrease-->
8
9设置组件对应的工具栏。
10
11>  **说明：**
12>
13>  从API version 20开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14>
15>  该toolbar为组件通用属性，请注意与[Navigation](ts-basic-components-navigation.md)组件自身的toolbar属性进行区分。
16
17## toolbar
18
19toolbar(value: CustomBuilder): T
20
21为绑定该属性的组件，在窗口顶部标题栏相应分栏创建与该组件绑定的由[ToolBarItem](ts-basic-components-toolbaritem.md)构成的工具栏，分栏位置依据绑定该属性的组件所在分栏位置确定。[CustomBuilder](ts-types.md#custombuilder8)必须由[ToolBarItem](ts-basic-components-toolbaritem.md)构成，该工具栏才能生效。
22
23**系统能力：** SystemCapability.ArkUI.ArkUI.Full
24
25**参数：**
26
27| 参数名 | 类型                                        | 必填 | 说明                                            |
28| ------ | ------------------------------------------- | ---- | ----------------------------------------------- |
29| value  | [CustomBuilder](ts-types.md#custombuilder8) | 是   | 为当前组件配置CustomBuilder类型的自定义工具栏。 |
30
31**返回值：**
32
33| 类型 | 说明 |
34| -------- | -------- |
35| T | 返回当前组件。 |
36
37>  **说明：**
38>  1. toolbar仅支持固定标题栏，不支持悬浮标题栏（仅限三键模式）。
39>
40>  2. toolbar支持自定义组件布局，可将其置于特定分栏位置（左侧或右侧）。但需注意，当元素数量超过可用空间时，将导致布局截断或焦点框遮挡等现象，从而使部分操作项不可见或引发交互冲突。此时，元素不会自动缩略，建议合理控制元素数量。
41>
42>  3. toolbar当前仅支持单行布局，不支持多行布局，因此应避免在一个toolbar中放置多行布局的元素。
43>
44>  4. toolbar仅支持在[NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明)为Split的场景中使用。当[NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明)设置为Stack或Auto时，无法应用toolbar。
45>
46>  5. 标题栏高度会根据toolbar内的[ToolBarItem](ts-basic-components-toolbaritem.md)组件在有限范围内浮动：
47>     * [ToolBarItem](ts-basic-components-toolbaritem.md)组件的会与标题栏默认存在4VP的margin（外边距）。
48>     * 当[ToolBarItem](ts-basic-components-toolbaritem.md)组件的最大高度小于等于48VP时，标题栏高度会调整为56VP，此设置适用于标题栏、工具栏、搜索栏等通用组件。
49>     * 当[ToolBarItem](ts-basic-components-toolbaritem.md)组件的最大高度介于48VP到56VP之间时，标题栏高度会调整为64VP，此设置适用于图标与文字同时呈现的工具栏。
50>     * 当[ToolBarItem](ts-basic-components-toolbaritem.md)组件的最大高度超过56VP时，标题栏高度会调整为72VP。如果[ToolBarItem](ts-basic-components-toolbaritem.md)组件的最大高度超过64VP，则标题栏的高度保持为72VP，超出的区域会发生裁剪。
51
52## 示例
53
54该示例通过为[Navigation](ts-basic-components-navigation.md)下的[Button](ts-basic-components-button.md)组件绑定toolbar通用属性，为标题栏Navbar分栏开头位置添加包含两个[Button](ts-basic-components-button.md)组件工具栏项。为[NavDestination](ts-basic-components-navdestination.md)下的[Text](ts-basic-components-text.md)组件绑定toolbar通用属性，为标题栏NavDestination分栏末尾位置添加包含一个滑动条组件和一个搜索栏组件工具栏项。
55
56```ts
57// xxx.ets
58@Entry
59@Component
60struct SideBarContainerExample {
61  normalIcon: Resource = $r("app.media.startIcon")
62  selectedIcon: Resource = $r("app.media.startIcon")
63  @State arr: number[] = [1, 2, 3]
64  @State current: number = 1
65  @Provide('navPathStack') navPathStack: NavPathStack = new NavPathStack()
66
67  @Builder
68  MyToolBar() {
69    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_LEADING }) {
70      Button("left").height("30vp")
71    }
72
73    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_LEADING }) {
74      Button("right").height("30vp")
75    }
76  }
77
78  @Builder
79  MyToolbarNavDest() {
80    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_TRAILING }) {
81      Slider().width("120vp")
82    }
83
84    ToolBarItem({ placement: ToolBarItemPlacement.TOP_BAR_TRAILING }) {
85      Search().width("120vp")
86    }
87  }
88
89  @Builder
90  PageNavDest(name: string) {
91    NavDestination() {
92      Column() {
93        Text("add toolbar")
94          .fontSize(30)
95          .toolbar(this.MyToolbarNavDest())
96      }
97      .backgroundColor(Color.Grey)
98    }
99  }
100
101  build() {
102    SideBarContainer(SideBarContainerType.Embed) {
103      Column() {
104        ForEach(this.arr, (item: number) => {
105          Column({ space: 5 }) {
106            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
107            Text("Index0" + item)
108              .fontSize(25)
109              .fontColor(this.current === item ? '#0A59F7' : '#999')
110              .fontFamily('source-sans-pro,cursive,sans-serif')
111          }
112          .onClick(() => {
113            this.current = item
114          })
115        }, (item: number) => item.toString())
116      }.width('100%')
117      .justifyContent(FlexAlign.SpaceEvenly)
118      .backgroundColor('#19000000')
119
120      Navigation(this.navPathStack) {
121        Column() {
122          Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
123            .width('20%')
124            .height(40)
125            .margin(20)
126            .toolbar(this.MyToolBar)
127          Button('showNavDest', { stateEffect: true, type: ButtonType.Capsule })
128            .width('20%')
129            .height(40)
130            .margin(20)
131            .onClick(() => {
132              this.navPathStack.pushPath({ name: "1" })
133            })
134        }
135        .width('100%')
136        .height('100%')
137      }
138      .navBarPosition(NavBarPosition.Start)
139      .navBarWidth("50%")
140      .navBarWidthRange(["25%", "70%"])
141      .hideBackButton(true)
142      .navDestination(this.PageNavDest)
143      .height('100%')
144      .title('Navigation')
145    }
146    .sideBarWidth(150)
147    .minSideBarWidth(50)
148    .maxSideBarWidth(300)
149    .minContentWidth(0)
150    .onChange((value: boolean) => {
151      console.info('status:' + value)
152    })
153    .divider({
154      strokeWidth: '1vp',
155      color: Color.Gray,
156      startMargin: '4vp',
157      endMargin: '4vp'
158    })
159  }
160}
161```
162![toolbar.png](figures/toolbar.png)