js-apis-basic-features-ohos-router.md 10.3 KB
Newer Older
K
kukixi 已提交
1 2 3
# 页面路由

> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明**
K
kukixi 已提交
4 5 6
>
> - 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
> - 页面路由需要在页面渲染完成之后才能调用,在onInit和onReady生命周期中页面还处于渲染阶段,禁止调用页面路由方法。
K
kukixi 已提交
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274

## 导入模块

```
import router from '@ohos.router'
```

## 权限列表



## router.push

push(options: RouterOptions): void

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

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

**参数:**
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | options | [RouterOptions](#RouterOptions) | 是 | 跳转页面描述信息。 |


**示例:**
  ```
  // 在当前页面中
  export default {
    pushPage() {
      router.push({
        url: 'pages/routerpage2/routerpage2',
        params: {
  	data1: 'message',
          data2: {
            data3: [123, 456, 789]
  	},
        },
      });
    }
  }
  ```
  ```
  // 在routerpage2页面中
  export default {
    data: {
      data1: 'default',
      data2: {
        data3: [1, 2, 3]
      }
    },
    onInit() {
      console.info('showData1:' + this.data1);
      console.info('showData3:' + this.data2.data3);
    }
  }
  ```


## router.replace

replace(options: RouterOptions): void

用应用内的某个页面替换当前页面,并销毁被替换的页面。

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

**参数:**
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | options | [RouterOptions](#RouterOptions) | 是 | 替换页面描述信息。 |

**示例:**
  ```
  // 在当前页面中
  export default {
    replacePage() {
      router.replace({
        url: 'pages/detail/detail',
        params: {
          data1: 'message',
        },
      });
    }
  }
  ```

  ```
  // 在detail页面中
  export default {
    data: {
      data1: 'default'
    },
    onInit() {
      console.info('showData1:' + this.data1)
    }
  }
  ```

## router.back

back(options?: RouterOptions ): void

返回上一页面或指定的页面。

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

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

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

  ```
  // detail页面
  export default {    
    detailPushPage() {        
      router.push({            
        url: 'pages/mall/mall',        
      });    
    }
  }
  ```

  ```
  // mall页面通过back,将返回detail页面
  export default {    
    mallBackPage() {        
      router.back();    
    }
  }
  ```

  ```
  // detail页面通过back,将返回index页面
  export default {    
    defaultBack() {        
      router.back();    
    }
  }
  ```

  ```
  // 通过back,返回到detail页面
  export default {    
    backToDetail() {        
      router.back({uri:'pages/detail/detail'});    
    }
  }
  ```

## router.clear

clear(): void

清空页面栈中的所有历史页面,仅保留当前页面作为栈顶页面。

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

**示例:**
  ```
  export default {    
    clearPage() {        
      router.clear();    
    }
  }
  ```

## router.getLength

getLength(): string

获取当前在页面栈内的页面数量。

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

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

## router.getState

getState(): RouterState

获取当前页面的状态信息。

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

**返回值:**

| 类型                        | 说明           |
| --------------------------- | -------------- |
| [RouterState](#RouterState) | 页面状态信息。 |
## 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 | 表示当前页面的路径。 |

**示例:**
  ```
  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);
    }
  }
  ```

## router.enableAlertBeforeBackPage

enableAlertBeforeBackPage(options: EnableAlertOptions): void

开启页面返回询问对话框。

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

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

**示例:**

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

K
kukixi 已提交
275 276
页面返回询问对话框选项。

K
kukixi 已提交
277 278
**系统能力:** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Lite。

K
kukixi 已提交
279
| 名称 | 类型 | 必填 | 说明 |
K
kukixi 已提交
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
| -------- | -------- | -------- | -------- |
| message | string | 是 | 询问对话框内容。 |

## router.disableAlertBeforeBackPage

disableAlertBeforeBackPage(): void

禁用页面返回询问对话框。

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

**示例:**
  ```
  export default {    
    disableAlertBeforeBackPage() {        
      router.disableAlertBeforeBackPage();    
    }
  }
  ```

##  router.getParams

getParams(): Object

获取发起跳转的页面往当前页传入的参数。

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

**返回值:**

| 类型   | 说明                               |
| ------ | ---------------------------------- |
| Object | 发起跳转的页面往当前页传入的参数。 |
**示例:**

- 类Web范示例
  ```
  // 在当前页面中
  export default {
    pushPage() {
      router.push({
        url: 'pages/detail/detail',
        params: {
          data1: 'message',
        },
      });
    }
  }
  ```
  ```
  // 在detail页面中
  export default {
    onInit() {
      console.info('showData1:' + router.getParams().data1);
    }
  }
  ```

- 声明式示例

  ```
  //通过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%')
    }
  }
  ```

  ```
  //在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%')
    }
  }
  ```

## RouterOptions

路由跳转选项。

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

| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| 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。