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组件。

参数：

参数名	参数类型	必填	参数描述
pathInfos	MultiNavPathStack	是	路由栈信息。

属性

不支持任何属性

事件

onNavigationModeChange

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

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

参数：

名称	类型	必填	描述
mode	NavigationMode	是	NavigationMode.Split: 当前Navigation显示为双栏; NavigationMode.Stack: 当前Navigation显示为单栏。

MultiNavPathStack

MultiNavigation路由栈。

pushPath

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

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

pushPathByName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

pushPathByName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
onPop	import('../api/@ohos.base').Callback<PopInfo>	是	Callback回调，用于页面出栈时触发该回调处理返回结果。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

pushDestination

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

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

返回值：

类型	说明
Promise<void>	异常返回结果。

错误码：

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

错误码ID	错误信息
401	参数错误。
100001	系统内部错误。
100005	创建NavDestination组件的builder函数未注册。
100006	目标页面中不存在NavDestination组件。

pushDestinationByName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

返回值：

类型	说明
Promise<void>	异常返回结果。

错误码：

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

错误码ID	错误信息
401	参数错误。
100001	系统内部错误。
100005	创建NavDestination组件的builder函数未注册。
100006	目标页面中不存在NavDestination组件。

pushDestinationByName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
onPop	import('../api/@ohos.base').Callback<PopInfo>	是	Callback回调，用于页面出栈时处理返回结果。
animated	boolean	否	是否支持转场动画，默认值：true。
policy	SplitPolicy	否	当前入栈页面的策略，默认值：DETAIL_PAGE

返回值：

类型	说明
Promise<void>	异常返回结果。

错误码：

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

错误码ID	错误信息
401	参数错误。
100001	系统内部错误。
100005	创建NavDestination组件的builder函数未注册。
100006	目标页面中不存在NavDestination组件。

replacePath

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

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	新栈顶页面参数信息
animated	boolean	否	是否支持转场动画，默认值：true。

replacePathByName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
animated	boolean	否	是否支持转场动画，默认值：true。

removeByIndexes

removeByIndexes(indexes: Array<number>): number

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

参数：

名称	类型	必填	描述
indexes	Array<number>	是	待删除NavDestination页面的索引值数组。

返回值：

类型	说明
number	返回删除的NavDestination页面数量。

removeByName

removeByName(name: string): number

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

参数：

名称	类型	必填	描述
name	string	是	删除的NavDestination页面的名字。

返回值：

类型	说明
number	返回删除的NavDestination页面数量。

pop

pop(animated?: boolean): NavPathInfo | undefined

弹出路由栈栈顶元素。

参数：

名称	类型	必填	描述
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
NavPathInfo	返回栈顶NavDestination页面的信息。
undefined	当路由栈为空时返回undefined。

pop

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

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

参数：

名称	类型	必填	描述
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
NavPathInfo	返回栈顶NavDestination页面的信息。
undefined	当路由栈为空时返回undefined。

popToName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
number	如果栈中存在名为name的NavDestination页面，则返回由栈底开始第一个名为name的NavDestination页面的索引，否则返回-1。

popToName

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
number	如果栈中存在名为name的NavDestination页面，则返回由栈底开始第一个名为name的NavDestination页面的索引，否则返回-1。

popToIndex

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

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。
animated	boolean	否	是否支持转场动画，默认值：true。

popToIndex

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

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

moveToTop

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

说明：

MultiNavigation不支持跨栈迁移，故MultiNavigationStack不支持此接口，会抛出异常，请勿调用

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

moveIndexToTop

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

说明：

MultiNavigation不支持跨栈迁移，故MultiNavigationStack不支持此接口，会抛出异常，请勿调用

clear

clear(animated?: boolean): void

清除栈中所有页面。

参数：

名称	类型	必填	描述
animated	boolean	否	是否支持转场动画，默认值：true。

getAllPathName

getAllPathName(): Array<string>

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

返回值：

类型	说明
Array<string>	返回栈中所有NavDestination页面的名称。

getParamByIndex

getParamByIndex(index: number): Object

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。

返回值：

类型	说明
Object	返回对应NavDestination页面的参数信息。

getParamByName

getParamByName(name: string): Array<Object>

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。

返回值：

类型	说明
Array<Object>	返回全部名为name的NavDestination页面的参数信息。

getIndexByName

getIndexByName(name: string): Array<number>

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。

返回值：

类型	说明
Array<number>	返回全部名为name的NavDestination页面的位置索引。

size

size(): number

获取栈大小。

返回值：

类型	说明
number	返回栈大小。

disableAnimation

disableAnimation(value: boolean): void

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

参数：

名称	类型	必填	描述
value	boolean	否	是否关闭转场动画，默认值：false。

getParent

~~getParent(): NavPathStack | null~~

说明：

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

setInterception

~~setInterception(interception: NavigationInterception): void~~

说明：

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

switchFullScreen

switchFullScreen(isFullScreen?: boolean): boolean

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

参数：

名称	类型	必填	描述
isFullScreen	boolean	是	是否切换为全屏。

返回值：

类型	说明
boolean	切换成功或失败。

setHomeWidthRange

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

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

参数：

名称	类型	必填	描述
minPercent	number	是	最小主页宽度百分比。
maxPercent	number	是	最大主页宽度百分比。

SplitPolicy枚举类型

名称	描述
HOME_PAGE	主页页面类型。
DETAIL_PAGE	详情页页面类型。
FULL_PAGE	全屏页页面类型。

约束与限制

在下述版本验证通过：

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 ，请自由地享受和参与开源。

OpenHarmony-SIG / ohos_multi_navigation .gitee-modal { width: 500px !important; }

ohos_multi_navigation

介绍

下载安装

使用说明

组件说明

MultiNavigation

子组件

接口

属性

事件

onNavigationModeChange

MultiNavPathStack

pushPath

pushPathByName

pushPathByName

pushDestination

pushDestinationByName

pushDestinationByName

replacePath

replacePathByName

removeByIndexes

removeByName

pop

pop

popToName

popToName

popToIndex

popToIndex

moveToTop

moveIndexToTop

clear

getAllPathName

getParamByIndex

getParamByName

getIndexByName

size

disableAnimation

getParent

setInterception

switchFullScreen

setHomeWidthRange

SplitPolicy枚举类型

约束与限制

目录结构

贡献代码

开源协议

简介

发行版

贡献者

近期动态

搜索帮助

OpenHarmony-SIG / ohos_multi_navigation