ohos_multi_navigation

介绍

提供高级分栏组件，给三方应用快速接入大尺寸设备的方案

下载安装

ohpm install @ohos/multinavigation

OpenHarmony ohpm 环境配置等更多内容，请参考如何安装 OpenHarmony ohpm 包

使用说明

1.提供了应用分栏组件MultiNavigation及MultiNavPathStack路由栈作为分栏时存储页面使用。

2.以MultiNavigation组件及配合MultiNavPathStack路由栈来实现应用分栏操作举例：

注：

PageHome：主页

PageDetail：详情页

PageFull：不参与分栏的页面，默认全屏展示

import { MultiNavigation, MultiNavPathStack, SplitPolicy } from '@ohos/multinavigation';
import { PageDetail1 } from './PageDetail1';
import { PageFull1 } from './PageFull1';
import { PageHome1 } from './PageHome1';

@Entry
@Component
struct Index {
  @Provide('pageStack')pageStack: MultiNavPathStack = new MultiNavPathStack();

  @Builder
  PageMap(name: string, param?: object) {
    if (name === 'PageHome1') {
      PageHome1()
    } else if (name === 'PageDetail1') {
      PageDetail1();
    } else if (name == 'PageFull1') {
      PageFull1();
    }
  }

  aboutToAppear(): void {
    this.pageStack.pushPath({ name : 'PageHome1', param: "paramTest"}, false, SplitPolicy.HOME_PAGE);
  }

  build() {
    Column() {
      Row() {
        MultiNavigation({navDestination: this.PageMap, multiStack: this.pageStack})
      }
      .width('100%')
    }
  }
}

PageHome1

import { hilog } from '@kit.PerformanceAnalysisKit';

@Component
export struct PageHome1 {
  @State message: string = 'PageHome1';
  @Consume('pageStack') pageStack: MultiNavPathStack;

  build() {
    if (this.log()) {
      NavDestination() {
        Column() {
          Button('OpenDetail', { stateEffect: true, type: ButtonType.Capsule})
            .width('50%')
            .height(40)
            .margin(20)
            .onClick(() => {
              if (this.pageStack !== undefined && this.pageStack !== null) {
                this.pageStack.pushPath({ name: 'PageDetail1' });
              }
            })
          Button('pop', { stateEffect: true, type: ButtonType.Capsule})
            .width('50%')
            .height(40)
            .margin(20)
            .onClick(() => {
              if (this.pageStack !== undefined && this.pageStack !== null) {
                this.pageStack.pop();
              }
            })
        }
      }
      .hideTitleBar(true)
    }
  }

  log(): boolean {
    hilog.info(0x0000, 'demotest', 'PageHome1 build called');
    return true;
  }
}

PageDetail1：

import { MultiNavPathStack, SplitPolicy } from '@ohos/multinavigation';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Component
export struct PageDetail1 {
  @State message: string = 'PageDetail1';
  @Consume('pageStack') pageStack: MultiNavPathStack;

  build() {
    if (this.log()) {
      NavDestination() {
        Column() {
          Scroll(){
            Column(){
              Button('pop', { stateEffect: true, type: ButtonType.Capsule})
                .width('50%')
                .height(40)
                .margin(20)
                .onClick(() => {
                  if (this.pageStack !== undefined && this.pageStack !== null) {
                    this.pageStack.pop();
                  }
                })
              Button('OpenFull', { stateEffect: true, type: ButtonType.Capsule})
                .width('50%')
                .height(40)
                .margin(20)
                .onClick(() => {
                  if (this.pageStack !== undefined && this.pageStack !== null) {
                    this.pageStack.pushPath({ name: 'PageFull1' }, true, SplitPolicy.FULL_PAGE);
                  }
                })
            }
          }
          .height('100%')
        }
      }
      .hideTitleBar(true)
    }
  }

  log(): boolean {
    hilog.info(0x0000, 'demotest', 'PageDetail1 build called');
    return true;
  }
}

PageFull1：

import { MultiNavPathStack, SplitPolicy } from '@ohos/multinavigation';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Component
export struct PageFull1 {
  @State message: string = 'PageFull1';
  @Consume('pageStack') pageStack: MultiNavPathStack;

  build() {
    if (this.log()) {
      NavDestination() {
        Column() {
          Button('OpenHome', { stateEffect: true, type: ButtonType.Capsule})
            .width('50%')
            .height(40)
            .margin(20)
            .onClick(() => {
              if (this.pageStack !== undefined && this.pageStack !== null) {
                this.pageStack.pushPath({ name: 'PageHome1', param: 'open from full' }, true, SplitPolicy.HOME_PAGE);
              }
            })
          Button('pop', { stateEffect: true, type: ButtonType.Capsule})
                .width('50%')
                .height(40)
                .margin(20)
                .onClick(() => {
               if (this.pageStack !== undefined && this.pageStack !== null) {
                this.pageStack.pop();
              }
            })
        }
      }
      .hideTitleBar(true)
    }
  }

  log(): boolean {
    hilog.info(0x0000, 'demotest', 'PageFull1 build called');
    return true;
  }
}

组件说明

MultiNavigation

子组件

不可以包含子组件

推荐使用MultiNavPathStack配合NavDestination组件进行页面路由。

接口

MultiNavigation(navDestination: navDestination, multiStack: MultiNavPathStack)

绑定路由栈到MultiNavigation组件。

参数：

属性

不支持任何属性

事件

onNavigationModeChange

onNavigationModeChange(callback: (mode: NavigationMode) => void)

当Navigation首次显示或者单双栏状态发生变化时触发该回调。

参数：

onHomeShowInTop

onHomeShowInTop(callback: (name: string) => void)

当通过pop等接口使得主页在栈顶时会触发该回调。

参数

MultiNavPathStack

MultiNavigation路由栈。

pushPath

pushPath(info: NavPathInfo, animated?: boolean, policy?: SplitPolicy): void

将info指定的NavDestination页面信息入栈。

参数：

pushPathByName

pushPathByName(name: string, param: Object, animated?: boolean, policy?: SplitPolicy): void

将name指定的NavDestination页面信息入栈，传递的数据为param。

参数：

pushPathByName

pushPathByName(name: string, param: Object, onPop: import('../api/@ohos.base').Callback<PopInfo>, animated?: boolean, policy?: SplitPolicy): void

将name指定的NavDestination页面信息入栈，传递的数据为param，添加onPop回调接收入栈页面出栈时的返回结果，并进行处理。

参数：

pushDestination

pushDestination(info: NavPathInfo, animated?: boolean, policy?: SplitPolicy): Promise<void>

将info指定的NavDestination页面信息入栈，使用Promise异步回调返回接口调用结果。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

pushDestinationByName

pushDestinationByName(name: string, param: Object, animated?: boolean, policy?: SplitPolicy): Promise<void>

将name指定的NavDestination页面信息入栈，传递的数据为param，使用Promise异步回调返回接口调用结果。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

pushDestinationByName

pushDestinationByName(name: string, param: Object, onPop: import('../api/@ohos.base').Callback<PopInfo>, animated?: boolean, policy?: SplitPolicy): Promise<void>

将name指定的NavDestination页面信息入栈，传递的数据为param，并且添加用于页面出栈时处理返回结果的OnPop回调，使用Promise异步回调返回接口调用结果。

参数：

返回值：

错误码：

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

replacePath

replacePath(info: NavPathInfo, animated?: boolean): void

将当前页面栈栈顶退出，将info指定的NavDestination页面信息入栈，新页面的分栏策略继承原栈顶页面的策略。

参数：

replacePathByName

replacePathByName(name: string, param: Object, animated?: boolean): void

将当前页面栈栈顶退出，将name指定的页面入栈，新页面的分栏策略继承原栈顶页面的策略。

参数：

removeByIndexes

removeByIndexes(indexes: Array<number>): number

将页面栈内索引值在indexes中的NavDestination页面删除。

参数：

返回值：

removeByName

removeByName(name: string): number

将页面栈内指定name的NavDestination页面删除。

参数：

返回值：

pop

pop(animated?: boolean): NavPathInfo | undefined

弹出路由栈栈顶元素。

说明

当调用setKeepBottomPage接口并设置为true时，会保留栈底页面。

参数：

返回值：

pop

pop(result: Object, animated?: boolean): NavPathInfo | undefined

弹出路由栈栈顶元素，并触发onPop回调传入页面处理结果。

说明

当调用setKeepBottomPage接口并设置为true时，会保留栈底页面。

参数：

返回值：

popToName

popToName(name: string, animated?: boolean): number

回退路由栈到由栈底开始第一个名为name的NavDestination页面。

参数：

返回值：

popToName

popToName(name: string, result: Object, animated?: boolean): number

回退路由栈到由栈底开始第一个名为name的NavDestination页面，并触发onPop回调传入页面处理结果。

参数：

返回值：

popToIndex

popToIndex(index: number, animated?: boolean): void

回退路由栈到index指定的NavDestination页面。

参数：

popToIndex

popToIndex(index: number, result: Object, animated?: boolean): void

回退路由栈到index指定的NavDestination页面，并触发onPop回调传入页面处理结果。

参数：

moveToTop

moveToTop(name: string, animated?: boolean): number

将由栈底开始第一个名为name的NavDestination页面移到栈顶。

说明：

高级分栏组件存在主页和详情页的关联关系，以及多主页多重栈的情况，会有以下场景和处理策略：

1)当找到的是最上层主页或者全屏页，此时不做任何处理；

2)当找到的是最上层主页对应的详情页，则会将对应的的详情页移到栈顶；

3)当找到的是非最上层的主页，则会将主页和对应所有详情页移到栈顶，详情页相对栈关系不变；

4)当找到的是非最上层的详情页，则会将主页和对应所有详情页移到栈顶，且将目标详情页移动到对应所有详情页的栈顶；

5)当找到的是非最上层的全屏页，则会将全屏页移动到栈顶。

返回值：

moveIndexToTop

moveIndexToTop(index: number, animated?: boolean): void

将指定index的NavDestination页面移到栈顶。

说明：

高级分栏组件存在主页和详情页的关联关系，以及多主页多重栈的情况，会有以下场景和处理策略：

1)当找到的是最上层主页或者全屏页，此时不做任何处理；

2)当找到的是最上层主页对应的详情页，则会将对应的的详情页移到栈顶；

3)当找到的是非最上层的主页，则会将主页和对应所有详情页移到栈顶，详情页相对栈关系不变；

4)当找到的是非最上层的详情页，则会将主页和对应所有详情页移到栈顶，且将目标详情页移动到对应所有详情页的栈顶；

5)当找到的是非最上层的全屏页，则会将全屏页移动到栈顶。

clear

clear(animated?: boolean): void

清除栈中所有页面。

说明

当调用setKeepBottomPage接口并设置为true时，会保留栈底页面。

参数：

getAllPathName

getAllPathName(): Array<string>

获取栈中所有NavDestination页面的名称。

返回值：

getParamByIndex

getParamByIndex(index: number): Object

获取index指定的NavDestination页面的参数信息。

参数：

返回值：

getParamByName

getParamByName(name: string): Array<Object>

获取全部名为name的NavDestination页面的参数信息。

参数：

返回值：

getIndexByName

getIndexByName(name: string): Array<number>

获取全部名为name的NavDestination页面的位置索引。

参数：

返回值：

size

size(): number

获取栈大小。

返回值：

disableAnimation

disableAnimation(value: boolean): void

关闭（true）或打开（false）当前MultiNavigation中所有转场动画。

参数：

getParent

getParent(): NavPathStack | null

说明：

MultiNavigation存在多重栈嵌套，故MultiNavigationStack不支持此接口，会抛出异常，请勿调用

setInterception

setInterception(interception: NavigationInterception): void

说明：

MultiNavigation存在多重栈嵌套，故MultiNavigationStack不支持此接口，会抛出异常，请勿调用

switchFullScreen

switchFullScreen(isFullScreen?: boolean): boolean

将当前最顶栈的分栏页的详情页面切换为全屏（true）或分栏（false）

参数：

返回值：

setHomeWidthRange

setHomeWidthRange(minPercent: number, maxPercent: number): void

设置主页宽度可拖动范围。应用不设置的情况下宽度为50%，且不可拖动。

参数：

setKeepBottomPage

setKeepBottomPage(keepBottom: boolean): void

设置在调用pop和clear接口时是否保留栈底页面，

说明

高级分栏组件将主页也当作了NavDestination页面入栈，所以调用pop或clear接口时会将栈底页面也出栈。 应用调用此接口并设置为TRUE时，高级分栏组件会在pop和clear时保留栈底页面。

参数：

SplitPolicy枚举类型

约束与限制

在下述版本验证通过：

• DevEco Studio: 4.1.3.500, SDK: API12(5.0.0.20-Canary2)

注意：

本组件从API12开始支持。

由于MultiNavPathStack继承自原生NavPathStack，调用本文档明确说明的不支持接口或不在本文档支持接口列表中的接口，可能会发生无法预期的问题。

MultiNavPathStack目前仅支持使用方自行创建，不支持通过回调拿到，不要使用NavDestination的onReady等类似事件或接口来拿到NavPathStack进行栈操作，可能会发生无法预期的问题。

目录结构

/library/src/
- main/ets/components
  - mainpage
    - MultiNavigation.ets        # 高级分栏组件
    - SubNavigation.ets          # 分栏子组件
       
/entry/src/
- main/ets     
  - entryability                             # 测试Ability列表
    - EntryAbility.ts                        # 测试入口Ability
  - pages                                    # 测试page页面列表
    - index.ets                              # 程序入口页面
    - PageDetail1.ets                        # 测试详情页1
    - PageDetail2.ets                        # 测试详情页2
    - PageFull1.ets                          # 测试全屏页
    - PageHome1.ets                          # 测试主页1

贡献代码

使用过程中发现任何问题都可以提Issue给我们，当然，我们也非常欢迎你给我们发PR。

开源协议

本项目基于 Apache License 2.0 ，请自由地享受和参与开源。