1# AtomicServiceNavigation 2 3<!--Kit: ArkUI--> 4<!--Subsystem: ArkUI--> 5<!--Owner: @qq_36417014--> 6<!--Designer: @zhangbeilei--> 7<!--Tester: @tinygreyy--> 8<!--Adviser: @zengyawen--> 9 10作为Page页面的根容器使用，其内部默认包含了标题栏、内容区，其中内容区默认首页显示导航内容或非首页显示（[NavDestination](ts-basic-components-navdestination.md)的子组件），首页和非首页通过路由进行切换。 11 12> **说明：** 13> 14> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15 16## 导入模块 17 18``` 19import { AtomicServiceNavigation } from '@kit.ArkUI'; 20``` 21 22## 子组件 23 24可以包含子组件。 25从API Version 10开始，推荐使用[NavPathStack](ts-basic-components-navigation.md#navpathstack10)进行页面路由。 26## AtomicServiceNavigation 27 28``` 29AtomicServiceNavigation({ 30 navPathStack?: NavPathStack, 31 navigationContent: Callback<void>, 32 title?: ResourceStr, 33 titleOptions?: TitleOptions, 34 gradientBackground?: GradientBackground, 35 hideTitleBar?: boolean, 36 navBarWidth?: Length, 37 mode?: NavigationMode, 38 navDestinationBuilder?: NavDestinationBuilder, 39 navBarWidthRange?: [Dimension, Dimension], 40 minContentWidth?: Dimension, 41 sideBarOptions?: sideBarOptions, 42 sideBarContent?: Callback<void>, 43 menus?: CustomBuilder | Array<NavigationMenuItem>, 44 stateChangeCallback?: Callback<boolean>, 45 modeChangeCallback?: Callback<NavigationMode> 46}) 47``` 48 49**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 50 51**装饰器类型：** @Component 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**参数**： 56 57| 名称 | 类型 | 必填 | 装饰器类型|说明 | 58| --------------- | ------ | ---- | ----|----------| 59| navPathStack | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | 否 | @State | 路由栈信息。 | 60| navigationContent | Callback\<void\> | 否 | @BuilderParam | Navigation容器内容。 | 61| title | [ResourceStr](ts-types.md#resourcestr) | 否 |@Prop | 设置页面标题。默认值为空字符串。当titleOptions的titleBarType字段设置为[TitleBarType](#titlebartype18).ROUND_ICON或者[TitleBarType](#titlebartype18).SQUARED_ICON，且设置了titleIcon时，title标题内容将不会显示。 | 62| titleOptions | [TitleOptions](#titleoptions) | 否 | @Prop | 标题栏选项。当titleBarType字段设置为[TitleBarType](#titlebartype18).ROUND_ICON或者[TitleBarType](#titlebartype18).SQUARED_ICON，且设置了titleIcon时，title标题内容将不会显示。 | 63| gradientBackground<sup>18+</sup> | [GradientBackground](#gradientbackground18) | 否 | @Prop | 背景色选项。| 64| hideTitleBar | boolean | 否 | @Prop | 设置是否隐藏标题栏。默认为false。<br>false表示显示标题栏，true表示隐藏标题栏。| 65| navBarWidth | [Length](ts-types.md#length)| 否 | @Prop | 设置导航栏宽度。默认值为240vp。<br>仅在Navigation组件分栏时生效。| 66| mode| [NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明) | 否 | @Prop |设置导航栏的显示模式。<br>支持Stack、Split与Auto模式。| 67| navDestinationBuilder | [NavDestinationBuilder](#navdestinationbuilder) | 否 | @BuilderParam | 创建[NavDestination](ts-basic-components-navdestination.md)组件所需要的Builder数据。 | 68| navBarWidthRange | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | 否 | @Prop |设置导航栏最小和最大宽度（双栏模式下生效）。默认值：最小默认值为240vp，最大默认值为组件宽度的40%，且不大于432vp，如果只设置一个值，则未设置的值按照默认值计算。单位：vp。 | 69| minContentWidth | [Dimension](ts-types.md#dimension10) | 否 | @Prop | 设置导航栏内容区最小宽度（双栏模式下生效）。| 70| sideBarOptions<sup>18+</sup> | [SideBarOptions](#sidebaroptions18) | 否 | @Prop | 侧边栏的功能选项。| 71| sideBarContent<sup>18+</sup> | Callback\<void\> | 否 | @BuilderParam | 侧边栏的内容。| 72| menus<sup>18+</sup> | [CustomBuilder](ts-types.md#custombuilder8) \| Array\<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)\> | 否 | @BuilderParam | 宽屏场景下用户自定义插入的布局样式。默认为空，不显示任何样式。屏幕宽度低于600vp为非宽屏场景，大于等于600vp为宽屏场景。 | 73| stateChangeCallback | Callback\<boolean\> | 否 | - | 导航栏显示状态切换时触发该回调。| 74| modeChangeCallback | Callback\<[NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明)\> | 否 | - | 当Navigation首次显示或者单双栏状态发生变化时触发该回调。| 75 76## TitleOptions 77标题栏选项。 78 79**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83| 名称 | 类型 | 必填 | 说明 | 84| --------------- | ------ | ---- | ---------- | 85| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 标题栏背景颜色。 | 86| isBlurEnabled | boolean | 否 | 标题栏是否模糊，默认值：true，表示标题栏模糊。 | 87| barStyle | [BarStyle](ts-basic-components-navigation.md#barstyle12枚举说明) | 否 | 标题栏样式属性设置。 | 88| titleBarType<sup>18+</sup> | [TitleBarType](#titlebartype18) | 否 | 设置标题栏类型。默认值为TitleBarType.ROUND_ICON。 | 89| titleIcon<sup>18+</sup> | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 设置标题栏的图标。默认值为$r('sys.color.ohos_id_color_titlebar_icon')。 | 90 91## GradientBackground<sup>18+</sup> 92供开发者设置品牌渐变色。 93 94**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98| 名称 | 类型 | 必填 | 说明 | 99| --------------- | ------ | ---- | ---------- | 100| primaryColor | [ResourceColor](ts-types.md#resourcecolor) | 是 | 单色渐变色彩值和双色渐变第一色彩值。无默认值。| 101| secondaryColor |[ResourceColor](ts-types.md#resourcecolor) | 否 |双色渐变色第二色彩值。无默认值。| 102| backgroundTheme |[BackgroundTheme<sup>18+</sup>](#backgroundtheme18) | 否 |导航栏背景底色。默认值为DEFAULT。| 103| mixMode | [MixMode<sup>18+</sup>](#mixmode18) | 否 |同时设置primaryColor和secondaryColor时此参数生效。代表双色渐变下两种颜色的融合方式。默认值为TOWARDS。| 104| alpha | [GradientAlpha<sup>18+</sup>](#gradientalpha18) | 否 |设置渐变色显示区域的透明度。默认值为OPACITY_20。| 105 106## NavDestinationBuilder 107 108type NavDestinationBuilder = (name: string, param?: Object) => void 109 110NavDestination组件内容。 111 112**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 113 114**系统能力：** SystemCapability.ArkUI.ArkUI.Full 115 116**参数：** 117 118| 参数名 | 类型 | 必填 | 说明 | 119| --------------- | ------ | ---- | ---------- | 120| name | string | 是 | [NavDestination](ts-basic-components-navdestination.md)页面名称。 | 121| param | Object | 否 | [NavDestination](ts-basic-components-navdestination.md)页面详细参数。 | 122 123## MixMode<sup>18+</sup> 124背景色颜色混合模式的可选项。 125 126**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130| 名称 | 值 | 说明 | 131| --------------- | ------ |-----| 132| AVERAGE | 1 | 两种颜色各占一半。 | 133| CROSS | 2 | 一种颜色从另一种颜色中穿过。 | 134| TOWARDS | 3 | 一种颜色渐变为另一种颜色。 | 135 136## TitleBarType<sup>18+</sup> 137标题栏类型的可选项，默认值为ROUND_ICON。 138 139**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 140 141**系统能力：** SystemCapability.ArkUI.ArkUI.Full 142 143| 名称 | 值 | 说明 | 144| --------------- | ------ |-----| 145| SQUARED_ICON | 1 | 方形图标样式。 | 146| ROUND_ICON | 2 | 圆形图标样式。 | 147| DRAWER | 3 | 抽屉样式。 | 148 149## GradientAlpha<sup>18+</sup> 150导航栏背景底色的可选项。 151 152**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 153 154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 155 156| 名称 | 值 | 说明 | 157| --------------- | ------ |-----| 158| OPACITY_20| 1 | 不透明度为0.2。 | 159| OPACITY_60| 2 | 不透明度为0.6。| 160| OPACITY_80| 3 | 不透明度为0.8。 | 161| OPACITY_100| 4 | 不透明度为1.0。 | 162 163## BackgroundTheme<sup>18+</sup> 164导航栏背景色底色的可选项。 165 166**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 167 168**系统能力：** SystemCapability.ArkUI.ArkUI.Full 169 170| 名称 | 值 | 说明 | 171| --------------- | ------ |-----| 172| DARK | 1 | 背景底色为黑色。 | 173| LIGHT | 2 | 背景底色为白色。| 174| DEFAULT | 3 | 背景底色为灰白色。颜色值`#F1F3F5` 。| 175 176## SideBarOptions<sup>18+</sup> 177侧边栏的功能选项。 178 179**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183| 名称 | 类型 | 必填 | 说明 | 184| --------------- | ------ | ---- | ---------- | 185| sideBarBackground | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置侧边栏的背景颜色。默认为$r('sys.color.ohos_id_color_sub_background')。 | 186| onChange | Callback\<boolean\> | 否 | 侧边栏显示隐藏回调。 | 187| sideBarIcon | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 侧边栏里的返回图标。默认值为$r('sys.symbol.open_sidebar')。 | 188 189## 示例 190 191### 示例1（AtomicServiceNavigation页面布局与渐变色背景） 192AtomicServiceNavigation的基础样式，并展示渐变色背景。 193 194```ts 195import { AtomicServiceNavigation, MixMode, GradientAlpha, BackgroundTheme } from '@kit.ArkUI'; 196import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 197@Entry 198@Component 199struct Index { 200 @State message: string = '主题'; 201 childNavStack: NavPathStack = new NavPathStack(); 202 @Builder 203 tabContent1() { 204 Text('first page') 205 .onClick(() => { 206 this.childNavStack.pushPath({ name: 'page one' }) 207 }) 208 } 209 210 @Builder 211 tabContent2() { 212 Text('second page') 213 } 214 215 @Builder 216 tabContent3() { 217 Text('third page') 218 } 219 220 @Builder 221 navigationContent() { 222 AtomicServiceTabs({ 223 tabContents: [ 224 () => { 225 this.tabContent1() 226 }, 227 () => { 228 this.tabContent2() 229 }, 230 () => { 231 this.tabContent3() 232 } 233 ], 234 tabBarOptionsArray: [ 235 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), '功能1'), 236 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 237 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能3') 238 ], 239 tabBarPosition: TabBarPosition.BOTTOM, 240 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 241 onTabBarClick: (index: Number) => { 242 if (index == 0) { 243 this.message = '功能1'; 244 } else if (index == 1) { 245 this.message = '功能2'; 246 } else { 247 this.message = '功能3'; 248 } 249 } 250 }) 251 } 252 253 @Builder 254 pageMap(name: string) { 255 if (name === 'page one') { 256 PageOne() 257 } else if (name === 'page two') { 258 PageTwo() 259 } 260 } 261 262 build() { 263 Row() { 264 Column() { 265 AtomicServiceNavigation({ 266 navigationContent: () => { 267 this.navigationContent() 268 }, 269 title: this.message, 270 titleOptions: { 271 isBlurEnabled: false 272 }, 273 gradientBackground: { 274 primaryColor: '#FF0000', 275 secondaryColor: '#00FF00', 276 backgroundTheme: BackgroundTheme.LIGHT, 277 mixMode: MixMode.AVERAGE, 278 alpha: GradientAlpha.OPACITY_100 279 }, 280 navDestinationBuilder: this.pageMap, 281 navPathStack: this.childNavStack, 282 mode: NavigationMode.Stack 283 }) 284 } 285 .width('100%') 286 } 287 .height('100%') 288 } 289} 290 291@Component 292export struct PageOne { 293 pageInfo: NavPathStack = new NavPathStack(); 294 295 build() { 296 NavDestination() { 297 Button('Next') 298 .onClick(() => { 299 this.pageInfo.pushPath({ name: 'page two'}) 300 }) 301 } 302 .title('PageOne') 303 .onReady((context: NavDestinationContext) => { 304 this.pageInfo = context.pathStack; 305 }) 306 } 307} 308 309@Component 310export struct PageTwo { 311 pageInfo: NavPathStack = new NavPathStack(); 312 313 build() { 314 NavDestination() { 315 Button('End') 316 } 317 .title('PageTwo') 318 .onReady((context: NavDestinationContext) => { 319 this.pageInfo = context.pathStack; 320 }) 321 } 322} 323``` 324 325 326 327### 示例2（抽屉模式，宽屏场景下插入自定义布局） 328 329设备宽屏场景（宽度大于600vp）下设置抽屉模式，用户在标题栏插入自定义布局。 330 331```ts 332import { AtomicServiceNavigation, TitleBarType } from '@kit.ArkUI'; 333import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 334 335@Entry 336@Component 337struct Index { 338 @State message: string = 'Hello World'; 339 childNavStack: NavPathStack = new NavPathStack(); 340 341 @Builder 342 tabContent1() { 343 Text('first page') 344 .onClick(() => { 345 this.childNavStack.pushPath({ name: 'page one' }) 346 }) 347 } 348 349 @Builder 350 tabContent2() { 351 Text('second page') 352 } 353 354 @Builder 355 tabContent3() { 356 Text('third page') 357 } 358 359 @Builder 360 navigationContent() { 361 AtomicServiceTabs({ 362 tabContents: [ 363 () => { 364 this.tabContent1() 365 }, 366 () => { 367 this.tabContent2() 368 }, 369 () => { 370 this.tabContent3() 371 } 372 ], 373 tabBarOptionsArray: [ 374 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), '功能1'), 375 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 376 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能3') 377 ], 378 tabBarPosition: TabBarPosition.BOTTOM, 379 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 380 onTabBarClick: (index: Number) => { 381 if (index == 0) { 382 this.message = '功能1'; 383 } else if (index == 1) { 384 this.message = '功能2'; 385 } else { 386 this.message = '功能3'; 387 } 388 } 389 }) 390 } 391 392 @Builder 393 pageMap(name: string) { 394 if (name === 'page one') { 395 PageOne() 396 } else if (name === 'page two') { 397 PageTwo() 398 } 399 } 400 401 @State showText: string = 'time: '; 402 @State time: number = 0; 403 404 @Builder 405 insertComp() { 406 Text('This is menus area') 407 .fontColor(Color.Red) 408 .width(200) 409 .height('100%') 410 } 411 412 build() { 413 Column() { 414 AtomicServiceNavigation({ 415 navigationContent: () => { 416 this.navigationContent() 417 }, 418 navDestinationBuilder: this.pageMap, 419 navPathStack: this.childNavStack, 420 title: this.message, 421 titleOptions: { 422 titleIcon: $r('app.media.startIcon'), 423 backgroundColor: 'rgb(61, 157, 180)', 424 titleBarType: TitleBarType.DRAWER 425 }, 426 menus: () => { this.insertComp() }, 427 mode: NavigationMode.Stack 428 }) 429 } 430 .width('100%') 431 } 432} 433 434@Component 435export struct PageOne { 436 pageInfo: NavPathStack = new NavPathStack(); 437 438 build() { 439 NavDestination() { 440 Button('Next') 441 .onClick(() => { 442 this.pageInfo.pushPath({ name: 'page two'}) 443 }) 444 } 445 .title('PageOne') 446 .onReady((context: NavDestinationContext) => { 447 this.pageInfo = context.pathStack; 448 }) 449 } 450} 451 452@Component 453export struct PageTwo { 454 pageInfo: NavPathStack = new NavPathStack(); 455 456 build() { 457 NavDestination() { 458 Button('End') 459 } 460 .title('PageTwo') 461 .onReady((context: NavDestinationContext) => { 462 this.pageInfo = context.pathStack; 463 }) 464 } 465} 466``` 467 468 469### 示例3（边栏使用场景） 470 471设置边栏：背景色与内容样式。 472 473```ts 474import { AtomicServiceNavigation, TitleBarType } from '@kit.ArkUI'; 475import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 476 477@Entry 478@Component 479struct Index { 480 @State message: string = 'Hello World'; 481 childNavStack: NavPathStack = new NavPathStack(); 482 483 @Builder 484 tabContent1() { 485 Text('first page') 486 .onClick(() => { 487 this.childNavStack.pushPath({ name: 'page one' }) 488 }) 489 } 490 491 @Builder 492 tabContent2() { 493 Text('second page') 494 } 495 496 @Builder 497 tabContent3() { 498 Text('third page') 499 } 500 501 @Builder 502 navigationContent() { 503 AtomicServiceTabs({ 504 tabContents: [ 505 () => { 506 this.tabContent1() 507 }, 508 () => { 509 this.tabContent2() 510 }, 511 () => { 512 this.tabContent3() 513 } 514 ], 515 tabBarOptionsArray: [ 516 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), '功能1'), 517 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 518 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能3') 519 ], 520 tabBarPosition: TabBarPosition.BOTTOM, 521 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 522 onTabBarClick: (index: Number) => { 523 if (index == 0) { 524 this.message = '功能1'; 525 } else if (index == 1) { 526 this.message = '功能2'; 527 } else { 528 this.message = '功能3'; 529 } 530 } 531 }) 532 } 533 534 @Builder 535 pageMap(name: string) { 536 if (name === 'page one') { 537 PageOne() 538 } else if (name === 'page two') { 539 PageTwo() 540 } 541 } 542 543 @State showText: string = 'time: '; 544 @State time: number = 0; 545 546 @Builder 547 insertComp() { 548 Text('This is menus area') 549 .fontColor(Color.Red) 550 .width(200) 551 .height('100%') 552 } 553 554 @Builder 555 sideBarContentBuilder() { 556 Text('This is sideBar content area') 557 .fontSize(20) 558 } 559 560 build() { 561 Column() { 562 AtomicServiceNavigation({ 563 navigationContent: () => { 564 this.navigationContent() 565 }, 566 navDestinationBuilder: this.pageMap, 567 navPathStack: this.childNavStack, 568 title: this.message, 569 titleOptions: { 570 titleIcon: $r('app.media.startIcon'), 571 backgroundColor: 'rgb(61, 157, 180)', 572 titleBarType: TitleBarType.DRAWER 573 }, 574 sideBarOptions: { 575 sideBarBackground: '#409EFF' 576 }, 577 sideBarContent: () => { this.sideBarContentBuilder() }, 578 mode: NavigationMode.Stack 579 }) 580 } 581 .width('100%') 582 } 583} 584 585@Component 586export struct PageOne { 587 pageInfo: NavPathStack = new NavPathStack(); 588 589 build() { 590 NavDestination() { 591 Button('Next') 592 .onClick(() => { 593 this.pageInfo.pushPath({ name: 'page two'}) 594 }) 595 } 596 .title('PageOne') 597 .onReady((context: NavDestinationContext) => { 598 this.pageInfo = context.pathStack; 599 }) 600 } 601} 602 603@Component 604export struct PageTwo { 605 pageInfo: NavPathStack = new NavPathStack(); 606 607 build() { 608 NavDestination() { 609 Button('End') 610 } 611 .title('PageTwo') 612 .onReady((context: NavDestinationContext) => { 613 this.pageInfo = context.pathStack; 614 }) 615 } 616} 617``` 618
