1# AtomicServiceNavigation 2 3作为Page页面的根容器使用，其内部默认包含了标题栏、内容区，其中内容区默认首页显示导航内容或非首页显示（[NavDestination](ts-basic-components-navdestination.md)的子组件），首页和非首页通过路由进行切换。 4 5> **说明：** 6> 7> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 导入模块 10 11``` 12import { AtomicServiceNavigation } from '@kit.ArkUI'; 13``` 14 15## 子组件 16 17可以包含子组件。 18从API Version 10开始，推荐使用[NavPathStack](ts-basic-components-navigation.md#navpathstack10)进行页面路由。 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**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 43 44**装饰器类型：** @Component 45 46**系统能力：** SystemCapability.ArkUI.ArkUI.Full 47 48**参数**： 49 50| 名称 | 类型 | 必填 | 装饰器类型|说明 | 51| --------------- | ------ | ---- | ----|----------| 52| navPathStack | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | 否 | @State | 路由栈信息。 | 53| navigationContent | Callback\<void\> | 否 | @BuilderParam | Navigation容器内容。 | 54| title | [ResourceStr](ts-types.md#resourcestr) | 否 |@Prop | 设置页面标题。默认值为空字符串。当titleOptions的titleBarType字段设置为[TitleBarType](#titlebartype18).ROUND_ICON或者[TitleBarType](#titlebartype18).SQUARED_ICON，且设置了titleIcon时，title标题内容将不会显示。 | 55| titleOptions | [TitleOptions](#titleoptions) | 否 | @Prop | 标题栏选项。当titleBarType字段设置为[TitleBarType](#titlebartype18).ROUND_ICON或者[TitleBarType](#titlebartype18).SQUARED_ICON，且设置了titleIcon时，title标题内容将不会显示。 | 56| gradientBackground<sup>18+</sup> | [GradientBackground](#gradientbackground18) | 否 | @Prop | 背景色选项。| 57| hideTitleBar | boolean | 否 | @Prop | 设置是否隐藏标题栏。默认为false。<br>false表示显示标题栏，true表示隐藏标题栏。| 58| navBarWidth | [Length](ts-types.md#length)| 否 | @Prop | 设置导航栏宽度。默认值为240vp。<br>仅在Navigation组件分栏时生效。| 59| mode| [NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明) | 否 | @Prop |设置导航栏的显示模式。<br>支持Stack、Split与Auto模式。| 60| navDestinationBuilder | [NavDestinationBuilder](#navdestinationbuilder) | 否 | @BuilderParam | 创建[NavDestination](ts-basic-components-navdestination.md)组件所需要的Builder数据。 | 61| navBarWidthRange | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | 否 | @Prop |设置导航栏最小和最大宽度（双栏模式下生效）。默认值：最小默认值为240vp，最大默认值为组件宽度的40%，且不大于432vp，如果只设置一个值，则未设置的值按照默认值计算。单位：vp。 | 62| minContentWidth | [Dimension](ts-types.md#dimension10) | 否 | @Prop | 设置导航栏内容区最小宽度（双栏模式下生效）。| 63| sideBarOptions<sup>18+</sup> | [SideBarOptions](#sidebaroptions18) | 否 | @Prop | 侧边栏的功能选项。| 64| sideBarContent<sup>18+</sup> | Callback\<void\> | 否 | @BuilderParam | 侧边栏的内容。| 65| menus<sup>18+</sup> | [CustomBuilder](ts-types.md#custombuilder8) \| Array\<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)\> | 否 | @BuilderParam | 宽屏场景下用户自定义插入的布局样式。默认为空，不显示任何样式。屏幕宽度低于600vp为非宽屏场景，大于等于600vp为宽屏场景。 | 66| stateChangeCallback | Callback\<boolean\> | 否 | - | 导航栏显示状态切换时触发该回调。| 67| modeChangeCallback | Callback\<[NavigationMode](ts-basic-components-navigation.md#navigationmode9枚举说明)\> | 否 | - | 当Navigation首次显示或者单双栏状态发生变化时触发该回调。| 68 69## TitleOptions 70标题栏选项。 71**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 72 73**系统能力：** SystemCapability.ArkUI.ArkUI.Full 74 75| 名称 | 类型 | 必填 | 说明 | 76| --------------- | ------ | ---- | ---------- | 77| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 标题栏背景颜色。 | 78| isBlurEnabled | boolean | 否 | 标题栏是否模糊，默认为true。 | 79| barStyle | [BarStyle](ts-basic-components-navigation.md#barstyle12枚举说明) | 否 | 标题栏样式属性设置。 | 80| titleBarType<sup>18+</sup> | [TitleBarType](#titlebartype18) | 否 | 设置标题栏类型。默认值为TitleBarType.ROUND_ICON。 | 81| titleIcon<sup>18+</sup> | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 设置标题栏的图标。默认值为$r('sys.color.ohos_id_color_titlebar_icon')。 | 82 83## GradientBackground<sup>18+</sup> 84供开发者设置品牌渐变色。 85 86**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 类型 | 必填 | 说明 | 91| --------------- | ------ | ---- | ---------- | 92| primaryColor | [ResourceColor](ts-types.md#resourcecolor) | 是 | 单色渐变色彩值和双色渐变第一色彩值。无默认值。| 93| secondaryColor |[ResourceColor](ts-types.md#resourcecolor) | 否 |双色渐变色第二色彩值。无默认值。| 94| backgroundTheme |[BackgroundTheme<sup>18+</sup>](#backgroundtheme18) | 否 |导航栏背景底色。默认值为DEFAULT。| 95| mixMode | [MixMode<sup>18+</sup>](#mixmode18) | 否 |同时设置primaryColor和secondaryColor时此参数生效。代表双色渐变下两种颜色的融合方式。默认值为TOWARDS。| 96| alpha | [GradientAlpha<sup>18+</sup>](#gradientalpha18) | 否 |设置渐变色显示区域的透明度。默认值为OPACITY_20。| 97 98## NavDestinationBuilder 99 100type NavDestinationBuilder = (name: string, param?: Object) => void 101 102**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106| 参数名 | 类型 | 必填 | 描述 | 107| --------------- | ------ | ---- | ---------- | 108| name | string | 是 | [NavDestination](ts-basic-components-navdestination.md)页面名称。 | 109| param | Object | 是 | [NavDestination](ts-basic-components-navdestination.md)页面详细参数。 | 110 111## MixMode<sup>18+</sup> 112背景色颜色混合模式的可选项。 113 114**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 115 116**系统能力：** SystemCapability.ArkUI.ArkUI.Full 117 118| 名称 | 值 | 说明 | 119| --------------- | ------ |-----| 120| AVERAGE | 1 | 两种颜色各占一半。 | 121| CROSS | 2 | 一种颜色从另一种颜色中穿过。 | 122| TOWARDS | 3 | 一种颜色渐变为另一种颜色。 | 123 124## TitleBarType<sup>18+</sup> 125标题栏类型的可选项，默认值为ROUND_ICON。 126 127**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131| 名称 | 值 | 说明 | 132| --------------- | ------ |-----| 133| SQUARED_ICON | 1 | 方形图标样式。 | 134| ROUND_ICON | 2 | 圆形图标样式。 | 135| DRAWER | 3 | 抽屉样式。 | 136 137## GradientAlpha<sup>18+</sup> 138导航栏背景底色的可选项。 139 140**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144| 名称 | 值 | 说明 | 145| --------------- | ------ |-----| 146| OPACITY_20| 1 | 不透明度为0.2。 | 147| OPACITY_60| 2 | 不透明度为0.6。| 148| OPACITY_80| 3 | 不透明度为0.8。 | 149| OPACITY_100| 4 | 不透明度为1.0。 | 150 151## BackgroundTheme<sup>18+</sup> 152导航栏背景色底色的可选项。 153 154**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.ArkUI.ArkUI.Full 157 158| 名称 | 值 | 说明 | 159| --------------- | ------ |-----| 160| DARK | 1 | 背景底色为黑色。 | 161| LIGHT | 2 | 背景底色为白色。| 162| DEFAULT | 3 | 背景底色为灰白色。颜色值`#F1F3F5` 。| 163 164## SideBarOptions<sup>18+</sup> 165侧边栏的功能选项。 166 167**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171| 名称 | 类型 | 必填 | 说明 | 172| --------------- | ------ | ---- | ---------- | 173| sideBarBackground | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置侧边栏的背景颜色。默认为$r('sys.color.ohos_id_color_sub_background')。 | 174| onChange | Callback\<boolean\> | 否 | 侧边栏显示隐藏回调。 | 175| sideBarIcon | [Resource](ts-types.md#resource) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 侧边栏里的返回图标。默认值为$r('sys.symbol.open_sidebar')。 | 176 177## 示例 178 179### 示例1（AtomicServiceNavigation页面布局与渐变色背景） 180AtomicServiceNavigation的基础样式，并展示渐变色背景。 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 = '主题'; 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'), '功能1'), 224 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 225 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能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 = '功能1'; 232 } else if (index == 1) { 233 this.message = '功能2'; 234 } else { 235 this.message = '功能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: '#FF0000', 263 secondaryColor: '#00FF00', 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### 示例2（抽屉模式，宽屏场景下插入自定义布局） 316 317设备宽屏场景（宽度大于600vp）下设置抽屉模式，用户在标题栏插入自定义布局。 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'), '功能1'), 363 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 364 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能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 = '功能1'; 371 } else if (index == 1) { 372 this.message = '功能2'; 373 } else { 374 this.message = '功能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 menus 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### 示例3（边栏使用场景） 458 459设置边栏：背景色与内容样式。 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'), '功能1'), 505 new TabBarOptions($r('sys.media.ohos_ic_public_location'), '功能2', Color.Green, Color.Red), 506 new TabBarOptions($r('sys.media.ohos_ic_public_more'), '功能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 = '功能1'; 513 } else if (index == 1) { 514 this.message = '功能2'; 515 } else { 516 this.message = '功能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
