HarmonyOS開發(fā)案例：【Stage模型下Ability的創(chuàng)建和使用】

介紹

基于Stage模型，對(duì)Ability的創(chuàng)建和使用進(jìn)行講解。首先在課程中我們將帶領(lǐng)大家使用DevEco Studio創(chuàng)建一個(gè)Stage模型Ability，并使用UIAbilityContext啟動(dòng)另一個(gè)Ability，然后借助Want，在Ability之間傳遞參數(shù)，最后我們使用HiLog打印Ability的生命周期。效果如圖所示：

相關(guān)概念

• [UIAbility]：UIAbility組件是系統(tǒng)調(diào)度的基本單元，為應(yīng)用提供繪制界面的窗口；一個(gè)UIAbility組件中可以通過多個(gè)頁(yè)面來實(shí)現(xiàn)一個(gè)功能模塊。每一個(gè)UIAbility組件實(shí)例，都對(duì)應(yīng)于一個(gè)最近任務(wù)列表中的任務(wù)。
• [UIAbilityContext]：UIAbilityContext是UIAbility的上下文環(huán)境，繼承自Context，提供UIAbility的相關(guān)配置信息以及操作UIAbility和ServiceExtensionAbility的方法，如啟動(dòng)UIAbility，停止當(dāng)前UIAbilityContext所屬的UIAbility，啟動(dòng)、停止、連接、斷開連接ServiceExtensionAbility等。
• [Want]：Want是對(duì)象間信息傳遞的載體, 可以用于應(yīng)用組件間的信息傳遞。 Want的使用場(chǎng)景之一是作為startAbility的參數(shù), 其包含了指定的啟動(dòng)目標(biāo), 以及啟動(dòng)時(shí)需攜帶的相關(guān)數(shù)據(jù)。
• [HiLog]：HiLog日志系統(tǒng)，讓應(yīng)用可以按照指定類型、指定級(jí)別、指定格式字符串輸出日志內(nèi)容，幫助開發(fā)者了解應(yīng)用的運(yùn)行狀態(tài)，更好地調(diào)試程序。

環(huán)境搭建

軟件要求

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

硬件要求

• 開發(fā)板類型：[潤(rùn)和RK3568開發(fā)板]。
• OpenHarmony系統(tǒng)：3.2 Release。

環(huán)境搭建

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

1. [獲取OpenHarmony系統(tǒng)版本]：標(biāo)準(zhǔn)系統(tǒng)解決方案（二進(jìn)制）。以3.2 Release版本為例：
   
2. 搭建燒錄環(huán)境。
   1. [完成DevEco Device Tool的安裝]
   2. [完成RK3568開發(fā)板的燒錄]
3. 搭建開發(fā)環(huán)境。
   1. 開始前請(qǐng)參考[工具準(zhǔn)備]，完成DevEco Studio的安裝和開發(fā)環(huán)境配置。
   2. 開發(fā)環(huán)境配置完成后，請(qǐng)參考[使用工程向?qū)創(chuàng)建工程（模板選擇“Empty Ability”）。
   3. 工程創(chuàng)建完成后，選擇使用[真機(jī)進(jìn)行調(diào)測(cè)]。
   4. 開發(fā)前請(qǐng)熟悉鴻蒙開發(fā)指導(dǎo)文檔：[qr23.cn/FBD4cY]。

代碼結(jié)構(gòu)解讀

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

├──entry/src/main/ets             // 代碼區(qū)
│  ├──common                      // 公共資源目錄
│  ├──DetailsAbility
│  │  └──DetailsAbility.ts        // 關(guān)聯(lián)詳情頁(yè)面的Ability
│  ├──entryability
│  │  └──EntryAbility.ts          // 程序入口類
│  ├──model
│  │  └──DataModel.ets            // 業(yè)務(wù)邏輯文件
│  ├──pages
│  │  ├──DetailsPage.ets          // 詳情頁(yè)面
│  │  └──NavPage.ets              // 導(dǎo)航頁(yè)面
│  ├──view                        // 自定義組件目錄
│  └──viewmodel                   // 視圖業(yè)務(wù)邏輯文件目錄
└──entry/src/main/resources       // 資源文件目錄

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

創(chuàng)建Ability和Page頁(yè)面

在本篇教程中，我們需要?jiǎng)?chuàng)建兩個(gè)Ability：EntryAbility，DetailsAbility，其中EntryAbility是由工程默認(rèn)創(chuàng)建的，這里我們只講如何創(chuàng)建DetailsAbility。

• 使用DevEco Studio，選中對(duì)應(yīng)的模塊，單擊鼠標(biāo)右鍵，選擇New > Ability，在對(duì)話框中修改名字后，即可創(chuàng)建相關(guān)的Ability。
• 創(chuàng)建完Ability后，需要我們?yōu)锳bility設(shè)置page頁(yè)面，選中pages目錄，單擊鼠標(biāo)右鍵，選擇New > Page，在對(duì)話框中修改名字后，即可創(chuàng)建相關(guān)的Page頁(yè)面。示例代碼如下：

  // DetailsPage.ets
  ...
  @Entry
  @Component
  struct DetailsPage {
    private goodsDetails: GoodsData = new GoodsData();
  
    aboutToAppear() {
      if (position !== undefined) {
        this.goodsDetails = viewModel.loadDetails(position);
      }
    }
  
    build() {
      Column() {
        Scroll() {
          Column() {
            Stack({ alignContent: Alignment.Top }) {
              // 商品圖片預(yù)覽組件
              PreviewerComponent({ goodsImg: this.goodsDetails.goodsImg })
              this.TopBarLayout()
            }
            .height(DetailsPageStyle.TOP_LAYOUT_HEIGHT)
            .width(PERCENTAGE_100)
            .backgroundColor($r('app.color.background1'))
            // 展示商品信息的卡片布局
            this.CardsLayout()
          }.width(PERCENTAGE_100)
        }
        .height(DetailsPageStyle.SCROLL_LAYOUT_WEIGHT)
        .backgroundColor($r('app.color.background'))
        // 底部工具欄
        BottomBarComponent().height(DetailsPageStyle.TOOLBAR_WEIGHT)
      }
      .height(PERCENTAGE_100)
      .width(PERCENTAGE_100)
    }
    ...
  }
  

• 使用windowStage.loadContent為指定Ability設(shè)置相關(guān)的Page頁(yè)面，由于配置流程一樣，我們?cè)谶@里只展示為DetailsAbility配置頁(yè)面的核心代碼：

  // DetailsAbility.ts
  ...
  export default class DetailsAbility extends UIAbility {
  ...
    onWindowStageCreate(windowStage: window.WindowStage): void {
      ...
      windowStage.loadContent('pages/DetailsPage', (err, data) = > {
        if (err.code) {
          hilog.error(DETAIL_ABILITY_DOMAIN, TAG, 'Failed. Cause: %{public}s', JSON.stringify(err) ?? '');
          return;
        }
        hilog.info(DETAIL_ABILITY_DOMAIN, TAG, 'Succeeded. Data: %{public}s', JSON.stringify(data) ?? '');
      });
    }
    ...
  };
  

效果如圖所示：

由于篇幅有限，這里不再詳細(xì)介紹頁(yè)面中的具體布局和布局中的業(yè)務(wù)視圖組件。

UIAbilityContext模塊啟動(dòng)Ability的能力

UIAbilityContext是UIAbility的上下文環(huán)境，繼承自Context，提供UIAbility的相關(guān)配置信息以及操作UIAbility和ServiceExtensionAbility的方法，如啟動(dòng)UIAbility，停止當(dāng)前UIAbilityContext所屬的UIAbility，啟動(dòng)、停止、連接、斷開連接ServiceExtensionAbility等。

在購(gòu)物應(yīng)用中，我們點(diǎn)擊首頁(yè)商品列表中的某一項(xiàng)商品，即可跳轉(zhuǎn)到商品的詳情頁(yè)面。此處使用到UIAbilityContext模塊的啟動(dòng)Ability的能力。關(guān)于[獲取UIAbilityContext的方法]，推薦使用getContext(this)方式來獲取UIAbilityContext。

// HomePage.ets
...
  build() {
    Column() {
      Column() {
        Blank().height(HomePageStyle.BLANK_HEIGHT)
        // Logo和二維碼區(qū)域
        TopBarComponent()
          .padding({
            top: HomePageStyle.PADDING_VERTICAL,
            bottom: HomePageStyle.PADDING_VERTICAL,
            left: HomePageStyle.PADDING_HORIZONTAL,
            right: HomePageStyle.PADDING_HORIZONTAL
          })
        SearchComponent()
        TabsComponent({ tabMenus: this.tabMenus })
        BannerComponent({ bannerList: this.bannerList })
        MenusComponent({ menus: this.menus })
        // 商品列表組件
        GoodsComponent({ goodsList: this.goodsList, startPage: (index) = > {
          let handler = getContext(this) as AppContext.UIAbilityContext;
          viewModel.startDetailsAbility(handler, index);
        } })
      }
      .width(PERCENTAGE_100)
    }
    .height(PERCENTAGE_100)
    .backgroundImage($rawfile('index/index_background.png'), ImageRepeat.NoRepeat)
    .backgroundImageSize(ImageSize.Cover)
  }
 ...

startDetailsAbility方法調(diào)用了UIAbilityContext模塊啟動(dòng)Ability的能力。

// HomeViewModel.ets
... 
  public startDetailsAbility(context: common.UIAbilityContext, index: number): void {
    const want: Want = {
      bundleName: getContext(context).applicationInfo.name,
      abilityName: DETAILS_ABILITY_NAME,
      parameters: {
        position: index
      }
    };
    try {
      context.startAbility(want);
    } catch (error) {
      hilog.error(HOME_PAGE_DOMAIN, TAG, '%{public}s', error);
    }
  }
...

信息傳遞載體Want

[Want]是對(duì)象間信息傳遞的載體, 可以用于應(yīng)用組件間的信息傳遞。Want的使用場(chǎng)景之一是作為startAbility的參數(shù), 其包含了指定的啟動(dòng)目標(biāo), 以及啟動(dòng)時(shí)需攜帶的相關(guān)數(shù)據(jù)。 在購(gòu)物應(yīng)用的EntryAbility中，我們使用startDetailsAbility方法啟動(dòng)DetailsAbility，并在代碼中指定了Want的具體參數(shù)，并使用parameters參數(shù)傳遞商品信息。

在DetailsAbility中通過AppStorage來存儲(chǔ)detailWant對(duì)象。

// DetailsAbility.ts
...
export default class DetailsAbility extends UIAbility {
  onCreate(want, launchParam): void {
    let index: number = want?.parameters?.position;
    AppStorage.SetOrCreate(KEY, index);
    hilog.info(DETAIL_ABILITY_DOMAIN, TAG, '%{public}s', 'Ability onCreate');
  }
  ...
};

在對(duì)應(yīng)的DetailsPage頁(yè)面，使用AppStorage來獲取detailWant對(duì)象，解析detailWant對(duì)象中的商品信息參數(shù)，調(diào)用loadDetails方法來展示商品詳情。

// DetailsPage.ets
...
let viewModel: DetailsViewModel = new DetailsViewModel();
const KEY: string = 'GoodsPosition';
let position = AppStorage.Get< number >(KEY);
...
@Entry
@Component
struct DetailsPage {
  private goodsDetails: GoodsData = new GoodsData();

  aboutToAppear() {
    if (position !== undefined) {
      this.goodsDetails = viewModel.loadDetails(position);
    }
  }
 ...
}

效果如圖所示：

使用HiLog打印生命周期函數(shù)

[HiLog]日志系統(tǒng)可以讓應(yīng)用按照指定類型、指定級(jí)別、指定格式字符串打印日志內(nèi)容，幫助開發(fā)者了解應(yīng)用/服務(wù)的運(yùn)行狀態(tài)，更好地調(diào)試程序。

HiLog提供了debug、info、warn、error以及fatal接口，在購(gòu)物應(yīng)用中，我們使用hilog打印EntryAbility 、DetailsAbility的生命周期。

在打印之前，我們需要了解三個(gè)參數(shù)：

• domain：日志對(duì)應(yīng)的領(lǐng)域標(biāo)識(shí)，范圍是0x0~0xFFFF。建議開發(fā)者在應(yīng)用內(nèi)根據(jù)需要自定義劃分。
• tag：指定日志標(biāo)識(shí)，可以為任意字符串，建議用于標(biāo)識(shí)調(diào)用所在的類或者業(yè)務(wù)行為。
• level：日志級(jí)別。
• format：格式字符串，用于日志的格式化輸出。格式字符串中可以設(shè)置多個(gè)參數(shù)，參數(shù)需要包含參數(shù)類型、隱私標(biāo)識(shí)。隱私標(biāo)識(shí)分為{public}和{private}，缺省為{private}。標(biāo)識(shí){public}的內(nèi)容明文輸出，標(biāo)識(shí){private}的內(nèi)容以過濾回顯。

下面我們?cè)贓ntryAbility中演示如何使用hilog對(duì)象打印Ability的生命周期函數(shù) onBackground，代碼如下：

// EntryAbility.ts
...
export default class EntryAbility extends UIAbility {
  ...
  onBackground(): void {
    // Ability has back to background
    hilog.isLoggable(ENTRY_ABILITY_DOMAIN, TAG, hilog.LogLevel.INFO);
    hilog.info(ENTRY_ABILITY_DOMAIN, TAG, '%{public}s', 'Ability onBackground');
  }
}

此時(shí)我們點(diǎn)擊商品列表中的商品，系統(tǒng)會(huì)打開商品詳情頁(yè)，承載商品列表視圖的EntryAbility將返回到后臺(tái)，系統(tǒng)會(huì)執(zhí)行EntryAbility的onBackground()方法，我們?cè)贒evEco Studio的控制臺(tái)中可以觀察相關(guān)生命周期函數(shù)的變換情況。

審核編輯 黃宇