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