1# AtomicServiceNavigation 2 3**AtomicServiceNavigation** is a component that serves as the root container of a page. By default, it includes a title bar, content area, and toolbar. The content area switches between the home page content (child components of [NavDestination](ts-basic-components-navdestination.md)) and non-home page content through routing. 4 5> **NOTE** 6> 7> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11``` 12import { AtomicServiceNavigation } from '@kit.ArkUI'; 13``` 14 15## Child Components 16 17Supported 18Since API version 10, you are advised to use [NavPathStack](ts-basic-components-navigation.md#navpathstack10) for page routing. 19## AtomicServiceNavigation 20 21``` 22AtomicServiceNavigation({ 23 navPathStack?: NavPathStack, 24 navigationContent: Callback<void>, 25 title?: ResourceStr, 26 titleOptions?: TitleOptions, 27 gradientBackground?: GradientBackground, 28 hideTitleBar?: boolean, 29 navBarWidth?: Length, 30 mode?: NavigationMode, 31 navDestinationBuilder?: NavDestinationBuilder, 32 navBarWidthRange?: [Dimension, Dimension], 33 minContentWidth?: Dimension, 34 sideBarOptions?: sideBarOptions, 35 sideBarContent?: Callback<void>, 36 menus?: CustomBuilder | Array<NavigationMenuItem>, 37 stateChangeCallback?: Callback<boolean>, 38 modeChangeCallback?: Callback<NavigationMode> 39}) 40``` 41 42**Atomic service API**: This API can be used in atomic services since API version 12. 43 44**Decorator**: @Component 45 46**System capability**: SystemCapability.ArkUI.ArkUI.Full 47 48**Parameters** 49 50| Name| Type| Mandatory| Decorator|Description| 51| --------------- | ------ | ---- | ----|----------| 52| navPathStack | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | No| @State | Information about the navigation stack.| 53| navigationContent | Callback\<void\> | No| @BuilderParam | Content of the navigation container.| 54| title | [ResourceStr](ts-types.md#resourcestr) | No|@Prop | Page title. The default value is an empty string. Title text will be hidden when the **titleBarType** field of **titleOption** is set to **[TitleBarType](#titlebartype18).ROUND_ICON** or **[TitleBarType](#titlebartype18).SQUARED_ICON** and **titleIcon** is configured.| 55| titleOptions | [TitleOptions](#titleoptions) | No| @Prop | Title bar options. Title text will be hidden when the **titleBarType** field of **titleBarType** is set to **[TitleBarType](#titlebartype18).ROUND_ICON** or **[TitleBarType](#titlebartype18).SQUARED_ICON** and **titleIcon** is configured.| 56| gradientBackground<sup>18+</sup> | [GradientBackground](#gradientbackground18) | No| @Prop | Background color options.| 57| hideTitleBar | boolean | No| @Prop | Whether to hide the title bar. The default value is **false**.<br>The value **true** means to hide the title bar, and **false** means the opposite.| 58| navBarWidth | [Length](ts-types.md#length)| No| @Prop | Width of the navigation bar. The default value is **240vp**.<br>This attribute takes effect only when the component is split.| 59| mode| [NavigationMode](ts-basic-components-navigation.md#navigationmode9)| No| @Prop |Display mode of the navigation bar.<br>Available options are **Stack**, **Split**, and **Auto**.| 60| navDestinationBuilder | [NavDestinationBuilder](#navdestinationbuilder) | No| @BuilderParam | Builder data required for creating the [NavDestination](ts-basic-components-navdestination.md) component.| 61| navBarWidthRange | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | No| @Prop |Minimum and maximum widths of the navigation bar (effective in dual-column mode). Default value: **240vp** for the minimum value; 40% of the component width (not greater than 432 vp) for the maximum value; if either of the widths is not set, the default value is used for that width. Unit: vp.| 62| minContentWidth | [Dimension](ts-types.md#dimension10) | No| @Prop | Minimum width of the navigation bar content area (effective in dual-column mode).| 63| sideBarOptions<sup>18+</sup> | [SideBarOptions](#sidebaroptions18) | No| @Prop | Sidebar options.| 64| sideBarContent<sup>18+</sup> | Callback\<void\> | No| @BuilderParam | Content of the sidebar.| 65| menus<sup>18+</sup> | [CustomBuilder](ts-types.md#custombuilder8) \| Array\<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)\> | No| @BuilderParam | Custom layout styles for wide-screen scenarios. The default value is empty, with no styles displayed. Wide-screen scenarios refer to scenarios where the screen width is greater than or equal to 600 vp.| 66| stateChangeCallback | Callback\<boolean\> | No| - | Callback invoked when the navigation bar visibility status changes.| 67| modeChangeCallback | Callback\<[NavigationMode](ts-basic-components-navigation.md#navigationmode9)\>| No| - | Callback invoked when the component is displayed for the first time or its display mode switches between single-column and dual-column.| 68 69## TitleOptions 70Title bar options. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76| Name| Type| Mandatory| Description| 77| --------------- | ------ | ---- | ---------- | 78| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No| Background color of the title bar.| 79| isBlurEnabled | boolean | No| Whether the title bar is blurred.<br>**true** (default): The title bar is blurred.<br>**false**: The title bar is not blurred.| 80| barStyle | [BarStyle](ts-basic-components-navigation.md#barstyle12) | No| Style options of the title bar.| 81| titleBarType<sup>18+</sup> | [TitleBarType](#titlebartype18) | No| Type of the title bar. <br>Default value: **TitleBarType.ROUND_ICON**| 82| titleIcon<sup>18+</sup> | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Icon of the title bar. Default value: **$r('sys.color.ohos_id_color_titlebar_icon')**| 83 84## GradientBackground<sup>18+</sup> 85Provides options for setting gradient colors for branding. 86 87**Atomic service API**: This API can be used in atomic services since API version 18. 88 89**System capability**: SystemCapability.ArkUI.ArkUI.Full 90 91| Name| Type| Mandatory| Description| 92| --------------- | ------ | ---- | ---------- | 93| primaryColor | [ResourceColor](ts-types.md#resourcecolor) | Yes| Color value for single-color gradients and the first color in dual-color gradients.<br> No default value.| 94| secondaryColor |[ResourceColor](ts-types.md#resourcecolor) | No|Second color in dual-color gradients.<br> No default value.| 95| backgroundTheme |[BackgroundTheme<sup>18+</sup>](#backgroundtheme18) | No|Background theme of the navigation bar. <br>Default value: **DEFAULT**| 96| mixMode | [MixMode<sup>18+</sup>](#mixmode18) | No|How the two colors blend in dual-color gradients. It is effective only when both **primaryColor** and **secondaryColor** are set. <br>Default value: **TOWARDS**| 97| alpha | [GradientAlpha<sup>18+</sup>](#gradientalpha18) | No|Transparency level for the gradient display area. <br>Default value: **OPACITY_20**| 98 99## NavDestinationBuilder 100 101type NavDestinationBuilder = (name: string, param?: Object) => void 102 103**Atomic service API**: This API can be used in atomic services since API version 12. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107| Name| Type| Mandatory| Description| 108| --------------- | ------ | ---- | ---------- | 109| name | string | Yes| Name of the [NavDestination](ts-basic-components-navdestination.md) page.| 110| param | Object | No| Settings of the [NavDestination](ts-basic-components-navdestination.md) page.| 111 112## MixMode<sup>18+</sup> 113Provides options for background color blending modes. 114 115**Atomic service API**: This API can be used in atomic services since API version 18. 116 117**System capability**: SystemCapability.ArkUI.ArkUI.Full 118 119| Name| Value| Description| 120| --------------- | ------ |-----| 121| AVERAGE | 1 | Both colors are evenly mixed. | 122| CROSS | 2 | One color passes through the other.| 123| TOWARDS | 3 | One color gradually blends into the other.| 124 125## TitleBarType<sup>18+</sup> 126Enumerates the title bar types. The default type is **ROUND_ICON**. 127 128**Atomic service API**: This API can be used in atomic services since API version 18. 129 130**System capability**: SystemCapability.ArkUI.ArkUI.Full 131 132| Name| Value| Description| 133| --------------- | ------ |-----| 134| SQUARED_ICON | 1 | Square icon style.| 135| ROUND_ICON | 2 | Round icon style.| 136| DRAWER | 3 | Drawer style.| 137 138## GradientAlpha<sup>18+</sup> 139Enumerates the transparency levels of the navigation bar background. 140 141**Atomic service API**: This API can be used in atomic services since API version 18. 142 143**System capability**: SystemCapability.ArkUI.ArkUI.Full 144 145| Name| Value| Description| 146| --------------- | ------ |-----| 147| OPACITY_20| 1 | Transparency level of 0.2.| 148| OPACITY_60| 2 | Transparency level of 0.6.| 149| OPACITY_80| 3 | Transparency level of 0.8.| 150| OPACITY_100| 4 | Transparency level of 1.0.| 151 152## BackgroundTheme<sup>18+</sup> 153Enumerates the navigation bar background themes. 154 155**Atomic service API**: This API can be used in atomic services since API version 18. 156 157**System capability**: SystemCapability.ArkUI.ArkUI.Full 158 159| Name| Value| Description| 160| --------------- | ------ |-----| 161| DARK | 1 | Dark theme.| 162| LIGHT | 2 | Light theme.| 163| DEFAULT | 3 | Light gray theme, with the color value of #F1F3F5.| 164 165## SideBarOptions<sup>18+</sup> 166Provides sidebar options. 167 168**Atomic service API**: This API can be used in atomic services since API version 18. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172| Name| Type| Mandatory| Description| 173| --------------- | ------ | ---- | ---------- | 174| sideBarBackground | [ResourceColor](ts-types.md#resourcecolor) | No| Background color of the sidebar. <br>Default value: **$r('sys.color.ohos_id_color_sub_background')**| 175| onChange | Callback\<boolean\> | No| Callback triggered when the sidebar is shown or hidden.| 176| sideBarIcon | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Icon of the sidebar. Default value: **$r('sys.symbol.open_sidebar')**| 177 178## Example 179 180### Example 1: Setting the Layout and Gradient Background 181This example demonstrates how to set the basic style of the **AtomicServiceNavigation** component with a gradient background. 182 183```ts 184import { AtomicServiceNavigation, MixMode, GradientAlpha, BackgroundTheme } from '@kit.ArkUI'; 185import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 186@Entry 187@Component 188struct Index { 189 @State message: string = 'Title'; 190 childNavStack: NavPathStack = new NavPathStack(); 191 @Builder 192 tabContent1() { 193 Text('first page') 194 .onClick(() => { 195 this.childNavStack.pushPath({ name: 'page one' }) 196 }) 197 } 198 199 @Builder 200 tabContent2() { 201 Text('second page') 202 } 203 204 @Builder 205 tabContent3() { 206 Text('third page') 207 } 208 209 @Builder 210 navigationContent() { 211 AtomicServiceTabs({ 212 tabContents: [ 213 () => { 214 this.tabContent1() 215 }, 216 () => { 217 this.tabContent2() 218 }, 219 () => { 220 this.tabContent3() 221 } 222 ], 223 tabBarOptionsArray: [ 224 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), 'Feature 1'), 225 new TabBarOptions($r('sys.media.ohos_ic_public_location'), 'Feature 2', Color.Green, Color.Red), 226 new TabBarOptions($r('sys.media.ohos_ic_public_more'), 'Feature 3') 227 ], 228 tabBarPosition: TabBarPosition.BOTTOM, 229 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 230 onTabBarClick: (index: Number) => { 231 if (index == 0) { 232 this.message = 'Feature 1'; 233 } else if (index == 1) { 234 this.message = 'Feature 2'; 235 } else { 236 this.message = 'Feature 3'; 237 } 238 } 239 }) 240 } 241 242 @Builder 243 pageMap(name: string) { 244 if (name === 'page one') { 245 PageOne() 246 } else if (name === 'page two') { 247 PageTwo() 248 } 249 } 250 251 build() { 252 Row() { 253 Column() { 254 AtomicServiceNavigation({ 255 navigationContent: () => { 256 this.navigationContent() 257 }, 258 title: this.message, 259 titleOptions: { 260 isBlurEnabled: false 261 }, 262 gradientBackground: { 263 primaryColor: '#FF0000', 264 secondaryColor: '#00FF00', 265 backgroundTheme: BackgroundTheme.LIGHT, 266 mixMode: MixMode.AVERAGE, 267 alpha: GradientAlpha.OPACITY_100 268 }, 269 navDestinationBuilder: this.pageMap, 270 navPathStack: this.childNavStack, 271 mode: NavigationMode.Stack 272 }) 273 } 274 .width('100%') 275 } 276 .height('100%') 277 } 278} 279 280@Component 281export struct PageOne { 282 pageInfo: NavPathStack = new NavPathStack(); 283 284 build() { 285 NavDestination() { 286 Button('Next') 287 .onClick(() => { 288 this.pageInfo.pushPath({ name: 'page two'}) 289 }) 290 } 291 .title('PageOne') 292 .onReady((context: NavDestinationContext) => { 293 this.pageInfo = context.pathStack; 294 }) 295 } 296} 297 298@Component 299export struct PageTwo { 300 pageInfo: NavPathStack = new NavPathStack(); 301 302 build() { 303 NavDestination() { 304 Button('End') 305 } 306 .title('PageTwo') 307 .onReady((context: NavDestinationContext) => { 308 this.pageInfo = context.pathStack; 309 }) 310 } 311} 312``` 313 314 315 316### Example 2: Implementing the Drawer Style with Custom Layouts for Wide-Screen Scenarios 317 318This example demonstrates how to implement the drawer style and insert custom layouts into the title bar in wide-screen scenarios (width > 600 vp). 319 320```ts 321import { AtomicServiceNavigation, TitleBarType } from '@kit.ArkUI'; 322import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 323 324@Entry 325@Component 326struct Index { 327 @State message: string = 'Hello World'; 328 childNavStack: NavPathStack = new NavPathStack(); 329 330 @Builder 331 tabContent1() { 332 Text('First page') 333 .onClick(() => { 334 this.childNavStack.pushPath({ name: 'page one' }) 335 }) 336 } 337 338 @Builder 339 tabContent2() { 340 Text('Second page') 341 } 342 343 @Builder 344 tabContent3() { 345 Text('Third page') 346 } 347 348 @Builder 349 navigationContent() { 350 AtomicServiceTabs({ 351 tabContents: [ 352 () => { 353 this.tabContent1() 354 }, 355 () => { 356 this.tabContent2() 357 }, 358 () => { 359 this.tabContent3() 360 } 361 ], 362 tabBarOptionsArray: [ 363 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), 'Feature 1'), 364 new TabBarOptions($r('sys.media.ohos_ic_public_location'), 'Feature 2', Color.Green, Color.Red), 365 new TabBarOptions($r('sys.media.ohos_ic_public_more'), 'Feature 3') 366 ], 367 tabBarPosition: TabBarPosition.BOTTOM, 368 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 369 onTabBarClick: (index: Number) => { 370 if (index == 0) { 371 this.message = 'Feature 1'; 372 } else if (index == 1) { 373 this.message = 'Feature 2'; 374 } else { 375 this.message = 'Feature 3'; 376 } 377 } 378 }) 379 } 380 381 @Builder 382 pageMap(name: string) { 383 if (name === 'page one') { 384 PageOne() 385 } else if (name === 'page two') { 386 PageTwo() 387 } 388 } 389 390 @State showText: string = 'time: '; 391 @State time: number = 0; 392 393 @Builder 394 insertComp() { 395 Text('This is the menu area') 396 .fontColor(Color.Red) 397 .width(200) 398 .height('100%') 399 } 400 401 build() { 402 Column() { 403 AtomicServiceNavigation({ 404 navigationContent: () => { 405 this.navigationContent() 406 }, 407 navDestinationBuilder: this.pageMap, 408 navPathStack: this.childNavStack, 409 title: this.message, 410 titleOptions: { 411 titleIcon: $r('app.media.startIcon'), 412 backgroundColor: 'rgb(61, 157, 180)', 413 titleBarType: TitleBarType.DRAWER 414 }, 415 menus: () => { this.insertComp() }, 416 mode: NavigationMode.Stack 417 }) 418 } 419 .width('100%') 420 } 421} 422 423@Component 424export struct PageOne { 425 pageInfo: NavPathStack = new NavPathStack(); 426 427 build() { 428 NavDestination() { 429 Button('Next') 430 .onClick(() => { 431 this.pageInfo.pushPath({ name: 'page two'}) 432 }) 433 } 434 .title('PageOne') 435 .onReady((context: NavDestinationContext) => { 436 this.pageInfo = context.pathStack; 437 }) 438 } 439} 440 441@Component 442export struct PageTwo { 443 pageInfo: NavPathStack = new NavPathStack(); 444 445 build() { 446 NavDestination() { 447 Button('End') 448 } 449 .title('PageTwo') 450 .onReady((context: NavDestinationContext) => { 451 this.pageInfo = context.pathStack; 452 }) 453 } 454} 455``` 456 457 458### Example 3: Configuring the Sidebar 459 460This example demonstrates how to set the sidebar background color and content style. 461 462```ts 463import { AtomicServiceNavigation, TitleBarType } from '@kit.ArkUI'; 464import { AtomicServiceTabs, TabBarOptions, TabBarPosition } from '@kit.ArkUI'; 465 466@Entry 467@Component 468struct Index { 469 @State message: string = 'Hello World'; 470 childNavStack: NavPathStack = new NavPathStack(); 471 472 @Builder 473 tabContent1() { 474 Text('first page') 475 .onClick(() => { 476 this.childNavStack.pushPath({ name: 'page one' }) 477 }) 478 } 479 480 @Builder 481 tabContent2() { 482 Text('second page') 483 } 484 485 @Builder 486 tabContent3() { 487 Text('third page') 488 } 489 490 @Builder 491 navigationContent() { 492 AtomicServiceTabs({ 493 tabContents: [ 494 () => { 495 this.tabContent1() 496 }, 497 () => { 498 this.tabContent2() 499 }, 500 () => { 501 this.tabContent3() 502 } 503 ], 504 tabBarOptionsArray: [ 505 new TabBarOptions($r('sys.media.ohos_ic_public_phone'), 'Feature 1'), 506 new TabBarOptions($r('sys.media.ohos_ic_public_location'), 'Feature 2', Color.Green, Color.Red), 507 new TabBarOptions($r('sys.media.ohos_ic_public_more'), 'Feature 3') 508 ], 509 tabBarPosition: TabBarPosition.BOTTOM, 510 barBackgroundColor: $r('sys.color.ohos_id_color_bottom_tab_bg'), 511 onTabBarClick: (index: Number) => { 512 if (index == 0) { 513 this.message = 'Feature 1'; 514 } else if (index == 1) { 515 this.message = 'Feature 2'; 516 } else { 517 this.message = 'Feature 3'; 518 } 519 } 520 }) 521 } 522 523 @Builder 524 pageMap(name: string) { 525 if (name === 'page one') { 526 PageOne() 527 } else if (name === 'page two') { 528 PageTwo() 529 } 530 } 531 532 @State showText: string = 'time: '; 533 @State time: number = 0; 534 535 @Builder 536 insertComp() { 537 Text('This is menus area') 538 .fontColor(Color.Red) 539 .width(200) 540 .height('100%') 541 } 542 543 @Builder 544 sideBarContentBuilder() { 545 Text('This is sideBar content area') 546 .fontSize(20) 547 } 548 549 build() { 550 Column() { 551 AtomicServiceNavigation({ 552 navigationContent: () => { 553 this.navigationContent() 554 }, 555 navDestinationBuilder: this.pageMap, 556 navPathStack: this.childNavStack, 557 title: this.message, 558 titleOptions: { 559 titleIcon: $r('app.media.startIcon'), 560 backgroundColor: 'rgb(61, 157, 180)', 561 titleBarType: TitleBarType.DRAWER 562 }, 563 sideBarOptions: { 564 sideBarBackground: '#409EFF' 565 }, 566 sideBarContent: () => { this.sideBarContentBuilder() }, 567 mode: NavigationMode.Stack 568 }) 569 } 570 .width('100%') 571 } 572} 573 574@Component 575export struct PageOne { 576 pageInfo: NavPathStack = new NavPathStack(); 577 578 build() { 579 NavDestination() { 580 Button('Next') 581 .onClick(() => { 582 this.pageInfo.pushPath({ name: 'page two'}) 583 }) 584 } 585 .title('PageOne') 586 .onReady((context: NavDestinationContext) => { 587 this.pageInfo = context.pathStack; 588 }) 589 } 590} 591 592@Component 593export struct PageTwo { 594 pageInfo: NavPathStack = new NavPathStack(); 595 596 build() { 597 NavDestination() { 598 Button('End') 599 } 600 .title('PageTwo') 601 .onReady((context: NavDestinationContext) => { 602 this.pageInfo = context.pathStack; 603 }) 604 } 605} 606``` 607 608
