!7008 路由文档修改

Merge pull request !7008 from luoying_ace/master

!7008 路由文档修改
Merge pull request !7008 from luoying_ace/master
e5baf008 · openharmony_ci · Gitee · 0203a1be · 36e62214 · e5baf008
隐藏空白更改
内联并排

Showing with 229 addition and 280 deletion

zh-cn/application-dev/reference/apis/js-apis-router.md zh-cn/application-dev/reference/apis/js-apis-router.md +229 -280

未找到文件。
--- a/zh-cn/application-dev/reference/apis/js-apis-router.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-router.md
@@ -2,9 +2,10 @@

 本模块提供通过不同的url访问不同的页面，包括跳转到应用内的指定页面、用应用内的某个页面替换当前页面、返回上一页面或指定的页面等。

-> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明**
+> **说明**
 >
 > - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 
 > - 页面路由需要在页面渲染完成之后才能调用，在onInit和onReady生命周期中页面还处于渲染阶段，禁止调用页面路由方法。

 ## 导入模块
@@ -13,59 +14,60 @@
 import router from '@ohos.router'
 ```

-## 权限列表
-
-无
-
 ## router.push

-push(options: RouterOptions, mode?: RouterMode): void
+push(options: RouterOptions): void

 跳转到应用内的指定页面。

 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **参数：**
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 |
-| mode<sup>9+</sup> | [RouterMode](#routermode9) | 否 | 跳转页面使用的模式。 |
+| 参数名  | 类型                            | 必填 | 说明               |
+| ------- | ------------------------------- | ---- | ------------------ |
+| options | [RouterOptions](#routeroptions) | 是   | 跳转页面描述信息。 |


 **示例：**
  ```js
-  // 在当前页面中
-  export default {
-    pushPage() {
-      router.push({
-        url: 'pages/routerpage2/routerpage2',
-        params: {
-  	data1: 'message',
-          data2: {
-            data3: [123, 456, 789]
-  	},
-        },
-      });
-    }
-  }
+router.push({
+  url: 'pages/routerpage2',
+  params: {
+    data1: 'message',
+    data2: {
+      data3: [123, 456, 789]
+    },
+  },
+});
  ```
+## router.push<sup>9+</sup>
+
+push(options: RouterOptions, mode: RouterMode): void
+
+跳转到应用内的指定页面。
+
+**系统能力：** SystemCapability.ArkUI.ArkUI.Full
+
+**参数：**
+| 参数名            | 类型                            | 必填 | 说明                 |
+| ----------------- | ------------------------------- | ---- | -------------------- |
+| options           | [RouterOptions](#routeroptions) | 是   | 跳转页面描述信息。   |
+| mode<sup>9+</sup> | [RouterMode](#routermode9)      | 是   | 跳转页面使用的模式。 |
+
+
+**示例：**
  ```js
-  // 在routerpage2页面中
-  export default {
-    data: {
-      data1: 'default',
-      data2: {
-        data3: [1, 2, 3]
-      }
+router.push({
+  url: 'pages/routerpage2/routerpage2',
+  params: {
+    data1: 'message',
+    data2: {
+      data3: [123, 456, 789]
    },
-    onInit() {
-      console.info('showData1:' + this.data1);
-      console.info('showData3:' + this.data2.data3);
-    }
-  }
+  },
+},router.RouterMode.Standard);
  ```

-
 ## router.replace

 replace(options: RouterOptions, mode?: RouterMode): void
@@ -75,37 +77,44 @@ replace(options: RouterOptions, mode?: RouterMode): void
 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **参数：**
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 |
-| mode<sup>9+</sup> | [RouterMode](#routermode9) | 否 | 跳转页面使用的模式。 |
+| 参数名  | 类型                            | 必填 | 说明               |
+| ------- | ------------------------------- | ---- | ------------------ |
+| options | [RouterOptions](#routeroptions) | 是   | 替换页面描述信息。 |

 **示例：**

  ```js
-  // 在当前页面中
-  export default {
-    replacePage() {
-      router.replace({
-        url: 'pages/detail/detail',
-        params: {
-          data1: 'message',
-        },
-      }, router.RouterMode.Standard);
-    }
-  }
+router.replace({
+  url: 'pages/detail',
+  params: {
+    data1: 'message',
+  },
+});
  ```

+  ## router.replace<sup>9+</sup>
+
+replace(options: RouterOptions, mode: RouterMode): void
+
+用应用内的某个页面替换当前页面，并销毁被替换的页面。
+
+**系统能力：** SystemCapability.ArkUI.ArkUI.Full
+
+**参数：**
+| 参数名            | 类型                            | 必填 | 说明                 |
+| ----------------- | ------------------------------- | ---- | -------------------- |
+| options           | [RouterOptions](#routeroptions) | 是   | 替换页面描述信息。   |
+| mode<sup>9+</sup> | [RouterMode](#routermode9)      | 是   | 跳转页面使用的模式。 |
+
+**示例：**
+
  ```js
-  // 在detail页面中
-  export default {
-    data: {
-      data1: 'default'
-    },
-    onInit() {
-      console.info('showData1:' + this.data1)
-    }
-  }
+router.replace({
+  url: 'pages/detail/detail',
+  params: {
+    data1: 'message',
+  },
+}, router.RouterMode.Standard);
  ```

 ## router.back
@@ -117,58 +126,14 @@ back(options?: RouterOptions ): void
 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **参数：**
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| options | [RouterOptions](#routeroptions) | 是 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页。 |
+| 参数名  | 类型                            | 必填 | 说明                                                         |
+| ------- | ------------------------------- | ---- | ------------------------------------------------------------ |
+| options | [RouterOptions](#routeroptions) | 否   | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页。 |

 **示例：**
-  ```js
-  // index页面
-  export default {    
-    indexPushPage() {        
-      router.push({            
-        url: 'pages/detail/detail',        
-      });        
-    }
-  }
-  ```
-
-  ```js
-  // detail页面
-  export default {    
-    detailPushPage() {        
-      router.push({            
-        url: 'pages/mall/mall',        
-      });    
-    }
-  }
-  ```

  ```js
-  // mall页面通过back，将返回detail页面
-  export default {    
-    mallBackPage() {        
-      router.back();    
-    }
-  }
-  ```
-
-  ```js
-  // detail页面通过back，将返回index页面
-  export default {    
-    defaultBack() {        
-      router.back();    
-    }
-  }
-  ```
-
-  ```js
-  // 通过back，返回到detail页面
-  export default {    
-    backToDetail() {        
-      router.back({uri:'pages/detail/detail'});    
-    }
-  }
+router.back({uri:'pages/detail'});    
  ```

 ## router.clear
@@ -180,12 +145,9 @@ clear(): void
 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **示例：**
+
  ```js
-  export default {    
-    clearPage() {        
-      router.clear();    
-    }
-  }js
+router.clear();    
  ```

 ## router.getLength
@@ -197,18 +159,14 @@ getLength(): string
 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **返回值：**
-| 类型 | 说明 |
-| -------- | -------- |
+| 类型   | 说明                               |
+| ------ | ---------------------------------- |
 | string | 页面数量，页面栈支持最大数值是32。 |

 **示例：**
  ```js
-  export default {     
-    getLength() {        
-      var size = router.getLength();        
-      console.log('pages stack size = ' + size);    
-    }
-  }
+var size = router.getLength();        
+console.log('pages stack size = ' + size);    
  ```

 ## router.getState
@@ -224,28 +182,26 @@ getState(): RouterState
 | 类型                        | 说明           |
 | --------------------------- | -------------- |
 | [RouterState](#routerstate) | 页面状态信息。 |
+**示例：** 
+
+```js
+var page = router.getState();
+console.log('current index = ' + page.index);
+console.log('current name = ' + page.name);
+console.log('current path = ' + page.path);
+```
+
 ## RouterState
-页面状态信息。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。
+页面状态信息。

-| 名称 | 类型 | 说明 |
-| -------- | -------- | -------- |
-| index | number | 表示当前页面在页面栈中的索引。<br/>>&nbsp;![icon-note.gif](public_sys-resources/icon-note.gif)&nbsp;**说明：**<br/>>&nbsp;从栈底到栈顶，index从1开始递增。 |
-| name | string | 表示当前页面的名称，即对应文件名。 |
-| path | string | 表示当前页面的路径。 |
+**系统能力：** SystemCapability.ArkUI.ArkUI.Full。

-**示例：**
-  ```js
-  export default {     
-    getState() {        
-      var page = router.getState();
-      console.log('current index = ' + page.index);
-      console.log('current name = ' + page.name);
-      console.log('current path = ' + page.path);
-    }
-  }
-  ```
+| 名称  | 类型   | 说明                                                         |
+| ----- | ------ | ------------------------------------------------------------ |
+| index | number | 表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。 |
+| name  | string | 表示当前页面的名称，即对应文件名。                           |
+| path  | string | 表示当前页面的路径。                                         |

 ## router.enableAlertBeforeBackPage

@@ -256,26 +212,16 @@ enableAlertBeforeBackPage(options: EnableAlertOptions): void
 **系统能力：** SystemCapability.ArkUI.ArkUI.Full

 **参数：**
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 |
+| 参数名  | 类型                                      | 必填 | 说明               |
+| ------- | ----------------------------------------- | ---- | ------------------ |
+| options | [EnableAlertOptions](#enablealertoptions) | 是   | 文本弹窗信息描述。 |

 **示例：**

-  ```js
-  export default {    
-    enableAlertBeforeBackPage() {        
-      router.enableAlertBeforeBackPage({            
-        message: 'Message Info',            
-        success: function() {                
-          console.log('success');            
-        },            
-        fail: function() {                
-          console.log('fail');            
-        },        
-      });    
-    }
-  }
+  ```js        
+  router.enableAlertBeforeBackPage({            
+    message: 'Message Info'        
+  });    
  ```
 ## EnableAlertOptions

@@ -283,9 +229,9 @@ enableAlertBeforeBackPage(options: EnableAlertOptions): void

 **系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。

-| 名称 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| message | string | 是 | 询问对话框内容。 |
+| 名称    | 类型   | 必填 | 说明             |
+| ------- | ------ | ---- | ---------------- |
+| message | string | 是   | 询问对话框内容。 |

 ## router.disableAlertBeforeBackPage

@@ -297,11 +243,7 @@ disableAlertBeforeBackPage(): void

 **示例：**
  ```js
-  export default {    
-    disableAlertBeforeBackPage() {        
-      router.disableAlertBeforeBackPage();    
-    }
-  }
+router.disableAlertBeforeBackPage();    
  ```

 ##  router.getParams
@@ -320,133 +262,140 @@ getParams(): Object

 **示例：**

- 类Web范示例
-  ```js
-  // 在当前页面中
-  export default {
-    pushPage() {
-      router.push({
-        url: 'pages/detail/detail',
-        params: {
-          data1: 'message',
-        },
-      });
-    }
-  }
-  ```
-  ```js
-  // 在detail页面中
-  export default {
-    onInit() {
-      console.info('showData1:' + router.getParams().data1);
-    }
-  }
-  ```
-
- 声明式示例
-
-  ```ts
-  //通过router.push跳转至目标页携带params参数
-  import router from '@ohos.router'
-  
-  @Entry
-  @Component
-  struct Index {
-    async  routePage() {
-      let options = {
-        url: 'pages/second',
-        params: {
-          text: '这是第一页的值',
-          data: {
-            array: [12, 45, 78]
-          },
-        }
-      }
-      try {
-        await router.push(options)
-      } catch (err) {
-        console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`)
-      }
-    }
-  
-    build() {
-      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
-          Text('这是第一页')
-            .fontSize(50)
-            .fontWeight(FontWeight.Bold)
-        Button() {
-          Text('next page')
-            .fontSize(25)
-            .fontWeight(FontWeight.Bold)
-        }.type(ButtonType.Capsule)
-            .margin({ top: 20 })
-            .backgroundColor('#ccc')
-            .onClick(() => {
-              this.routePage()
-        })
-      }
-      .width('100%')
-      .height('100%')
-    }
-  }
-  ```
-
-  ```ts
-  //在second页面中接收传递过来的参数
-  import router from '@ohos.router'
-  
-  @Entry
-  @Component
-  struct Second {
-    private content: string = "这是第二页"
-    @State text: string = router.getParams()['text']
-    @State data: any = router.getParams()['data']
-    @State secondData : string = ''
-    
-    build() {
-      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
-        Text(`${this.content}`)
-          .fontSize(50)
-          .fontWeight(FontWeight.Bold)
-        Text(this.text)
-          .fontSize(30)
-          .onClick(()=>{
-            this.secondData = (this.data.array[1]).toString()
-          })
-        .margin({top:20})
-        Text('第一页传来的数值' + '  ' + this.secondData)
-          .fontSize(20)
-          .margin({top:20})
-          .backgroundColor('red')      
-      }
-      .width('100%')
-      .height('100%')
-    }
-  }
-  ```
+```
+router.getParams();
+```

 ## RouterOptions

 路由跳转选项。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.FULL。
+**系统能力：** SystemCapability.ArkUI.ArkUI.FULL。

-| 名称 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| url | string | 是 | 表示目标页面的uri，可以用以下两种格式：<br/>-&nbsp;页面绝对路径，由配置文件中pages列表提供，例如：<br/>&nbsp;&nbsp;-&nbsp;pages/index/index<br/>&nbsp;&nbsp;-&nbsp;pages/detail/detail<br/>-&nbsp;特殊值，如果uri的值是"/"，则跳转到首页。 |
-| params | Object | 否 | 跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如this.data1(data1为跳转时params参数中的key值)。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 |
+| 名称   | 类型   | 必填 | 说明                                                         |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| url    | string | 是   | 表示目标页面的uri，可以用以下两种格式：<br/>-&nbsp;页面绝对路径，由配置文件中pages列表提供，例如：<br/>&nbsp;&nbsp;-&nbsp;pages/index/index<br/>&nbsp;&nbsp;-&nbsp;pages/detail/detail<br/>-&nbsp;特殊值，如果uri的值是"/"，则跳转到首页。 |
+| params | Object | 否   | 跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如this.data1(data1为跳转时params参数中的key值)。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 |


-  > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+  > **说明：**
  > 页面路由栈支持的最大Page数量为32。

 ## RouterMode<sup>9+</sup>

 路由跳转模式。

-**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.FULL。
+**系统能力：** SystemCapability.ArkUI.ArkUI.FULL。
+
+| 名称     | 描述                                                         |
+| -------- | ------------------------------------------------------------ |
+| Standard | 标准模式。                                                   |
+| Single   | 单实例模式。<br/>如果目标页面的url在页面栈中已经存在同url页面，离栈顶最近的页面会被移动到栈顶，移动后的页面为新建页。<br/>如目标页面的url在页面栈中不存在同url页面，按标准模式跳转。 |
+
+## 完整示例
+
+### 基于JS扩展的类Web开发范式
+
+```js
+// 在当前页面中
+export default {
+  pushPage() {
+    router.push({
+      url: 'pages/detail/detail',
+      params: {
+        data1: 'message',
+      },
+    });
+  }
+}
+```
+```js
+// 在detail页面中
+export default {
+  onInit() {
+    console.info('showData1:' + router.getParams().data1);
+  }
+}
+```
+
+### 基于TS扩展的声明式开发范式

-| 名称 | 描述 |
-| -------- | -------- |
-| Standard | 标准模式。 |
-| Single | 单实例模式。<br/>如果目标页面的url在页面栈中已经存在同url页面，离栈顶最近的页面会被移动到栈顶，移动后的页面为新建页。<br/>如目标页面的url在页面栈中不存在同url页面，按标准模式跳转。 |
+```ts
+//通过router.push跳转至目标页携带params参数
+import router from '@ohos.router'
+
+@Entry
+@Component
+struct Index {
+  async  routePage() {
+    let options = {
+      url: 'pages/second',
+      params: {
+        text: '这是第一页的值',
+        data: {
+          array: [12, 45, 78]
+        },
+      }
+    }
+    try {
+      await router.push(options)
+    } catch (err) {
+      console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`)
+    }
+  }
+
+  build() {
+    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
+        Text('这是第一页')
+          .fontSize(50)
+          .fontWeight(FontWeight.Bold)
+      Button() {
+        Text('next page')
+          .fontSize(25)
+          .fontWeight(FontWeight.Bold)
+      }.type(ButtonType.Capsule)
+          .margin({ top: 20 })
+          .backgroundColor('#ccc')
+          .onClick(() => {
+            this.routePage()
+      })
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+```ts
+//在second页面中接收传递过来的参数
+import router from '@ohos.router'
+
+@Entry
+@Component
+struct Second {
+  private content: string = "这是第二页"
+  @State text: string = router.getParams()['text']
+  @State data: any = router.getParams()['data']
+  @State secondData : string = ''
+  
+  build() {
+    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
+      Text(`${this.content}`)
+        .fontSize(50)
+        .fontWeight(FontWeight.Bold)
+      Text(this.text)
+        .fontSize(30)
+        .onClick(()=>{
+          this.secondData = (this.data.array[1]).toString()
+        })
+      .margin({top:20})
+      Text('第一页传来的数值' + '  ' + this.secondData)
+        .fontSize(20)
+        .margin({top:20})
+        .backgroundColor('red')      
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
\ No newline at end of file