點擊藍字 ╳ 關注我們

開源項目 OpenHarmony是每個人的 OpenHarmony

馬迪欣

OpenHarmony知識體系工作組

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

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


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


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

而在stage模型里，由于不再有featureAbility，因此無法import featureAbility，進而無法使用featureAbility.startAbility拉起應用，進而使用getContext獲取上下文后，調用startAbility拉起應用。

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


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

除了startAbility外，樣例里使用到的獲取包含bundleName，設備發現deviceManager的相關API都需要按照上述方法進行修改。 修改點3：數據從組件分離，提取到Ability中 在分布式拉起時，需要傳遞當前播放的音樂和音樂的播放進度。在兩種模型里，這些參數都是被設置在wantValue的parameters里，通過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
}

但在接收參數時，FA模型里，是在當前組件的代碼里，通過featureAbility.getWant來獲取參數，如下代碼。

  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模型后，雖然參數傳遞的方式是一致的，但是無法直接在組件UI中獲取參數，而需要先在MainAbility.ts獲取參數want。此時如果要傳遞給組件，有多種方式，這里我是使用的如下方式，即在MainAbility.ts的onCreate和onNewWant里，把want賦值到globalThis里，然后在UI組件里，通過globalThis獲取參數。

    // 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)
}

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

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

新增首頁頁面，和播放列表頁的動畫，不是本文的重點，大家可以參考代碼自行學習。

總結

OpenHarmony的FA模型能力已經停止演進，后續將會增強Stage模型。此次將現有的樣例代碼適配Stage模型，雖然整體代碼修改量不大，但因為慣性思維以及API的變化，期間還是踩了不少坑。我已在OpenHarmony知識體系倉中更新了樣例代碼，歡迎開發者來參考和指正問題，建議新上手OpenHarmony的開發者可以直接學習使用新的Stage模型來開發應用。 前面提到在Stage模型里，ExtensionAbility又被擴展為ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility，這個樣例目前還沒有涉及到，待后續進一步學習，通過ExtensionAbility把音樂播放實現成一個后臺服務，從而實現應用在后臺時也能繼續播放音樂，屆時將持續更新這個應用，也歡迎大家一起共建。 分布式音樂播放器樣例地址

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