UIAbility內和UIAbility間頁(yè)面的跳轉（ArkTS）

介紹

基于Stage模型下的UIAbility開(kāi)發(fā)，實(shí)現UIAbility內和UIAbility間頁(yè)面的跳轉。包含如下功能：

1. UIAbility內頁(yè)面的跳轉。
2. 跳轉到指定UIAbility的首頁(yè)。
3. 跳轉到指定UIAbility的指定頁(yè)面（非首頁(yè)）。

最終效果圖如下：

相關(guān)概念

• [UIAbility組件概述]：UIAbility組件是一種包含UI界面的應用組件，主要用于和用戶(hù)交互。UIAbility組件是系統調度的基本單元，為應用提供繪制界面的窗口。一個(gè)應用可以包含一個(gè)或多個(gè)UIAbility組件。
• [UIAbilityContext]：UIAbilityContext是[UIAbility]的上下文環(huán)境，繼承自[Context]，提供UIAbility的相關(guān)配置信息以及操作UIAbility和ServiceExtensionAbility的方法。
• [頁(yè)面路由]：提供通過(guò)不同的url訪(fǎng)問(wèn)不同的頁(yè)面，包括跳轉到應用內的指定頁(yè)面、用應用內的某個(gè)頁(yè)面替換當前頁(yè)面、返回上一頁(yè)面或指定的頁(yè)面等。
• [Text]：文本組件，用于呈現一段文本信息。
• [Button]：按鈕組件，可快速創(chuàng )建不同樣式的按鈕。

環(huán)境搭建

軟件要求

• [DevEco Studio]版本：DevEco Studio 3.1 Release。
• OpenHarmony SDK版本：API version 9。

硬件要求

• 開(kāi)發(fā)板類(lèi)型：[潤和RK3568開(kāi)發(fā)板]。
• OpenHarmony系統：3.2 Release。

環(huán)境搭建

完成本篇Codelab我們首先要完成開(kāi)發(fā)環(huán)境的搭建，本示例以RK3568開(kāi)發(fā)板為例，參照以下步驟進(jìn)行：

1. [獲取OpenHarmony系統版本]：標準系統解決方案（二進(jìn)制）。以3.2 Release版本為例：
   
2. 搭建燒錄環(huán)境。
   1. [完成DevEco Device Tool的安裝]
   2. [完成RK3568開(kāi)發(fā)板的燒錄](méi)
3. 搭建開(kāi)發(fā)環(huán)境。
   1. 開(kāi)始前請參考[工具準備]，完成DevEco Studio的安裝和開(kāi)發(fā)環(huán)境配置。
   2. 開(kāi)發(fā)環(huán)境配置完成后，請參考[使用工程向導]創(chuàng )建工程（模板選擇“Empty Ability”）。
   3. 工程創(chuàng )建完成后，選擇使用[真機進(jìn)行調測]。
   4. 開(kāi)發(fā)前請熟悉鴻蒙開(kāi)發(fā)指導文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

代碼結構解讀

本篇Codelab只對核心代碼進(jìn)行講解，完整代碼可以直接從gitee獲取。

├──device/src/main/ets              // device模塊的代碼區
│  ├──pages
│  │  ├──Index.ets                  // SecondAbility的Index頁(yè)面
│  │  └──Second.ets                 // SecondAbility的Second頁(yè)面
│  ├──secondability
│  │  └──SecondAbility.ets          // 程序入口類(lèi)
├──device/src/main/resources        // device模塊的資源文件目錄
├──entry/src/main/ets               // entry模塊的代碼區
│  ├──common
│  │  ├──constants
│  │  │  ├──CommonConstants.ets     // 公共常量類(lèi)
│  │  │  └──StyleConstants.ets	    // 樣式常量類(lèi)
│  │  ├──utils
│  │  │  ├──GlobalContext.ets       // 全局變量控制類(lèi)
│  │  │  └──Logger.ets	            // 日志打印類(lèi)
│  ├──entryability
│  │  └──EntryAbility.ts            // 程序入口類(lèi)
│  ├──model
│  │  └──ButtonClickMethod.ets      // 按鈕點(diǎn)擊后調用的方法類(lèi)
│  ├──pages
│  │  ├──Index.ets                  // EntryAbility的Index頁(yè)面
│  │  └──Second.ets                 // EntryAbility的Second頁(yè)面
└──entry/src/main/resources         // entry模塊的資源文件目錄

`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

UIAbility內頁(yè)面的跳轉

entry模塊中，EntryAbility內頁(yè)面的跳轉可以通過(guò)頁(yè)面路由router來(lái)實(shí)現。頁(yè)面路由router根據頁(yè)面url找到目標頁(yè)面，從而實(shí)現跳轉。效果圖如下：

1. 實(shí)現UIAbility內頁(yè)面的跳轉，我們首先需要構建兩個(gè)頁(yè)面。在“Project”窗口，點(diǎn)擊“entry > src > main > ets > pages”，打開(kāi)“Index.ets”文件，可以看到EntryAbility的Index頁(yè)面由一個(gè)Image組件、兩個(gè)Text組件、三個(gè)Button組件組成?！癐ndex.ets”文件的示例代碼如下：

   @Entry
   @Component
   struct Index {
     @State text: string = '';
     @State bottomMargin: string = StyleConstants.MAIN_INDEX_BUTTON_MARGIN_BOTTOM;
   
     build() {
       Column() {
         Image($r('app.media.right'))
           ...
   
         Text($r('app.string.main_index_page_name'))
           ...
   
         // 條件渲染：當text的值不為空時(shí)，顯示該組件
         if (this.text !== '') {
           Text(this.text)
             ...
         }
   
         // 導航到EntryAbility的Second Page
         Button($r('app.string.to_main_second_page_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
   
         // 導航到SecondAbility的Index Page
         Button($r('app.string.to_second_index_page_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
   
         // 導航到SecondAbility的Second Page
         Button($r('app.string.to_second_second_page_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
       }
       ...
     }
   }
   

2. 在“Project”窗口，打開(kāi)“entry > src > main > ets”，右鍵點(diǎn)擊“pages”文件夾，選擇“New > Page”，命名為“Second”?？梢钥吹紼ntryAbility的Second頁(yè)面由一個(gè)Image組件、兩個(gè)Text組件、一個(gè)Button組件組成?！癝econd.ets”文件的示例代碼如下：

   @Entry
   @Component
   struct Second {
     ...
   
     build() {
       Column() {
         Image($r('app.media.left'))
           ...
   
         Text($r('app.string.main_second_page_name'))
           ...
   
         Text(`${this.src}：${this.count}`)
           ...
   
         // 返回到EntryAbility的Index Page
         Button($r('app.string.back_main_index_page_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
       }
       ...
     }
   }
   

3. 從entry模塊的Index頁(yè)面跳轉到Second頁(yè)面，并進(jìn)行數據傳遞，通過(guò)頁(yè)面路由router來(lái)實(shí)現。需要如下幾個(gè)步驟：

   • 給兩個(gè)頁(yè)面導入router模塊。
   • 在EntryAbility的Index頁(yè)面中，點(diǎn)擊“導航到EntryAbility的Second Page”按鈕后，調用ButtonClickMethod類(lèi)中的toEntryAbilitySecond方法，跳轉到EntryAbility的Second頁(yè)面。使用router.pushUrl實(shí)現跳轉，可以通過(guò)params來(lái)向新頁(yè)面傳入參數，示例代碼如下：

   // 導入router模塊
   import router from '@ohos.router';
   
   // 導航到EntryAbility的Second Page
   toEntryAbilitySecond() {
     router.pushUrl({
       url: 'pages/Second',
       params: {
         src: textMessage,
         count: CommonConstants.NUM_VALUES[0]
       }
     });
   }
   

   • Second頁(yè)面通過(guò)router.getParams()方法獲取Index頁(yè)面傳遞過(guò)來(lái)的自定義參數，并用一個(gè)Text文本展示從Index頁(yè)面傳遞過(guò)來(lái)的數據，示例代碼如下：

   @Entry
   @Component
   struct Second {
     ...
     // 獲取Index頁(yè)面傳遞過(guò)來(lái)的自定義參數
     params = router?.getParams();
     @State src: string = this.params == undefined ? '-' : (this.params as Record< string,Object >)['src'] as string;
     @State count: number = this.params == undefined ? 0 : (this.params as Record< string,Object >)['count'] as number;
   
     build() {
       Column() {
         Image($r('app.media.left'))
           ...
   
         Text($r('app.string.main_second_page_name'))
           ...
   
         // 用一個(gè)Text文本展示從Index頁(yè)面傳遞過(guò)來(lái)的數據      
         Text(`${this.src}：${this.count}`)
           ...
   
         // 返回到EntryAbility的Index Page
         Button($r('app.string.back_main_index_page_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
       }
       ...
     }
   }
   

4. 從entry模塊的Second返回到Index頁(yè)面，使用router.back來(lái)實(shí)現。在EntryAbility的Second頁(yè)面中，點(diǎn)擊“返回到EntryAbility的Index Page”按鈕后，返回到EntryAbility的Index頁(yè)面，示例代碼如下：

   // 返回到EntryAbility的Index Page
   router.back();
   

跳轉到指定UIAbility的首頁(yè)

實(shí)現UIAbility間頁(yè)面的跳轉，需要啟動(dòng)另外一個(gè)UIAbility，可以通過(guò)UIAbilityContext的startAbility的方法來(lái)完成。本篇Codelab是用兩個(gè)模塊（entry和device），實(shí)現UIAbility間頁(yè)面的跳轉。跳轉到指定UIAbility的首頁(yè)，效果圖如下：

1. 在本章節中，實(shí)現跳轉到指定UIAbility的首頁(yè)，我們需要新建一個(gè)模塊。在“Project”窗口，右鍵點(diǎn)擊“entry 文件夾”，選擇“New > Module > Empty Ability > Next”，在“Module name”中給新建的模塊命名為“device”，點(diǎn)擊“Next”，在“Ability name”中給新建模塊的Ability命名為“SecondAbility”，點(diǎn)擊“Finish”?？梢钥吹轿募夸浗Y構如下：
   
2. 構建SecondAbility的首頁(yè)。在“Project”窗口，點(diǎn)擊“device > src > main > ets > pages”，打開(kāi)“Index.ets”文件，可以看到SecondAbility的Index頁(yè)面由一個(gè)Image組件、兩個(gè)Text組件、一個(gè)Button組件組成?！癐ndex.ets”文件的示例代碼如下：

   @Entry
   @Component
   struct Index {
     ...
   
     build() {
       Column() {
         Image($r('app.media.left'))
           ...
   
         Text($r('app.string.second_index_page_name'))
           ...
   
         Text(`${this.src}：${this.count}`)
           ...
   
         // 停止SecondAbility自身
         Button($r('app.string.terminate_second_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
       }
       ...
     }
   }
   

3. 從entry模塊的EntryAbility的首頁(yè)，跳轉到SecondAbility的首頁(yè)，即從EntryAbility的Index頁(yè)面跳轉到SecondAbility的Index頁(yè)面。通過(guò)UIAbilityContext的startAbility方法來(lái)實(shí)現。

   • 首先需要在EntryAbility的“Index.ets”文件中獲取UIAbilityContext，示例代碼如下：

     // 獲取UIAbilityContext
     let context = getContext(this) as common.UIAbilityContext;
     

     說(shuō)明： 如果需要使用UIAbilityContext中的方法，需要在對應的頁(yè)面獲取相應的UIAbilityContext。

   • 在EntryAbility的Index頁(yè)面中，點(diǎn)擊“導航到SecondAbility的Index Page”按鈕后，調用ButtonClickMethod類(lèi)中的toSecondAbilityIndex方法，拉起SecondAbility的Index頁(yè)面。使用UIAbilityContext.startAbility來(lái)實(shí)現，可以通過(guò)parameters來(lái)向被拉起方傳遞參數，示例代碼如下：

     // 導航到SecondAbility的Index Page
     toSecondAbilityIndex(context: common.UIAbilityContext) {
       let want: Want = {
         'deviceId': '',
         'bundleName': CommonConstants.BUNDLE_NAME,
         'abilityName': CommonConstants.SECOND_ABILITY_NAME,
         'moduleName': CommonConstants.DEVICE_MODULE_NAME,
         'parameters': {
            src: textMessage,
            count: CommonConstants.NUM_VALUES[1]
          }
       };
       context.startAbility(want).then(() = > {
         Logger.info(CommonConstants.TAG, `start second ability index page succeed with ${JSON.stringify(want)}`);
       }).catch((error: Error) = > {
         Logger.error(CommonConstants.TAG, `start second ability index page failedwith ${error}`);
       });
     }
     

   • 在SecondAbility的Index頁(yè)面，獲取從EntryAbility的Index頁(yè)面傳遞過(guò)來(lái)的自定義參數，并用一個(gè)Text文本展示從Index頁(yè)面傳遞過(guò)來(lái)的數據，示例代碼如下：

     @Entry
     @Component
     struct Index {
       // 獲取從EntryAbility的Index頁(yè)面傳遞過(guò)來(lái)的自定義參數
       secondAbilityWant?: Want = GlobalContext.getContext().getObject('secondAbilityWant');
       @State src: string = this.secondAbilityWant?.parameters?.src as string ?? '-';
       @State count: number = this.secondAbilityWant?.parameters?.count as number ?? 0;
     
       build() {
         Column() {
           Image($r('app.media.left'))
             ...
     
           Text($r('app.string.second_index_page_name'))
             ...
     
           // 用一個(gè)Text文本展示從Index頁(yè)面傳遞過(guò)來(lái)的數據
           Text(`${this.src}：${this.count}`)
             ...
     
           // 停止SecondAbility自身
           Button($r('app.string.terminate_second_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
             ...
         }
         ...
       }
     }
     

4. 在SecondAbility的Index頁(yè)面，點(diǎn)擊“停止SecondAbility自身”按鈕，使用UIAbilityContext.terminateSelf方法手動(dòng)銷(xiāo)毀Ability。示例代碼如下：

   // 停止SecondAbility自身
   terminateSecondAbility(context: common.UIAbilityContext) {
     context.terminateSelf().then(() = > {
       Logger.info(CommonConstants.TAG, 'terminate second ability self succeed');
     }).catch((error: Error) = > {
       Logger.error(CommonConstants.TAG, `terminate second ability self failed with ${error}`);
     });
   }
   

5. 運行時(shí)，需要在DevEco Studio的entry模塊中勾選“Deploy Multi Hap Packages”，如下圖所示：
   

跳轉到指定UIAbility的指定頁(yè)面（非首頁(yè)）

跳轉到指定UIAbility的指定頁(yè)面（非首頁(yè)），本章節以從EntryAbility的Index頁(yè)面跳轉到SecondAbility的Second頁(yè)面為例。只需要在本文檔“跳轉到指定UIAbility的首頁(yè)”章節的基礎上，另外在device模塊中構建一個(gè)Second頁(yè)面。效果圖如下：

1. 構建SecondAbility的Second頁(yè)面。在“Project”窗口，打開(kāi)“device > src > main > ets”，右鍵點(diǎn)擊“pages”文件夾，選擇“New > Page”，命名為“Second”?？梢钥吹轿募夸浗Y構如下：
   
2. 可以看到SecondAbility的Second頁(yè)面由一個(gè)Image組件、兩個(gè)Text組件、一個(gè)Button組件組成?！癝econd.ets”文件的示例代碼如下：

   @Entry
   @Component
   struct Second {
     // 用來(lái)接收parameters參數傳過(guò)來(lái)的值
     secondAbilityWant?: Want = GlobalContext.getContext().getObject('secondAbilityWant');
     @State src: string = this.secondAbilityWant?.parameters?.src as string ?? '-';
     @State count: number = this.secondAbilityWant?.parameters?.count as number ?? 0;
   
     build() {
       Column() {
         Image($r('app.media.left'))
           ...
   
         Text($r('app.string.second_second_page_name'))
           ...
   
         Text(`${this.src}：${this.count}`)
           ...
   
         // 停止SecondAbility自身并返回結果
         Button($r('app.string.terminate_second_for_result_btn_text'), { type: ButtonType.Capsule, stateEffect: true })
           ...
       }
       ...
     }
   }
   

3. 在EntryAbility的Index頁(yè)面中，點(diǎn)擊“導航到SecondAbility的Second Page”按鈕后，調用ButtonClickMethod類(lèi)中的toSecondAbilitySecond方法，拉起SecondAbility的Second頁(yè)面。
   • 使用UIAbilityContext.startAbilityForResult來(lái)實(shí)現，并獲取被拉起側銷(xiāo)毀后的返回結果?？梢酝ㄟ^(guò)parameters來(lái)向被拉起方傳遞參數，示例代碼如下：

     // 導航到SecondAbility的Second Page
     toSecondAbilitySecond(context: common.UIAbilityContext, callback: (abilityResult: common.AbilityResult) = > void) {
       let want: Want = {
         'deviceId': '',
         'bundleName': CommonConstants.BUNDLE_NAME,
         'abilityName': CommonConstants.SECOND_ABILITY_NAME,
         'moduleName': CommonConstants.DEVICE_MODULE_NAME,
         'parameters': {
            url: 'pages/Second',
            src: textMessage,
            count: CommonConstants.NUM_VALUES[2]
          }
       };
     
       // 被拉起側銷(xiāo)毀后，在startAbilityForResult回調中可以獲取到被拉起側銷(xiāo)毀時(shí)傳遞過(guò)來(lái)的AbilityResult
       context.startAbilityForResult(want).then((result) = > {
         callback(result);
         Logger.info(CommonConstants.TAG, `start second ability second page succeed with ${JSON.stringify(want)}`);
       }).catch((error: Error) = > {
         Logger.error(CommonConstants.TAG, `start second ability second page failed with ${error}`);
       });
     }
     

   • 在“Project”窗口，點(diǎn)擊“device > src > main > ets > SecondAbility”，打開(kāi)“SecondAbility.ets”文件，在onWindowStageCreate的生命周期回調函數中獲取拉起方的意圖，展示SecondAbility的指定頁(yè)面到界面。示例代碼如下：

     onWindowStageCreate(windowStage: Window.WindowStage) {
       ...
       let parameters: Record< string, Object > = (GlobalContext.getContext().getObject('secondAbilityWant') as Want)?.parameters as Record< string, Object >;
       let url = parameters?.url ?
         parameters.url as string : 'pages/Index';
       windowStage.loadContent(url, (err, data) = > {
         ...
       });
     }
     

4. 在SecondAbility的Second頁(yè)面，點(diǎn)擊“停止SecondAbility自身并返回結果”按鈕，使用UIAbilityContext.terminateSelfWithResult方法，傳入不同的resultCode和want，手動(dòng)銷(xiāo)毀Ability。成功后發(fā)起拉起側會(huì )收到abilityResult的值。示例代碼如下：

   // 停止SecondAbility自身并返回結果
   terminateSecondAbilityForResult(context: common.UIAbilityContext) {
     let abilityResult: common.AbilityResult = {
       resultCode: CommonConstants.RESULT_CODE,
       want: {
         'deviceId': '',
         'bundleName': CommonConstants.BUNDLE_NAME,
         'abilityName': CommonConstants.SECOND_ABILITY_NAME,
         'moduleName': CommonConstants.DEVICE_MODULE_NAME,
         'parameters': {
            src: returnMessage,
            count: CommonConstants.RESULT_NUM_VALUE
          }
       }
     };
   
     // 停止SecondAbility自身，并將abilityResult返回給startAbilityForResult接口調用方
     context.terminateSelfWithResult(abilityResult).then(() = > {
       Logger.info(CommonConstants.TAG, `terminate second ability self with
         result succeed with ${JSON.stringify(abilityResult)}`);
     }).catch((error: Error) = > {
       Logger.error(CommonConstants.TAG, `terminate second ability self with
         result failed with ${error}`);
     });
   }
   

審核編輯 黃宇