# ohos_multi_navigation **Repository Path**: CWasBo/ohos_multi_navigation ## Basic Information - **Project Name**: ohos_multi_navigation - **Description**: 提供高级分栏组件,给三方应用快速接入大尺寸设备的方案 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: https://gitee.com/openharmony-sig/ohos_multi_navigation - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 10 - **Created**: 2024-04-26 - **Last Updated**: 2024-04-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ohos_multi_navigation ## 介绍 提供高级分栏组件,给三方应用快速接入大尺寸设备的方案 ## 下载安装 ```shell ohpm install @ohos/multinavigation ``` OpenHarmony ohpm 环境配置等更多内容,请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) ## 使用说明 1.提供了应用分栏组件MultiNavigation及MultiNavPathStack路由栈作为分栏时存储页面使用。 2.以MultiNavigation组件及配合MultiNavPathStack路由栈来实现应用分栏操作举例: **注:** PageHome:主页 PageDetail:详情页 PageFull:不参与分栏的页面,默认全屏展示 ```typescript 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 ```typescript 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: ```typescript 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: ```typescript 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](#MultiNavPathStack)配合NavDestination组件进行页面路由。 ### 接口 MultiNavigation(navDestination: navDestination, multiStack: MultiNavPathStack) 绑定路由栈到MultiNavigation组件。 **参数:** | 参数名 | 参数类型 | 必填 | 参数描述 | |:---------:|:---------------------------------------:|-----| ------ | | pathInfos | [MultiNavPathStack](#MultiNavPathStack) | 是 | 路由栈信息。 | ### 属性 不支持任何属性 ### 事件 #### onNavigationModeChange onNavigationModeChange(callback: (mode: NavigationMode) => void) 当Navigation首次显示或者单双栏状态发生变化时触发该回调。 **参数:** | 名称 | 类型 | 必填 | 描述 | | ---- | :----------------------------------------------------------: | :--: | :----------------------------------------------------------- | | mode | [NavigationMode](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navigationmode9枚举说明) | 是 | NavigationMode.Split: 当前Navigation显示为双栏; NavigationMode.Stack: 当前Navigation显示为单栏。 | ### MultiNavPathStack MultiNavigation路由栈。 #### pushPath pushPath(info: NavPathInfo, animated?: boolean, policy?: SplitPolicy): void 将info指定的NavDestination页面信息入栈。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:---------:|:------------------------------:|----|----------------------| | info | [NavPathInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathinfo10) | 是 | NavDestination页面的信息。 | | animated | boolean | 否 | 是否支持转场动画,默认值:true。 | | policy | [SplitPolicy](#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](#SplitPolicy枚举类型) | 否 | 当前入栈页面的策略,默认值:DETAIL_PAGE | #### pushPathByName pushPathByName(name: string, param: Object, onPop: import('../api/@ohos.base').Callback\, animated?: boolean, policy?: SplitPolicy): void 将name指定的NavDestination页面信息入栈,传递的数据为param,添加onPop回调接收入栈页面出栈时的返回结果,并进行处理。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:---------:|:-------------------------------------------------------------:|:------:|------| | name | string | 是 | NavDestination页面名称。 | | param | Object | 是 | NavDestination页面详细参数。 | | onPop | import('../api/@ohos.base').Callback\<[PopInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#popinfo11)> | 是 | Callback回调,用于页面出栈时触发该回调处理返回结果。 | | animated | boolean | 否 | 是否支持转场动画,默认值:true。 | | policy | [SplitPolicy](#SplitPolicy枚举类型) | 否 | 当前入栈页面的策略,默认值:DETAIL_PAGE | #### pushDestination pushDestination(info: NavPathInfo, animated?: boolean, policy?: SplitPolicy): Promise<void> 将info指定的NavDestination页面信息入栈,使用Promise异步回调返回接口调用结果。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:---------:|:-------------------------------:|:------:| -------------------- | | info | [NavPathInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathinfo10) | 是 | NavDestination页面的信息。 | | animated | boolean | 否 | 是否支持转场动画,默认值:true。 | | policy | [SplitPolicy](#SplitPolicy枚举类型) | 否 | 当前入栈页面的策略,默认值:DETAIL_PAGE | **返回值:** | 类型 | 说明 | | ------------------- | --------- | | Promise<void> | 异常返回结果。 | **错误码:** 以下错误码的详细介绍请参见[ohos.router(页面路由)](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/errorcode-router.md)错误码。 | 错误码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](#SplitPolicy枚举类型) | 否 | 当前入栈页面的策略,默认值:DETAIL_PAGE | **返回值:** | 类型 | 说明 | | ------------------- | --------- | | Promise<void> | 异常返回结果。 | **错误码:** 以下错误码的详细介绍请参见[ohos.router(页面路由)](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | --------- | ------- | | 401 | 参数错误。 | | 100001 | 系统内部错误。| | 100005 | 创建NavDestination组件的builder函数未注册。 | | 100006 | 目标页面中不存在NavDestination组件。| #### pushDestinationByName pushDestinationByName(name: string, param: Object, onPop: import('../api/@ohos.base').Callback\, animated?: boolean, policy?: SplitPolicy): Promise<void> 将name指定的NavDestination页面信息入栈,传递的数据为param,并且添加用于页面出栈时处理返回结果的OnPop回调,使用Promise异步回调返回接口调用结果。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:---------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---:| --------------------- | | name | string | 是 | NavDestination页面名称。 | | param | Object | 是 | NavDestination页面详细参数。 | | onPop | import('../api/@ohos.base').Callback\<[PopInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#popinfo11)> | 是 | Callback回调,用于页面出栈时处理返回结果。 | | animated | boolean | 否 | 是否支持转场动画,默认值:true。 | | policy | [SplitPolicy](#SplitPolicy枚举类型) | 否 | 当前入栈页面的策略,默认值:DETAIL_PAGE | **返回值:** | 类型 | 说明 | | ------------------- | --------- | | Promise<void> | 异常返回结果。 | **错误码:** 以下错误码的详细介绍请参见[ohos.router(页面路由)](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | --------- | ------- | | 401 | 参数错误。 | | 100001 | 系统内部错误。| | 100005 | 创建NavDestination组件的builder函数未注册。 | | 100006 | 目标页面中不存在NavDestination组件。| #### replacePath replacePath(info: NavPathInfo, animated?: boolean): void 将当前页面栈栈顶退出,将info指定的NavDestination页面信息入栈,新页面的分栏策略继承原栈顶页面的策略。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:--------:|:-------------------------------:| ---- | -------------------- | | info | [NavPathInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathinfo10) | 是 | 新栈顶页面参数信息 | | 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 将页面栈内索引值在indexes中的NavDestination页面删除。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:--------:|:---------------:|:------:| --------------------- | | indexes | Array | 是 | 待删除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](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathinfo10) | 返回栈顶NavDestination页面的信息。 | | undefined | 当路由栈为空时返回undefined。 | #### pop pop(result: Object, animated?: boolean): NavPathInfo | undefined 弹出路由栈栈顶元素,并触发onPop回调传入页面处理结果。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:---------:|:-------------------------------:|:------:| -------------------- | | result | Object | 是 | 页面自定义处理结果。 | | animated | boolean | 否 | 是否支持转场动画,默认值:true。 | **返回值:** | 类型 | 说明 | | ----------- | ------------------------ | | [NavPathInfo](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathinfo10) | 返回栈顶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 获取栈中所有NavDestination页面的名称。 **返回值:** | 类型 | 说明 | |:----------------:| -------------------------- | | Array | 返回栈中所有NavDestination页面的名称。 | #### getParamByIndex getParamByIndex(index: number): Object 获取index指定的NavDestination页面的参数信息。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:-------:|:--------:|:------:| ---------------------- | | index | number | 是 | NavDestination页面的位置索引。 | **返回值:** | 类型 | 说明 | | --------- | -------------------------- | | Object | 返回对应NavDestination页面的参数信息。 | #### getParamByName getParamByName(name: string): Array 获取全部名为name的NavDestination页面的参数信息。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:------:|:--------:|:------:| ------------------- | | name | string | 是 | NavDestination页面名称。 | **返回值:** | 类型 | 说明 | | --------------- | --------------------------------- | | Array | 返回全部名为name的NavDestination页面的参数信息。 | #### getIndexByName getIndexByName(name: string): Array 获取全部名为name的NavDestination页面的位置索引。 **参数:** | 名称 | 类型 | 必填 | 描述 | |:------:|:--------:|:------:| ------------------- | | name | string | 是 | NavDestination页面名称。 | **返回值:** | 类型 | 说明 | | -------------- | --------------------------------- | | Array | 返回全部名为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不支持此接口,会抛出异常,请勿调用 ### SplitPolicy枚举类型 | 名称 | 描述 | |:------------:|:-------:| | HOME_PAGE | 左分栏页面类型。 | | DETAIL_PAGE | 右分栏页面类型。| | FULL_PAGE | 全屏页面类型。 | ## 约束与限制 在下述版本验证通过: - DevEco Studio: 4.1.3.500, SDK: API12(5.0.0.20-Canary2) ## 目录结构 ## 贡献代码 使用过程中发现任何问题都可以提[Issue](https://gitee.com/feather_ys/ohos_multi_navigation/issues)给我们,当然,我们也非常欢迎你给我们发[PR](https://gitee.com/feather_ys/ohos_multi_navigation/pulls)。 ## 开源协议 本项目基于 [Apache License 2.0](https://gitee.com/openharmony-sig/ohos_multi_navigation/blob/master/LICENSE) ,请自由地享受和参与开源。