點(diǎn)擊藍(lán)字 ╳ 關(guān)注我們

開(kāi)源項(xiàng)目 OpenHarmony是每個(gè)人的 OpenHarmony

馬迪欣

OpenHarmony知識(shí)體系工作組

以下內(nèi)容來(lái)自嘉賓分享，不代表開(kāi)放原子開(kāi)源基金會(huì)觀點(diǎn) OpenAtom OpenHarmony（以下簡(jiǎn)稱(chēng)“OpenHarmony”）應(yīng)用開(kāi)發(fā)自API 8及其更早版本一直使用的是FA模型進(jìn)行開(kāi)發(fā)。FA模型是Feature Ability的縮寫(xiě)，它和PA（Particle Ability）兩種類(lèi)型是過(guò)往長(zhǎng)期推廣的術(shù)語(yǔ)，深入人心。 然而從API 9開(kāi)始，Ability框架引入了Stage模型作為第二種應(yīng)用框架形態(tài)，Stage模型將Ability分為PageAbility和ExtensionAbility兩大類(lèi)，其中ExtensionAbility又被擴(kuò)展為ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility，以便滿(mǎn)足更多的使用場(chǎng)景。新模型接口中有AbilityStage/WindowStage的概念，這個(gè)Stage本身有舞臺(tái)的意思，寓意是給開(kāi)發(fā)者一個(gè)新的展現(xiàn)舞臺(tái)。Stage模型的設(shè)計(jì)，主要是為了開(kāi)發(fā)者更加方便地開(kāi)發(fā)出分布式環(huán)境下的復(fù)雜應(yīng)用。下表給出了兩種模型在設(shè)計(jì)上的差異： ? 可以看得出來(lái)，新的模型設(shè)計(jì)的主要目標(biāo)是把UI與Ability分離，即從架構(gòu)設(shè)計(jì)層面，規(guī)范開(kāi)發(fā)者編寫(xiě)業(yè)務(wù)邏輯和UI交互的開(kāi)發(fā)方式。通過(guò)數(shù)據(jù)把UI和業(yè)務(wù)邏輯解耦，開(kāi)發(fā)者在Ability中產(chǎn)生數(shù)據(jù)，數(shù)據(jù)傳遞給UI框架后，利用ArkTS聲明式框架的特點(diǎn)，UI=F(state)，通過(guò)數(shù)據(jù)驅(qū)動(dòng)UI變化。這樣的設(shè)計(jì)是為了更好地支持Ability實(shí)現(xiàn)跨端遷移和多端協(xié)同，即數(shù)據(jù)都是存儲(chǔ)在Ability里，繼而通過(guò)數(shù)據(jù)驅(qū)動(dòng)UI展示。此外，F(xiàn)A模型每個(gè)Ability使用一個(gè)VM實(shí)例，而Stage模型整個(gè)進(jìn)程只使用一個(gè)VM實(shí)例，減少進(jìn)程內(nèi)存占用，應(yīng)用內(nèi)狀態(tài)在進(jìn)程內(nèi)共享。 ? 分布式音樂(lè)播放器，是今年上半年我基于OpenHarmony 3.1，參考OpenHarmony JS分布式音樂(lè)播放的Sample代碼，使用ArkTS新寫(xiě)的樣例，當(dāng)時(shí)的主要目的就是為了學(xué)習(xí)ArkTS開(kāi)發(fā)頁(yè)面。此次適配Stage模型后，在潤(rùn)和大禹系列HH-SCDAYU200開(kāi)發(fā)套件上，效果如下圖所示 ? ? 可以看到，此次更新，不僅使用了Stage模型適配，還使用ArkTS增加了一個(gè)音樂(lè)播放器首頁(yè)列表的界面，以及播放時(shí)使用屬性動(dòng)畫(huà)，實(shí)現(xiàn)了一個(gè)播放音樂(lè)時(shí)“唱片旋轉(zhuǎn)”的動(dòng)畫(huà)效果。這次使用Stage模型適配樣例，主要是修改了如下幾個(gè)地方： ?修改點(diǎn)1：代碼目錄的調(diào)整 ? 可以看到，相對(duì)于FA的目錄結(jié)構(gòu)，首先是在最上層目錄里，增加了一個(gè)AppScope目錄，這個(gè)目錄下也是resources下的資源文件，比如string.json，圖片等內(nèi)容。這個(gè)目錄里的資源文件，會(huì)在編譯時(shí)拼接到具體的hap內(nèi)編譯，因此可以把不同hap包里的公用資源提取到這個(gè)目錄下。 此外是增加了AbilityStage.ts這個(gè)文件，它是Hap及加載入口，開(kāi)發(fā)者可以基于它派生完成hap的初始化以及指定多個(gè)實(shí)例開(kāi)發(fā)。AbilityStage可以配合ApplicationContext監(jiān)聽(tīng)/管理進(jìn)程內(nèi)組件的生命周期，感覺(jué)是有點(diǎn)充當(dāng)了FA模型里的app.ets的作用。 其它的文件也有小的變化，如配置文件，pages位置等都有調(diào)整。所以建議還是新建一個(gè)stage模型的工程，然后把之前的代碼逐步復(fù)制過(guò)來(lái)，然后修改問(wèn)題。 ?修改點(diǎn)2：獲取設(shè)備列表，分布式拉起等API變化 由于兩種模型的應(yīng)用上下文不同，導(dǎo)致一些跟上下文相關(guān)的API大都有些變化，在SDK及文檔中有明確標(biāo)明哪些API是stage模型專(zhuān)用的。比如耳熟能詳?shù)膕tartAbility分布式拉起應(yīng)用，在FA模型中是通過(guò)以下代碼實(shí)現(xiàn)：

import featureAbility from '@ohos.ability.featureAbility';


   featureAbility.startAbility({
      want: wantValue
    }).then((data) => {
      CommonLog.info('startAbilityContinuation finished, ' + JSON.stringify(data))


      //拉起后，自我關(guān)閉
      featureAbility.terminateSelf((error) => {
        CommonLog.info('startAbilityContinuation terminateSelf finished, error=' + JSON.stringify(error))
      })
    }).catch((error) => {
      CommonLog.info('startAbilityContinuation error ' + JSON.stringify(error))
})

而在stage模型里，由于不再有featureAbility，因此無(wú)法import featureAbility，進(jìn)而無(wú)法使用featureAbility.startAbility拉起應(yīng)用，進(jìn)而使用getContext獲取上下文后，調(diào)用startAbility拉起應(yīng)用。

    getContext(this).startAbility(want).then((data) => {
      CommonLog.info('startAbilityContinuation finished, ' + JSON.stringify(data))


      //自我關(guān)閉
      getContext(this).terminateSelf((error) => {
        CommonLog.info('startAbilityContinuation terminateSelf finished, error=' + JSON.stringify(error))
      })
    }).catch((error) => {
      CommonLog.info('startAbilityContinuation error ' + JSON.stringify(error))
})

除了startAbility外，樣例里使用到的獲取包含bundleName，設(shè)備發(fā)現(xiàn)deviceManager的相關(guān)API都需要按照上述方法進(jìn)行修改。 修改點(diǎn)3：數(shù)據(jù)從組件分離，提取到Ability中 在分布式拉起時(shí)，需要傳遞當(dāng)前播放的音樂(lè)和音樂(lè)的播放進(jìn)度。在兩種模型里，這些參數(shù)都是被設(shè)置在wantValue的parameters里，通過(guò)startAbility傳出去。

   let params = {
      index: this.playerManager.getCurrentMusicIndex(),
      seekTo: this.playerManager.getCurrentTimeMs(),
      isPlaying: this.isPlaying
    }
    let wantValue = {
      bundleName: this.bundleName,
      abilityName: 'com.madixin.music.MainAbility',
      deviceId: remoteDevice.deviceId,
      parameters: params
}

但在接收參數(shù)時(shí)，F(xiàn)A模型里，是在當(dāng)前組件的代碼里，通過(guò)featureAbility.getWant來(lái)獲取參數(shù)，如下代碼。

  featureAbility.getWant((error, want) => {
      CommonLog.info('restoreFromWant featureAbility.getWant=' + JSON.stringify(want))
      let status = want.parameters
      if (status != null && status.index != null) {
        this.playerManager.playSpecifyMusic(status.seekTo, status.index)
        this.isPlaying = true
        this.playAnimation()
      }
})

而使用Stage模型后，雖然參數(shù)傳遞的方式是一致的，但是無(wú)法直接在組件UI中獲取參數(shù)，而需要先在MainAbility.ts獲取參數(shù)want。此時(shí)如果要傳遞給組件，有多種方式，這里我是使用的如下方式，即在MainAbility.ts的onCreate和onNewWant里，把want賦值到globalThis里，然后在UI組件里，通過(guò)globalThis獲取參數(shù)。

    // MainAbility.ts
    onNewWant(want, launchParams) {
        globalThis.newWant = want
        hilog.info(0x0000, 'MyOpenHarmonyPlayer', '%{public}s', 'onNewWant launchParam:' + JSON.stringify(launchParams) ?? '');
    }


    onCreate(want, launchParam) {
        globalThis.newWant = want
        hilog.info(0x0000, 'MyOpenHarmonyPlayer', '%{public}s', 'want param:' + JSON.stringify(want) ?? '');
        hilog.info(0x0000, 'MyOpenHarmonyPlayer', '%{public}s', 'launchParam:' + JSON.stringify(launchParam) ?? '');
    }
    
    // index.ets
    let newWant = globalThis.newWant
    CommonLog.info("aboutToAppear newWant:" + JSON.stringify(newWant))
    if (newWant !== null && newWant.parameters.hasOwnProperty("seekTo")) {
      this.playerManager.playSpecifyMusic(newWant.parameters.seekTo, newWant.parameters.index)
}

另外，了解到還有一種方式傳遞數(shù)據(jù)是使用AppStorage來(lái)關(guān)聯(lián)，比如在MainAbility.ts里使用AppStorage.SetOrCreate傳入數(shù)據(jù)，在UI組件里，使用@StorageLink標(biāo)簽修飾變量來(lái)獲取數(shù)據(jù)。 除以上三點(diǎn)修改外，還有兩點(diǎn)值得說(shuō)明下 首先是因OpenHarmony 3.2后分布式能力限制智能系統(tǒng)應(yīng)用使用，需要提升apl等級(jí)：找到所使用API版本對(duì)應(yīng)toolchains>版本號(hào)>lib>UnsgnedReleasedProfileTemplate.json，更改 "apl": "normal"為 "apl": "system_core"。 其次是API 9以后區(qū)分了public-SDK和Full SDK。DevEco Studio默認(rèn)下載的是public-SDK，它不包含系統(tǒng)應(yīng)用所需要的高權(quán)限API。當(dāng)我們import deviceManager from '@ohos.distributedHardware.deviceManager'時(shí)，會(huì)發(fā)現(xiàn)里面只有一個(gè)空的接口，沒(méi)有任何方法。雖然這不影響功能，但代碼中必須使用@ts-ignore忽略typescript的告警，而且沒(méi)有語(yǔ)法提示。此時(shí)，需要使用full-SDK替換。 相關(guān)文檔請(qǐng)參考

https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/full-sdk-switch-guide.md

新增首頁(yè)頁(yè)面，和播放列表頁(yè)的動(dòng)畫(huà)，不是本文的重點(diǎn)，大家可以參考代碼自行學(xué)習(xí)。

總結(jié)

OpenHarmony的FA模型能力已經(jīng)停止演進(jìn)，后續(xù)將會(huì)增強(qiáng)Stage模型。此次將現(xiàn)有的樣例代碼適配Stage模型，雖然整體代碼修改量不大，但因?yàn)閼T性思維以及API的變化，期間還是踩了不少坑。我已在OpenHarmony知識(shí)體系倉(cāng)中更新了樣例代碼，歡迎開(kāi)發(fā)者來(lái)參考和指正問(wèn)題，建議新上手OpenHarmony的開(kāi)發(fā)者可以直接學(xué)習(xí)使用新的Stage模型來(lái)開(kāi)發(fā)應(yīng)用。 前面提到在Stage模型里，ExtensionAbility又被擴(kuò)展為ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility，這個(gè)樣例目前還沒(méi)有涉及到，待后續(xù)進(jìn)一步學(xué)習(xí)，通過(guò)ExtensionAbility把音樂(lè)播放實(shí)現(xiàn)成一個(gè)后臺(tái)服務(wù)，從而實(shí)現(xiàn)應(yīng)用在后臺(tái)時(shí)也能繼續(xù)播放音樂(lè)，屆時(shí)將持續(xù)更新這個(gè)應(yīng)用，也歡迎大家一起共建。 分布式音樂(lè)播放器樣例地址

https://growing.openharmony.cn/mainPlay/detail?sampleId=3742